Gwirian

Gerenciamento de Testes moderno e de código aberto com integração ao servidor MCP

Documentação

Gwirian

Uma plataforma moderna de gerenciamento de features BDD (Behavior-Driven Development) que ajuda equipes a colaborar, organizar e acompanhar suas funcionalidades de software, da concepção à execução.

O Gwirian capacita equipes de desenvolvimento a gerenciar suas features BDD com facilidade. Crie e organize features, defina cenários, acompanhe execuções e colabore com sua equipe—tudo em uma plataforma bonita, rápida e intuitiva. Construída com tecnologias web modernas para uma experiência perfeita.

O que o Gwirian Faz

Organize seu Fluxo de Trabalho BDD

Gerencie todos os seus recursos de Desenvolvimento Orientado por Comportamento em um só lugar. Crie features, defina cenários com etapas Given/When/Then e acompanhe o status de execução em vários projetos. Mantenha sua equipe alinhada com uma visão centralizada de suas especificações BDD.

Organização Multi-Workspace

Organize seu trabalho em workspaces, cada um contendo vários projetos. Perfeito para equipes que gerenciam múltiplos produtos ou clientes. Membros do workspace podem ter diferentes papéis (owner, admin, viewer) com controle de acesso granular.

Busca e Descoberta Poderosas

Encontre features instantaneamente com busca em texto completo powered by Elasticsearch. Adicione tags às suas features e cenários para melhor organização e filtragem rápida. Nunca perca o rastro de especificações importantes novamente.

Colaboração em Equipe

Convide membros da equipe para workspaces e projetos com controle de acesso baseado em papéis. Gerencie associações de projetos, acompanhe quem está trabalhando no quê e mantenha uma clara responsabilidade sobre features e cenários.

Acompanhamento de Execuções

Monitore execuções de cenários para entender quais features foram testadas e seu status atual (pendente, aprovado, reprovado). Mantenha sua equipe informada sobre o progresso de suas especificações BDD com histórico detalhado de execuções.

Seguro e Auditável

Autenticação sem senha via magic link por e-mail. O histórico de login garante que o trabalho da sua equipe seja seguro e auditável. Saiba quem acessou o quê e quando.

Moderno e Rápido

Experimente uma interface extremamente rápida construída com as tecnologias web mais recentes. A navegação usa htmx, então links e atalhos atualizam apenas o conteúdo principal—sem recarregamentos completos de página. Desfrute de uma UI reativa e fluida com Alpine.js, estilização elegante com Tailwind CSS v4 e uma paleta de comandos global (Ctrl+K / ⌘K) para busca e navegação rápida. O app é keyboard-first: use G seguido de uma letra para navegação entre projetos (estilo Linear) e ? para ver todos os atalhos.

Principais Recursos

Workspaces: Organize equipes e projetos em workspaces separados
Projetos: Agrupe features relacionadas dentro de um workspace
Features: Defina features BDD com descrições e backgrounds
Cenários: Crie cenários com estrutura Given/When/Then
Etapas: Defina etapas detalhadas para cada cenário
Execuções: Acompanhe o status e o histórico de execução dos cenários
Tags: Organize features e cenários com tags flexíveis
Busca: Busca em texto completo powered by Elasticsearch; busca instantânea pela paleta de comandos global (Ctrl+K)
Paleta de comandos global: Um atalho (Ctrl+K) para busca, navegação e ações—sem recarregamentos completos de página
Navegação keyboard-first: Navegação G (G + letra) e sobreposição de atalhos (?); feature anterior/próxima (G P / G N)
Acesso via API: Tokens de API com escopo de workspace para acesso programático
Integração MCP: Servidor Model Context Protocol para integração com assistentes de IA

Visão Geral da Arquitetura

Modelo de Dados

O Gwirian segue uma estrutura hierárquica:

Workspace
  ├── Workspace Members (users with roles)
  └── Projects
      ├── Project Members (email-based access)
      └── Features
          ├── Tags
          └── Scenarios
              ├── Steps (Given/When/Then)
              └── Scenario Executions

Autenticação

