Gwirian

Gestión moderna de pruebas de código abierto con integración de servidor MCP

Documentación

Gwirian

Una plataforma moderna de gestión de funciones BDD (Desarrollo Guiado por Comportamiento) que ayuda a los equipos a colaborar, organizar y realizar seguimiento de sus funciones de software desde la concepción hasta la ejecución.

Gwirian permite a los equipos de desarrollo gestionar sus funciones BDD con facilidad. Crea y organiza funciones, define escenarios, realiza seguimiento de ejecuciones y colabora con tu equipo, todo en una plataforma hermosa, rápida e intuitiva. Construida con tecnologías web modernas para una experiencia sin interrupciones.

Qué Hace Gwirian

Organiza tu Flujo de Trabajo BDD

Gestiona todas tus funciones de Desarrollo Guiado por Comportamiento en un solo lugar. Crea funciones, define escenarios con pasos Dado/Cuando/Entonces y realiza seguimiento de su estado de ejecución en múltiples proyectos. Mantén a tu equipo alineado con una vista centralizada de tus especificaciones BDD.

Organización Multi-Espacio de Trabajo

Organiza tu trabajo en espacios de trabajo, cada uno con múltiples proyectos. Perfecto para equipos que gestionan múltiples productos o clientes. Los miembros del espacio de trabajo pueden tener diferentes roles (propietario, administrador, visor) con control de acceso detallado.

Búsqueda y Descubrimiento Potentes

Encuentra funciones al instante con búsqueda de texto completo impulsada por Elasticsearch. Etiqueta tus funciones y escenarios para una mejor organización y filtrado rápido. Nunca pierdas de vista especificaciones importantes.

Colaboración en Equipo

Invita a miembros del equipo a espacios de trabajo y proyectos con control de acceso basado en roles. Gestiona membresías de proyectos, realiza seguimiento de quién trabaja en qué y mantén una propiedad clara de funciones y escenarios.

Seguimiento de Ejecuciones

Monitorea ejecuciones de escenarios para entender qué funciones han sido probadas y su estado actual (pendiente, aprobado, fallido). Mantén a tu equipo informado sobre el progreso de tus especificaciones BDD con historial detallado de ejecuciones.

Seguro y Auditable

Autenticación sin contraseña mediante enlaces mágicos por correo electrónico. El seguimiento del historial de inicio de sesión garantiza que el trabajo de tu equipo sea seguro y auditable. Sabrás quién accedió a qué y cuándo.

Moderno y Rápido

Experimenta una interfaz ultrarrápida construida con las últimas tecnologías web. La navegación utiliza htmx para que los enlaces y atajos actualicen solo el contenido principal, sin recargas completas de página. Disfruta de una interfaz fluida y reactiva con Alpine.js, estilos hermosos con Tailwind CSS v4 y una paleta de comandos global (Ctrl+K / ⌘K) para búsqueda y navegación rápida. La aplicación está diseñada para el teclado: usa G seguido de una letra para navegación de proyectos (estilo Linear) y ? para ver todos los atajos.

Características Clave

Espacios de Trabajo: Organiza equipos y proyectos en espacios de trabajo separados
Proyectos: Agrupa funciones relacionadas dentro de un espacio de trabajo
Funciones: Define funciones BDD con descripciones y antecedentes
Escenarios: Crea escenarios con estructura Dado/Cuando/Entonces
Pasos: Define pasos detallados para cada escenario
Ejecuciones: Realiza seguimiento del estado y historial de ejecución de escenarios
Etiquetas: Organiza funciones y escenarios con etiquetado flexible
Búsqueda: Búsqueda de texto completo impulsada por Elasticsearch; búsqueda instantánea desde la paleta de comandos global (Ctrl+K)
Paleta de comandos global: Un atajo (Ctrl+K) para búsqueda, navegación y acciones, sin recargas completas de página
Navegación con teclado: Navegación G (G + letra) y superposición de atajos (?); función anterior/siguiente (G P / G N)
Acceso API: Tokens API con ámbito de espacio de trabajo para acceso programático
Integración MCP: Servidor de Protocolo de Contexto de Modelo para integración con asistentes de IA

