Gherkio

Gherkio te permite describir pruebas de integración basadas en HTTP como escenarios declarativos en YAML. Define solicitudes, aserciones, extracciones de variables y orquestación, todo en un formato simple y legible que se mantiene mantenible con el tiempo.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Gherkio — Plataforma Declarativa de Pruebas de Integración

Gherkio Architecture Diagram

Escribe pruebas de integración de API en YAML declarativo. Sin código imperativo innecesario.

Gherkio es una plataforma de pruebas de integración de última generación diseñada para orquestar recorridos de usuario basados en HTTP. Describe secuencias de solicitudes, extrae variables, define aserciones enriquecidas y aplica políticas de seguridad, todo en un DSL YAML limpio y autodocumentado que sigue siendo legible después de 2 años.

¿Qué es Gherkio?

Gherkio es una plataforma declarativa de pruebas de integración que te permite escribir pruebas de integración de API en YAML puro en lugar de código imperativo. Se compila en un único binario estático de Go sin dependencias externas en tiempo de ejecución, lo que lo hace ideal para entornos CI efímeros, contenedores Docker y sistemas aislados.

  • DSL YAML declarativo — Describe qué comportamiento orquestar, no cómo implementarlo
  • Cero dependencias en tiempo de ejecución — Un único binario estático, sin necesidad de Node.js, Python o JVM
  • Listo para IA — Servidor MCP nativo para asistentes de codificación con IA
  • Seguridad empresarial — Aislamiento de salida, enmascaramiento de credenciales, prevención de SSRF

🎯 La Filosofía de Gherkio

Gherkio se basa en un principio central simple e inquebrantable:

Las pruebas de integración deben describir qué comportamiento orquestar, no cómo implementarlo.

  • Declarativo primero: Los escenarios describen flujos de trabajo de API de alto nivel en lugar de escribir cientos de líneas de scripts personalizados en Javascript/Go.
  • La legibilidad importa: Las pruebas de integración se escriben para que cualquier persona del equipo (incluidos gerentes de producto y QA) pueda leerlas, auditarlas y mantenerlas fácilmente.
  • Observabilidad profunda: Cada ejecución genera aserciones de terminal de alta precisión y rastreos estructurados para que los fallos se depuren al instante.
  • DSL restringido: Flujo de control declarativo limitado (repeat, for_each) sin scripting arbitrario ni ramificaciones complejas, lo que mantiene las pruebas predecibles y auditables.

📚 Libro de Documentación para Desarrolladores

Gherkio incluye un extenso Libro de Documentación para Desarrolladores (mdBook) de nivel de producción que cubre todas las capas estructurales, referencias detalladas de sintaxis DSL, pautas de seguridad y recetas de pruebas del mundo real:

Compilar y ver localmente

Para compilar y explorar la documentación para desarrolladores localmente:

# Generate Cobra CLI manual pages and compile mdBook
make docs-build

# Open the compiled HTML index in your browser
# (or double-click docs/book/book/index.html)

🎮 Playground interactivo en el navegador

Para reducir la curva de aprendizaje de Gherkio a cero, Gherkio incluye un Playground interactivo y centro de documentación autónomo basado en navegador ubicado en docs/book/playground/index.html.

  • Paso a paso visual del DSL: Escribe o edita pasos de prueba Gherkio en YAML y ve un diagrama de flujo gráfico en vivo construido al instante.
  • Traductor de cURL a YAML: Pega declaraciones cURL heredadas estándar y obtén pasos Gherkio perfectamente compilados al instante.

Inícialo al instante:

  • Sandbox en línea: Accede al espacio de trabajo web alojado directamente en Playground de GitHub Pages.
  • Inicio local: Haz doble clic en docs/book/playground/index.html para ejecutarlo en tu navegador sin conexión, o ábrelo mediante la terminal: 
    # Linux
xdg-open docs/book/playground/index.html

# macOS
open docs/book/playground/index.html

⚡ Funciones principales

  • DSL YAML declarativo — Describe escenarios de prueba, no la implementación. Los escenarios funcionan como documentación ejecutable en vivo, legible por ingenieros, QA y gerentes de producto.
  • Ejecución de solicitudes HTTP — POST, GET, PUT, DELETE, PATCH con soporte completo de encabezados/cuerpo y cargas multiparte en streaming con anulaciones MIME explícitas.
  • Motor de aserciones enriquecido — Más de 30 comparadores integrados que incluyen códigos de estado, tipos de campo (uuid, email, datetime, uri), longitudes de listas, comprobaciones de existencia y aserciones negativas.
  • Decodificación automática de JWT — Decodifica y valida automáticamente las reclamaciones de los tokens de respuesta (jwt.role: admin) sin escribir código de analizador personalizado. Extrae reclamaciones en variables mediante save: { role: jwt.user_role }. Configura rutas de token personalizadas en .gherkio/config.yaml con jwt_token_path: "data.access_token".
  • Composición de escenarios — Reutiliza escenarios existentes como pasos con use: para una orquestación limpia y DRY en todos los conjuntos de pruebas.
  • Reintentos de solicitudes — Maneja la consistencia eventual con intervalos configurables, retroceso exponencial y condiciones de salida basadas en estado.
  • Aislamiento de salida (prevención de SSRF) — Restringe los alcances de conexión de API con mapas de dominio comodín, detección de bucle local a nivel de DNS y bloqueo de subredes privadas.
  • Enmascaramiento de campos sensibles — Redacta automáticamente contraseñas, claves de API, tokens y encabezados de autorización en todas las salidas de consola e informes.
  • Credenciales de múltiples cuentas — Ejecuta la misma prueba contra múltiples cuentas de usuario (--account / --all-accounts) sin duplicar archivos de prueba.
  • Ejecución paralela — Acelera los ciclos de retroalimentación ejecutando pruebas de forma concurrente con concurrencia configurable (-p <concurrency>).
  • Servidor MCP nativo — Servidor de Protocolo de contexto de modelo integrado para la integración de asistentes de IA con Cursor, Claude Desktop, Cline y Copilot.
  • Conversión de cURL a YAML — Traduce declaraciones cURL heredadas a pasos Gherkio en YAML al instante mediante CLI o el playground interactivo.

