Gherkio

O Gherkio permite descrever testes de integração baseados em HTTP como cenários declarativos em YAML. Defina requisições, asserções, extrações de variáveis e orquestração, tudo em um formato simples e legível que se mantém sustentável ao longo do tempo.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Gherkio — Plataforma Declarativa de Testes de Integração

Gherkio Architecture Diagram

Escreva testes de integração de API em YAML declarativo. Sem boilerplates imperativos.

Gherkio é uma plataforma de testes de integração de última geração projetada para orquestrar jornadas de usuário baseadas em HTTP. Descreva sequências de requisições, extraia variáveis, defina asserções ricas e aplique políticas de segurança — tudo em um DSL YAML limpo e autodocumentado que permanece legível após 2 anos.

O que é o Gherkio?

Gherkio é uma plataforma declarativa de testes de integração que permite escrever testes de integração de API em YAML puro, em vez de código imperativo. Ele compila para um único binário Go estático, sem dependências externas em tempo de execução, tornando-o ideal para ambientes CI efêmeros, contêineres Docker e sistemas isolados.

  • DSL YAML declarativo — Descreva qual comportamento orquestrar, não como implementá-lo
  • Zero dependências em tempo de execução — Binário estático único, sem necessidade de Node.js, Python ou JVM
  • Pronto para IA — Servidor MCP nativo para assistentes de codificação com IA
  • Segurança empresarial — Sandboxing de saída, mascaramento de credenciais, prevenção de SSRF

🎯 A Filosofia do Gherkio

Gherkio é construído sobre um princípio central simples e inflexível:

Testes de integração devem descrever qual comportamento orquestrar, não como implementá-lo.

  • Declarativo-Primeiro: Cenários descrevem fluxos de trabalho de API de alto nível, em vez de escrever centenas de linhas de scripts customizados em Javascript/Go.
  • Legibilidade Importa: Testes de integração são escritos para serem facilmente lidos, auditados e mantidos por qualquer pessoa da equipe (incluindo Gerentes de Produto e QA).
  • Observabilidade Profunda: Cada execução gera asserções de terminal de alta precisão e tracebacks estruturados para que falhas sejam depuradas instantaneamente.
  • DSL Restrito: Fluxo de controle declarativo limitado (repeat, for_each) sem scripts arbitrários ou ramificações complexas — mantendo os testes previsíveis e auditáveis.

📚 Livro de Documentação para Desenvolvedores

O Gherkio possui um extenso Livro de Documentação para Desenvolvedores (mdBook) de nível de produção que cobre todas as camadas estruturais, referências detalhadas de sintaxe DSL, diretrizes de segurança e receitas de testes do mundo real:

Compilar e Visualizar Localmente

Para compilar e navegar pela documentação do desenvolvedor 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 Interativo no Navegador

Para reduzir a curva de aprendizado do Gherkio a zero, o Gherkio inclui um Playground Interativo e Hub de Documentação autônomo baseado em navegador, localizado em docs/book/playground/index.html.

  • Stepper Visual de DSL: Digite ou edite etapas de teste Gherkio em YAML e veja um fluxograma gráfico ao vivo construído em tempo real!
  • Tradutor de Etapas cURL-para-YAML: Cole declarações cURL legadas padrão e receba etapas Gherkio perfeitamente compiladas instantaneamente.

Inicie instantaneamente:

  • Sandbox Online: Acesse o workspace web hospedado diretamente no GitHub Pages Playground.
  • Inicialização Local: Clique duas vezes em docs/book/playground/index.html para executá-lo no seu navegador offline, ou abra-o via terminal: 
    # Linux
xdg-open docs/book/playground/index.html

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

