Gherkio
About
Gherkio lets you describe HTTP-based integration tests as declarative YAML scenarios. Define requests, assertions, variable extractions, and orchestration. all in a simple, human-readable format that stays maintainable over time.
Details
- Author
- muhfaris
- Categories
- Productivity, Developer Tools, API, Automation
Jump to
Setup
Install Gherkio in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/muhfaris/gherkio
Follow the installation instructions in the repository README, then restart your MCP client.
Gherkio — Declarative Integration Testing Platform
Write API integration tests in declarative YAML. No imperative boilerplates required.
Gherkio is a state-of-the-art integration testing platform designed to orchestrate HTTP-based user journeys. Describe request sequences, extract variables, define rich assertions, and enforce security policies — all in a clean, self-documenting YAML DSL that stays readable after 2 years.
Gherkio is a declarative integration testing platform that lets you write API integration tests in pure YAML instead of imperative code. It compiles to a single static Go binary with zero external runtime dependencies, making it ideal for ephemeral CI environments, Docker containers, and air-gapped systems.
- Declarative YAML DSL— Describe what behavior to orchestrate, not how to implement it
- Zero runtime dependencies— Single static binary, no Node.js, Python, or JVM required
- AI-ready— Native MCP server for AI coding assistants
- Enterprise security— Outbound sandboxing, credential masking, SSRF prevention
Gherkio is built on a simple, uncompromising core principle:
Integration testing should describewhatbehavior to orchestrate, nothowto implement it.
- Declarative-First: Scenarios describe high-level API workflows rather than writing hundreds of lines of custom Javascript/Go scripts.
- Readability Matters: Integration tests are written to be easily read, audited, and maintained by anyone on the team (including Product Managers and QA).
- Deep Observability: Every execution outputs high-precision terminal assertions and structured tracebacks so failures are debugged instantly.
- Constrained DSL: No arbitrary loops or complex branching inside test files—forcing tests to stay clean, predictable, and robust.
Gherkio features an extensive, production-gradeDeveloper Documentation Book (mdBook)that covers all structural layers, detailed DSL syntax references, security guidelines, and real-world testing recipes:
- Progressive Onboarding: Progress through ourIntroduction,2-Minute Quickstart,Tutorial, andInteractive Playground.
- Deep DSL Reference: Comprehensive specifications forAssertions & Dot-Paths,Request Configuration,Multipart Form Data,Setup & Teardown, andRetries.
- Variable Precedence & Dynamic Generators: Details on time/date offsets, custom Go layout formatting, base64 encodes, and cryptographic SHA-256 HMAC validations inVariables & Generators.
- Outbound Network Sandboxing: In-depth explanations of SSRF prevention, DNS rebound protection, and network allowlists/blocklists inProject & Security Setup.
- AI Integration & MCP Server: Step-by-step connection guides for Claude Desktop, VS Code (Cline/Continue), Cursor, Neovim, JetBrains, and Zed inModel Context Protocol.
- Frequently Asked Questions: Quick answers to common questions about setup, credentials, CI/CD integration, and troubleshooting in theFAQ.
To compile and browse the developer documentation locally:
# 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)
To lower Gherkio's learning curve to zero, Gherkio includes a self-contained, browser-basedInteractive Playground and Documentation Hublocated underdocs/book/playground/index.html.
- Visual DSL Stepper: Type or edit Gherkio YAML test steps and see a live graphical flowchart built on the fly!
- cURL-to-YAML Step Translator: Paste standard legacy cURL statements and get back perfectly compiled Gherkio steps instantly.
- Online Sandbox: Access the hosted web workspace directly onGitHub Pages Playground.
- Local Launch: Double-clickdocs/book/playground/index.htmlto run it in your browser offline, or open it via terminal:
# Linux xdg-open docs/book/playground/index.html # macOS open docs/book/playground/index.html
- Declarative YAML DSL— Describe test scenarios, not implementation. Scenarios double as live, executable documentation readable by engineers, QA, and product managers.
- HTTP Request Execution— POST, GET, PUT, DELETE, PATCH with full header/body support, multipart uploads, and automatic MIME detection.
- Rich Assertion Engine— 30+ built-in matchers including status codes, field types (uuid,email,datetime,uri), list lengths, existence checks, and negative assertions.
- JWT Auto-Decoding— Automatically decode and assert claims from response tokens (jwt.role: admin) without writing custom parser code. Extract claims into variables viasave: { role: jwt.user_role }. Configure custom token paths in.gherkio/config.yamlwithjwt_token_path: "data.access_token".
- Scenario Composition— Reuse existing scenarios as steps withuse:for clean, DRY orchestration across test suites.
- Request Retries— Handle eventual consistency with configurable intervals, exponential backoff, and status-based exit conditions.
- Outbound Sandboxing (SSRF Prevention)— Restrict API connection scopes with wildcard domain maps, DNS-level loopback detection, and private subnet blocking.
- Sensitive Field Masking— Automatically redact passwords, API keys, tokens, and authorization headers in all console and report outputs.
- Multi-Account Credentials— Run the same test against multiple user accounts (--account/--all-accounts) without duplicating test files.
- Parallel Execution— Accelerate feedback loops by executing tests concurrently with configurable concurrency (-p <concurrency>).
- Native MCP Server— Built-in Model Context Protocol server for AI assistant integration with Cursor, Claude Desktop, Cline, and Copilot.
- cURL-to-YAML Conversion— Translate legacy cURL statements into Gherkio YAML steps instantly via CLI or interactive playground.
Install Gherkio using our lightweight installer script:
curl -fsSL https://raw.githubusercontent.com/muhfaris/gherkio/main/install.sh | sudo bash
Initialize Gherkio's canonical workspace layout:
Execute the auto-generated test scenario:
Gherkio ships with a nativeModel Context Protocol (MCP) serverover stdio. This lets AI coding assistants (like Cursor, Claude Desktop, Cline, and Copilot) read specifications, generate scenarios, validate structures, and run tests for you using natural language.
{ "mcpServers": { "gherkio": { "command": "/usr/local/bin/gherkio", "args": ["mcp"] } } }
For Claude, Cline, Neovim, JetBrains, and Zed configurations, see theModel Context Protocol Setup Guide.
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
For detailed contribution guidelines, commit standards, and snapshot testing explanations, see theContributing Guide.
What makes Gherkio different from Postman or Bruno?
Postman and Bruno are GUI-centric API clients. Gherkio is a CLI-first integration testing platform designed for CI/CD pipelines. Tests are plain YAML files that live in your repository, execute deterministically, and produce structured reports — no GUI required, no vendor lock-in.
Does Gherkio require Node.js, Python, or a JVM?
No. Gherkio is a single static Go binary with zero external runtime dependencies. It runs anywhere Go compiles — Linux, macOS, Windows, Docker, and even air-gapped environments.
Can Gherkio work with existing CI/CD pipelines?
Yes. Gherkio produces exit codes, structured JSON reports, and machine-readable output that integrates with GitHub Actions, GitLab CI, Jenkins, CircleCI, and any POSIX-compatible pipeline.
How does Gherkio handle authentication and credentials?
Gherkio supports multi-account credentials, environment variable injection, and automatic sensitive field masking. You can run the same test against admin, user, and read-only accounts simultaneously usinggherkio run --all-accounts.
Gherkio's HTTP engine supports any JSON-based API, including GraphQL endpoints. Native gRPC support is on the roadmap.
Yes. Gherkio ships with a native MCP server that lets AI coding assistants (Cursor, Claude Desktop, Cline, Copilot) read specifications, generate scenarios, validate structures, and run tests using natural language.
How do I convert existing cURL commands to Gherkio YAML?
Usegherkio convert --curl "curl -X POST https://api.example.com/login"to instantly translate cURL statements into Gherkio YAML steps. The interactive playground also includes a cURL-to-YAML translator.
What security features does Gherkio include?
Gherkio includes outbound network sandboxing (SSRF prevention), DNS-level loopback protection, sensitive field masking in console output, and credential isolation across accounts.
Operate and build n8n: 55 tools with validation, surgical edits, webhook testing and rollback.
An MCP server for Factifai, enabling integration with any MCP-compatible AI tool to create and retrieve test results asynchronously.
Source-grounded launch review for x402, MCP, paid API, and agent-tool listings.
Magica is your all-in-one AI platform, offering 2500+ cutting-edge tools under a single subscription.
Turn your Make scenarios into callable tools for AI assistants.
Dynamically search and call tools using UnifAI Network
WunderTrading MCP connects AI agents to live crypto trading execution on 20+ supported exchanges through a single MCP integration. Use it to turn AI-driven signals, market analysis, sentiment, screenshots, and custom strategy logic into real trades on exchanges including Binance, Bybit, Coinbase, Bitget, OKX, KuCoin, Hyperliquid, and BingX. Supports MCP and REST API workflows for order execution, trade management, and AI-powered automation.
Connect your AI Agents to 8,000 apps instantly.
Connect AI assistants to Automatisch for workflow automation.
The new Bright MCP Server enables AI assistants to directly interact with Bright and manage security scans end-to-end. Using natural language prompts, AI can now analyze existing coverage, identify missing or hidden entrypoints, add them to the project, select the most relevant security tests based on the application’s technology, and start scans automatically.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