Magic Links: Autenticação sem senha via links de e-mail (código de 6 caracteres)
Sessões: Gerenciamento de sessão com suporte a banco de dados e expiração
Tokens de API: Tokens com escopo de workspace para acesso programático

Autorização

CanCanCan: Autorização baseada em papéis em toda a aplicação
Papéis do Workspace: Owner, Admin, Viewer
Acesso a Projetos: Associação a projetos baseada em e-mail, com papéis

Jobs em Segundo Plano

Solid Queue: Fila de jobs com suporte a banco de dados (sem necessidade de Redis)
Solid Cache: Cache com suporte a banco de dados
Solid Cable: Action Cable com suporte a banco de dados

Stack Técnica

Tecnologias Principais

Ruby 4.0.0: Runtime Ruby moderno
Rails 8.0: Framework Rails mais recente
SQLite3: Banco de dados padrão (facilmente trocável por PostgreSQL/MySQL)
Tailwind CSS v4: Framework CSS utility-first
Alpine.js: Framework JavaScript leve para interatividade
htmx: Interações HTML dinâmicas sem recarregamentos de página
ViewComponent: Componentes de UI reutilizáveis

Gems Principais

Elasticsearch: Busca em texto completo e indexação
CanCanCan: Framework de autorização
acts-as-taggable-on: Sistema flexível de tags
acts_as_list: Suporte a listas ordenáveis
Pagy: Paginação rápida e eficiente
Solid Queue/Cache/Cable: Jobs em segundo plano, cache e WebSockets com suporte a banco de dados
Kamal: Implantação sem downtime
Thruster: Cache/compressão de assets HTTP para Puma

Ferramentas de Desenvolvimento

RSpec: Framework de testes
FactoryBot: Geração de dados de teste
Rubocop: Aplicação de estilo de código
Brakeman: Scanner de vulnerabilidades de segurança
Capybara: Testes de sistema

Requisitos

Ruby 4.0.0 (veja .ruby-version)
Docker e Docker Compose (para Elasticsearch e Mailhog)
Bundler (gerenciador de gems Ruby)
Node.js (para compilação do Tailwind CSS)

Início Rápido

Comece a usar em minutos:

# 1. Clone the repository
git clone https://github.com/TheAcmada/gwirian.git
cd gwirian

# 2. Install dependencies
bundle install

# 3. Start external services (Elasticsearch, Mailhog)
docker-compose up -d

# 4. Setup database
bin/rails db:create db:migrate db:seed

# 5. Reindex Elasticsearch
bin/rails elasticsearch:reindex

# 6. Start the development server
bin/dev

Acesse http://localhost:3000 e entre com seu endereço de e-mail. Você receberá um código de magic link por e-mail (ou verifique o console do navegador/cabeçalhos de resposta em desenvolvimento para obter o código).

Nota: O servidor de desenvolvimento executa tanto o servidor Rails quanto o watcher do Tailwind CSS via Procfile.dev. Certifique-se de que o Elasticsearch esteja rodando antes de reindexar.

Desenvolvimento

Iniciando o Servidor

O comando bin/dev inicia tanto o servidor Rails quanto o watcher do Tailwind CSS:

bin/dev

Isso usa Procfile.dev, que executa:

web: servidor Rails (porta 3000)
css: watcher do Tailwind CSS para compilação automática

Fluxo de Trabalho de Desenvolvimento

Tailwind CSS: Compilado automaticamente via bin/rails tailwindcss:watch (incluído em bin/dev)
htmx e Alpine.js: Incluídos via /public/js/htmx.min.js e /public/js/alpinejs.min.js
Layout principal: app/views/layouts/application.html.erb
Componentes ViewComponent: Localizados em app/components/
Models: Localizados em app/models/
Controllers: Localizados em app/controllers/

Gerenciamento do Banco de Dados

# Create database
bin/rails db:create

# Run migrations
bin/rails db:migrate

# Reset database (drop, create, migrate, seed)
bin/rails db:reset

# Load seed data
bin/rails db:seed

Gerenciamento do Elasticsearch

# Reindex all features and scenario executions
bin/rails elasticsearch:reindex