⚡ Recursos Principais

  • DSL YAML Declarativo — Descreva cenários de teste, não implementação. Cenários funcionam como documentação executável ao vivo, legível por engenheiros, QA e gerentes de produto.
  • Execução de Requisições HTTP — POST, GET, PUT, DELETE, PATCH com suporte completo a cabeçalhos/corpo e uploads multipart em streaming com overrides explícitos de MIME.
  • Motor de Asserções Rico — Mais de 30 matchers integrados, incluindo códigos de status, tipos de campo (uuid, email, datetime, uri), tamanhos de listas, verificações de existência e asserções negativas.
  • Decodificação Automática de JWT — Decodifique e valide automaticamente claims de tokens de resposta (jwt.role: admin) sem escrever código de parser customizado. Extraia claims em variáveis via save: { role: jwt.user_role }. Configure caminhos de token customizados em .gherkio/config.yaml com jwt_token_path: "data.access_token".
  • Composição de Cenários — Reutilize cenários existentes como etapas com use: para orquestração limpa e DRY entre suítes de teste.
  • Tentativas de Requisição — Lide com consistência eventual com intervalos configuráveis, backoff exponencial e condições de saída baseadas em status.
  • Sandboxing de Saída (Prevenção de SSRF) — Restrinja escopos de conexão de API com mapas de domínio curinga, detecção de loopback em nível de DNS e bloqueio de sub-redes privadas.
  • Mascaramento de Campos Sensíveis — Redija automaticamente senhas, chaves de API, tokens e cabeçalhos de autorização em todas as saídas de console e relatórios.
  • Credenciais Multi-Conta — Execute o mesmo teste contra múltiplas contas de usuário (--account / --all-accounts) sem duplicar arquivos de teste.
  • Execução Paralela — Acelere loops de feedback executando testes concorrentemente com concorrência configurável (-p <concurrency>).
  • Servidor MCP Nativo — Servidor Model Context Protocol integrado para integração com assistentes de IA como Cursor, Claude Desktop, Cline e Copilot.
  • Conversão cURL-para-YAML — Traduza declarações cURL legadas em etapas Gherkio YAML instantaneamente via CLI ou playground interativo.

🚀 Quickstart em 3 Etapas

1. Instalação

Instale o Gherkio usando nosso script de instalação leve:

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

2. Estruture um Projeto

Inicialize o layout de workspace canônico do Gherkio:

gherkio init

3. Execute o Teste Estruturado

Execute o cenário de teste gerado automaticamente:

gherkio run example/auth/login.yaml -v

🤖 Servidor MCP Integrado (Integração com IA)

O Gherkio inclui um servidor Model Context Protocol (MCP) nativo via stdio. Isso permite que assistentes de codificação com IA (como Cursor, Claude Desktop, Cline e Copilot) leiam especificações, gerem cenários, validem estruturas e executem testes para você usando linguagem natural.

Configuração do Cursor (.cursor/mcp.json)

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

Para configurações do Claude, Cline, Neovim, JetBrains e Zed, consulte o Guia de Configuração do Model Context Protocol.

🤝 Desenvolvimento e Contribuição

Pré-requisitos: 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 diretrizes detalhadas de contribuição, padrões de commit e explicações sobre testes de snapshot, consulte o Guia de Contribuição.

❓ Perguntas Frequentes

O que torna o Gherkio diferente do Postman ou Bruno?

Postman e Bruno são clientes de API focados em GUI. O Gherkio é uma plataforma de testes de integração CLI-first projetada para pipelines CI/CD. Os testes são arquivos YAML simples que vivem no seu repositório, executam deterministicamente e produzem relatórios estruturados — sem necessidade de GUI, sem vendor lock-in.

O Gherkio requer Node.js, Python ou JVM?

Não. O Gherkio é um único binário Go estático com zero dependências externas em tempo de execução. Ele roda em qualquer lugar onde Go compila — Linux, macOS, Windows, Docker e até ambientes isolados.

O Gherkio funciona com pipelines CI/CD existentes?

Sim. O Gherkio produz códigos de saída, relatórios JSON estruturados e saída legível por máquina que se integra com GitHub Actions, GitLab CI, Jenkins, CircleCI e qualquer pipeline compatível com POSIX.

Como o Gherkio lida com autenticação e credenciais?

O Gherkio suporta credenciais multi-conta, injeção de variáveis de ambiente e mascaramento automático de campos sensíveis. Você pode executar o mesmo teste contra contas admin, usuário e somente leitura simultaneamente usando gherkio run --all-accounts.

O Gherkio suporta GraphQL ou gRPC?

O motor HTTP do Gherkio suporta qualquer API baseada em JSON, incluindo endpoints GraphQL. Suporte nativo a gRPC está no roadmap.

Assistentes de IA podem escrever testes Gherkio?

Sim. O Gherkio inclui um servidor MCP nativo que permite que assistentes de codificação com IA (Cursor, Claude Desktop, Cline, Copilot) leiam especificações, gerem cenários, validem estruturas e executem testes usando linguagem natural.

Como converto comandos cURL existentes para YAML Gherkio?

Use gherkio convert --curl "curl -X POST https://api.example.com/login" para traduzir instantaneamente declarações cURL em etapas YAML Gherkio. O playground interativo também inclui um tradutor cURL-para-YAML.

Quais recursos de segurança o Gherkio inclui?

O Gherkio inclui sandboxing de rede de saída (prevenção de SSRF), proteção contra loopback em nível de DNS, mascaramento de campos sensíveis na saída do console e isolamento de credenciais entre contas.

📄 Licença

MIT © 2026 Muhammad Faris