Resumen de Arquitectura

Modelo de Datos

Gwirian sigue una estructura jerárquica:

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

Autenticación

Enlaces Mágicos: Autenticación sin contraseña mediante enlaces por correo electrónico (código de 6 caracteres)
Sesiones: Gestión de sesiones respaldada por base de datos con expiración
Tokens API: Tokens con ámbito de espacio de trabajo para acceso programático

Autorización

CanCanCan: Autorización basada en roles en toda la aplicación
Roles de Espacio de Trabajo: Propietario, Administrador, Visor
Acceso a Proyectos: Membresía de proyectos basada en correo electrónico con roles

Trabajos en Segundo Plano

Solid Queue: Cola de trabajos respaldada por base de datos (sin necesidad de Redis)
Solid Cache: Caché respaldada por base de datos
Solid Cable: Action Cable respaldado por base de datos

Stack Tecnológico

Tecnologías Principales

Ruby 4.0.0: Runtime moderno de Ruby
Rails 8.0: Último framework de Rails
SQLite3: Base de datos predeterminada (fácilmente cambiable a PostgreSQL/MySQL)
Tailwind CSS v4: Framework CSS de utilidades primero
Alpine.js: Framework JavaScript ligero para interactividad
htmx: Interacciones HTML dinámicas sin recargas de página
ViewComponent: Componentes de interfaz reutilizables

Gemas Clave

Elasticsearch: Búsqueda de texto completo e indexación
CanCanCan: Framework de autorización
acts-as-taggable-on: Sistema de etiquetado flexible
acts_as_list: Soporte de listas ordenables
Pagy: Paginación rápida y eficiente
Solid Queue/Cache/Cable: Trabajos en segundo plano, caché y WebSockets respaldados por base de datos
Kamal: Despliegue sin tiempo de inactividad
Thruster: Caché/compresión de activos HTTP para Puma

Herramientas de Desarrollo

RSpec: Framework de pruebas
FactoryBot: Generación de datos de prueba
Rubocop: Aplicación de estilo de código
Brakeman: Escáner de vulnerabilidades de seguridad
Capybara: Pruebas de sistema

Requisitos

Ruby 4.0.0 (ver .ruby-version)
Docker y Docker Compose (para Elasticsearch y Mailhog)
Bundler (gestor de gemas de Ruby)
Node.js (para compilación de Tailwind CSS)

Inicio Rápido

Ponte en marcha en 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

Visita http://localhost:3000 e inicia sesión con tu dirección de correo electrónico. Recibirás un código de enlace mágico por correo electrónico (o revisa la consola del navegador/encabezados de respuesta en desarrollo para obtener el código).

Nota: El servidor de desarrollo ejecuta tanto el servidor Rails como el observador de Tailwind CSS mediante Procfile.dev. Asegúrate de que Elasticsearch esté en ejecución antes de reindexar.

Desarrollo

Iniciar el Servidor

El comando bin/dev inicia tanto el servidor Rails como el observador de Tailwind CSS:

bin/dev

Esto utiliza Procfile.dev que ejecuta:

web: Servidor Rails (puerto 3000)
css: Observador de Tailwind CSS para compilación automática

Flujo de Trabajo de Desarrollo

Tailwind CSS: Compilado automáticamente mediante bin/rails tailwindcss:watch (incluido en bin/dev)
htmx y Alpine.js: Incluidos mediante /public/js/htmx.min.js y /public/js/alpinejs.min.js
Diseño principal: app/views/layouts/application.html.erb
Componentes ViewComponent: Ubicados en app/components/
Modelos: Ubicados en app/models/
Controladores: Ubicados en app/controllers/

Gestión de Base de Datos

# 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

Gestión de Elasticsearch

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