Esta tarefa irá:

Excluir índices existentes do Elasticsearch (se houver)
Criar novos índices com configurações e mapeamentos adequados
Importar todas as features e execuções de cenários para os índices

Nota: Certifique-se de que o Elasticsearch esteja rodando antes de executar este comando (docker-compose up -d).

Testes

O Gwirian usa tanto o RSpec quanto o framework de testes integrado do Rails:

# Run all tests
bundle exec rspec && bin/rails test

# Run only RSpec tests
bundle exec rspec

# Run only Rails tests
bin/rails test

# Run a specific test file
bundle exec rspec spec/path/to/file_spec.rb
bin/rails test test/path/to/file_test.rb

# Run tests in parallel (if configured)
bundle exec rspec --parallel

Dados de Teste

FactoryBot: Usado para gerar dados de teste no RSpec
Fixtures: Usados para testes do Rails

Serviços Externos

Este aplicativo depende de serviços externos para funcionalidade completa, que podem ser iniciados usando Docker Compose:

Serviços

Elasticsearch (porta 9200): Busca em texto completo e indexação
- Disponível em http://localhost:9200
- Verificação de saúde: curl http://localhost:9200
Mailhog (portas 8025, 1025): Teste de e-mail local
- Interface web: http://localhost:8025
- SMTP: localhost:1025

Iniciando os Serviços

# Start all services in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Servidor MCP

O Gwirian inclui um servidor Model Context Protocol (MCP) que permite que assistentes de IA e outras ferramentas interajam programaticamente com suas features BDD, cenários e execuções.

Para configuração completa, instruções de uso e ferramentas disponíveis, consulte o Guia de Configuração do Cliente MCP.

Implantação

O Gwirian usa Kamal para implantações sem downtime. Kamal fornece um fluxo de trabalho de implantação simples, baseado em Docker, que funciona com qualquer provedor de hospedagem.

Pré-requisitos

Docker instalado no seu servidor
Acesso SSH ao seu servidor
Nome de domínio configurado

Guia de Implantação

Para um passo a passo completo, consulte o guia de implantação Kamal ou o guia de implantação Docker.

Implantação Rápida

# Deploy to production
bin/kamal deploy

# Deploy with specific environment
bin/kamal deploy -d production

# View deployment configuration
cat config/deploy.yml

Recursos de Implantação

Implantações sem downtime
Verificações de saúde automáticas
Suporte a rollback
Configurações específicas por ambiente
Serviço Elasticsearch incluído na implantação

Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto (veja .env.example como referência):

# Database
DATABASE_URL=sqlite3:db/development.sqlite3

# Elasticsearch
ELASTICSEARCH_URL=http://localhost:9200

# Application
SECRET_KEY_BASE=your_secret_key_here
RAILS_ENV=development

Arquivos de Configuração

Banco de dados: config/database.yml
Elasticsearch: config/initializers/elasticsearch.rb
Rotas: config/routes.rb
Aplicação: config/application.rb
Ambientes: config/environments/

Gwirian

Documentação

Gwirian

Sumário

O que o Gwirian Faz

Organize seu Fluxo de Trabalho BDD

Organização Multi-Workspace

Busca e Descoberta Poderosas

Colaboração em Equipe

Acompanhamento de Execuções

Seguro e Auditável

Moderno e Rápido

Principais Recursos

Visão Geral da Arquitetura

Modelo de Dados

Autenticação

Autorização

Jobs em Segundo Plano

Stack Técnica

Tecnologias Principais

Gems Principais

Ferramentas de Desenvolvimento

Requisitos

Início Rápido

Desenvolvimento

Iniciando o Servidor

Fluxo de Trabalho de Desenvolvimento

Gerenciamento do Banco de Dados

Gerenciamento do Elasticsearch

Testes

Dados de Teste

Serviços Externos

Serviços

Iniciando os Serviços

Servidor MCP

Implantação

Pré-requisitos

Guia de Implantação

Implantação Rápida

Recursos de Implantação

Configuração

Variáveis de Ambiente

Arquivos de Configuração

Recursos

Documentação

Documentação do Projeto

Comunidade