NazarKalytiuk/tarn

API tests an AI agent can write, run, and debug.
Docs ·
Get started ·
MCP integration ·
Agent loop demo
---
Tarn is a CLI-first API testing tool written in Rust. Tests are .tarn.yaml files. Output is structured JSON with categorized failures and remediation hints, so an agent — Claude Code, Codex, opencode, Cursor, Windsurf, pi — can write a test, run it, read what broke, and fix it without scraping logs.
When something breaks, --format json returns the same run as machine-readable data with failure_category, error_code, and the offending request/response. The tarn-mcp companion exposes a tarn_fix_plan tool that turns that report into actionable suggestions an agent can apply directly.
Why Tarn?
- **Structured failures, not log scraping** — every failure carries a stable category, error code, and remediation hints. Agents branch on taxonomy, not regex.
- **MCP-native** — tarn-mcp exposes list, validate, run, and fix_plan as structured tools for Claude Code, Codex, opencode, Cursor, and Windsurf (and pi via the skill + CLI). See AI agent integrations.
- **YAML the model already knows** — no DSL to teach, no test framework to bootstrap. An LLM writes a .tarn.yaml and ships.
- **One static binary** — curl | sh install, no runtime, drops into any CI image.
- **Batteries included** — REST + GraphQL, captures, cookies, multipart, includes, polling, Lua, parallel execution, 7 output formats.
Install
Pre-built binaries for **macOS** (Intel + Apple Silicon), **Linux** (amd64 + arm64), and **Windows** (amd64 zip) are on the releases page, each with a tarn-checksums.txt for SHA-256 verification and a generated tarn.rb Homebrew formula artifact. The installer also lays down tarn-mcp and tarn-lsp when present in the archive. Set TARN_INSTALL_DIR to install elsewhere. Container path: ghcr.io/ /tarn: from the release workflow. Manual verification works with shasum -a 256 -c tarn-checksums.txt.
Quick Start
The 60-second path:
Layer on the flags you actually need:
Debugging a failed run
Default to the **failures-first loop** — it keeps agents and humans off the megabyte-scale full report until they actually need it:
tarn failures groups by root-cause fingerprint and collapses skipped_due_to_failed_capture cascades into their upstream entry — one failing step with five downstream skips surfaces as one entry with cascades: 5, not six. tarn inspect supports run-id aliases last / latest / @latest / prev and drills into one record via FILE[::TEST[::STEP]]. tarn rerun --failed stamps rerun_source onto the new report. tarn diff prev last buckets failure fingerprints into new / fixed / persistent so you can confirm a patch without re-reading the full report.
Reach for .tarn/runs/ /report.json only when failures + inspect cannot answer the question. See plugin/skills/tarn-api-testing/SKILL.md (Failures-First Loop) and docs/TROUBLESHOOTING.md for the canonical agent-facing guidance, including a worked example of a mutation endpoint whose response shape changed from {"uuid": "..."} to {"request": {"uuid": "..."}} and the $.uuid → $.request.uuid fix.
Hello World
A fully local demo with no external network dependency:
More local scenarios — redirects, cookies, forms, error responses, authenticated CRUD — live in examples/demo-server/.
Documentation
Full guides, CLI reference, AI workflow walkthroughs, and editor setup live on the docs site:
** **
In-repo docs to start with:
- docs/INDEX.md — canonical map of all in-repo docs
- docs/AI_WORKFLOW_DEMO.md — end-to-end agent loop walkthrough
- docs/MCP_WORKFLOW.md — MCP server usage patterns
- docs/TARN_PRODUCT_STRATEGY.md — product direction
- docs/TARN_VS_HURL_COMPARISON.md and docs/HURL_MIGRATION.md — comparison and migration
- docs/TARN_LSP.md — tarn-lsp Language Server (LSP 3.17) for Neovim, Helix, Zed, and other compatible clients
- docs/VSCODE_EXTENSION.md — VS Code extension in editors/vscode
- editors/zed/README.md — Zed extension, published via zed-industries/extensions
The reference sections below mirror what's on the docs site — useful when reading on GitHub directly.
AI agent integrations
Tarn drives any agent that speaks MCP or has a shell. tarn-mcp exposes list / validate / run / fix_plan (plus the failures-first tools); the tarn-api-testing skill teaches the loop. This table is the canonical supported-agents list — per-agent setup kits live under editors/.