Esta tarea:

Eliminará los índices existentes de Elasticsearch (si existen)
Creará nuevos índices con configuraciones y mapeos adecuados
Importará todas las funciones y ejecuciones de escenarios en los índices

Nota: Asegúrate de que Elasticsearch esté en ejecución antes de ejecutar este comando (docker-compose up -d).

Pruebas

Gwirian utiliza tanto RSpec como el framework de pruebas integrado de 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

Datos de Prueba

FactoryBot: Se utiliza para generar datos de prueba en RSpec
Fixtures: Se utilizan para pruebas de Rails

Servicios Externos

Esta aplicación depende de servicios externos para su funcionalidad completa, que se pueden iniciar usando Docker Compose:

Servicios

Elasticsearch (puerto 9200): Búsqueda de texto completo e indexación
- Disponible en http://localhost:9200
- Verificación de salud: curl http://localhost:9200
Mailhog (puertos 8025, 1025): Pruebas de correo electrónico local
- Interfaz web: http://localhost:8025
- SMTP: localhost:1025

Iniciar Servicios

# 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

Gwirian incluye un servidor de Protocolo de Contexto de Modelo (MCP) que permite a asistentes de IA y otras herramientas interactuar programáticamente con tus funciones BDD, escenarios y ejecuciones.

Para configuración completa, instrucciones de uso y herramientas disponibles, consulta la Guía de Configuración del Cliente MCP.

Despliegue

Gwirian utiliza Kamal para despliegues sin tiempo de inactividad. Kamal proporciona un flujo de trabajo de despliegue simple basado en Docker que funciona con cualquier proveedor de hosting.

Requisitos Previos

Docker instalado en tu servidor
Acceso SSH a tu servidor
Nombre de dominio configurado

Guía de Despliegue

Para un recorrido completo, consulta la guía de despliegue de Kamal o la guía de despliegue de Docker.

Despliegue Rápido

# Deploy to production
bin/kamal deploy

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

# View deployment configuration
cat config/deploy.yml

Características de Despliegue

Despliegues sin tiempo de inactividad
Verificaciones de salud automáticas
Soporte de reversión
Configuraciones específicas por entorno
Servicio de Elasticsearch incluido en el despliegue

Configuración

Variables de Entorno

Crea un archivo .env en la raíz del proyecto (ver .env.example como referencia):

# Database
DATABASE_URL=sqlite3:db/development.sqlite3

# Elasticsearch
ELASTICSEARCH_URL=http://localhost:9200

# Application
SECRET_KEY_BASE=your_secret_key_here
RAILS_ENV=development

Archivos de Configuración

Base de datos: config/database.yml
Elasticsearch: config/initializers/elasticsearch.rb
Rutas: config/routes.rb
Aplicación: config/application.rb
Entornos: config/environments/

Gwirian

Documentación

Gwirian

Tabla de Contenidos

Qué Hace Gwirian

Organiza tu Flujo de Trabajo BDD

Organización Multi-Espacio de Trabajo

Búsqueda y Descubrimiento Potentes

Colaboración en Equipo

Seguimiento de Ejecuciones

Seguro y Auditable

Moderno y Rápido

Características Clave

Resumen de Arquitectura

Modelo de Datos

Autenticación

Autorización

Trabajos en Segundo Plano

Stack Tecnológico

Tecnologías Principales

Gemas Clave

Herramientas de Desarrollo

Requisitos

Inicio Rápido

Desarrollo

Iniciar el Servidor

Flujo de Trabajo de Desarrollo

Gestión de Base de Datos

Gestión de Elasticsearch

Pruebas

Datos de Prueba

Servicios Externos

Servicios

Iniciar Servicios

Servidor MCP

Despliegue

Requisitos Previos

Guía de Despliegue

Despliegue Rápido

Características de Despliegue

Configuración

Variables de Entorno

Archivos de Configuración

Recursos

Documentación

Documentación del Proyecto

Comunidad