🚀 Inicio rápido en 3 pasos

1. Instalación

Instala Gherkio usando nuestro script de instalación ligero:

curl -fsSL https://raw.githubusercontent.com/muhfaris/gherkio/main/install.sh | sudo bash

2. Crear un proyecto

Inicializa el diseño de espacio de trabajo canónico de Gherkio:

gherkio init

3. Ejecutar la prueba generada

Ejecuta el escenario de prueba generado automáticamente:

gherkio run example/auth/login.yaml -v

🤖 Servidor MCP integrado (Integración de IA)

Gherkio incluye un servidor de Protocolo de contexto de modelo (MCP) nativo sobre stdio. Esto permite que los asistentes de codificación con IA (como Cursor, Claude Desktop, Cline y Copilot) lean especificaciones, generen escenarios, validen estructuras y ejecuten pruebas por ti usando lenguaje natural.

Configuración de Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "gherkio": {
      "command": "/usr/local/bin/gherkio",
      "args": ["mcp"]
    }
  }
}

Para configuraciones de Claude, Cline, Neovim, JetBrains y Zed, consulta la Guía de configuración del Protocolo de contexto de modelo.

🤝 Desarrollo y contribuciones

Requisitos previos: Go 1.25+

git clone https://github.com/muhfaris/gherkio.git
cd gherkio

# Build the CLI
go build -o gherkio .

# Run all unit tests
go test ./...

# Regenerate console output golden snapshot files
go test ./internal/runner/ -update

Para pautas detalladas de contribución, estándares de confirmación y explicaciones de pruebas de instantáneas, consulta la Guía de contribución.

❓ Preguntas frecuentes

¿Qué hace diferente a Gherkio de Postman o Bruno?

Postman y Bruno son clientes de API centrados en GUI. Gherkio es una plataforma de pruebas de integración centrada en CLI diseñada para pipelines CI/CD. Las pruebas son archivos YAML simples que viven en tu repositorio, se ejecutan de forma determinista y producen informes estructurados, sin necesidad de GUI ni bloqueo de proveedor.

¿Gherkio requiere Node.js, Python o una JVM?

No. Gherkio es un único binario estático de Go con cero dependencias externas en tiempo de ejecución. Se ejecuta en cualquier lugar donde Go compile: Linux, macOS, Windows, Docker e incluso entornos aislados.

¿Puede Gherkio funcionar con pipelines CI/CD existentes?

Sí. Gherkio produce códigos de salida, informes JSON estructurados y salida legible por máquina que se integra con GitHub Actions, GitLab CI, Jenkins, CircleCI y cualquier pipeline compatible con POSIX.

¿Cómo maneja Gherkio la autenticación y las credenciales?

Gherkio admite credenciales de múltiples cuentas, inyección de variables de entorno y enmascaramiento automático de campos sensibles. Puedes ejecutar la misma prueba contra cuentas de administrador, usuario y solo lectura simultáneamente usando gherkio run --all-accounts.

¿Gherkio admite GraphQL o gRPC?

El motor HTTP de Gherkio admite cualquier API basada en JSON, incluidos los endpoints de GraphQL. El soporte nativo de gRPC está en la hoja de ruta.

¿Pueden los asistentes de IA escribir pruebas de Gherkio?

Sí. Gherkio incluye un servidor MCP nativo que permite que los asistentes de codificación con IA (Cursor, Claude Desktop, Cline, Copilot) lean especificaciones, generen escenarios, validen estructuras y ejecuten pruebas usando lenguaje natural.

¿Cómo convierto comandos cURL existentes a YAML de Gherkio?

Usa gherkio convert --curl "curl -X POST https://api.example.com/login" para traducir al instante declaraciones cURL a pasos YAML de Gherkio. El playground interactivo también incluye un traductor de cURL a YAML.

¿Qué funciones de seguridad incluye Gherkio?

Gherkio incluye aislamiento de red de salida (prevención de SSRF), protección contra bucle local a nivel de DNS, enmascaramiento de campos sensibles en la salida de consola y aislamiento de credenciales entre cuentas.

📄 Licencia

MIT © 2026 Muhammad Faris