tarn

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.

# tests/health.tarn.yaml
name: Health check
steps:
  - name: GET /health
    request:
      method: GET
      url: "{{ env.base_url }}/health"
    assert:
      status: 200

$ tarn run
 TARN  Running tests/health.tarn.yaml

 ● Health check
   ✓ GET /health (4ms)

 Results: 1 passed (15ms)

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

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/NazarKalytiuk/tarn/main/install.sh | sh

# from source
cargo install --git https://github.com/NazarKalytiuk/tarn.git --bin tarn

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/<owner>/tarn:<tag> from the release workflow. Manual verification works with shasum -a 256 -c tarn-checksums.txt.

Quick Start

The 60-second path:

tarn init                              # scaffold tests/ + tarn.env.yaml + advanced templates
# edit tarn.env.yaml so base_url points at your API
tarn run                               # runs every .tarn.yaml under tests/

Layer on the flags you actually need:

tarn run --format json --json-mode compact   # structured output for agents and CI
tarn run --env staging                       # use a named environment
tarn run --only-failed                       # quiet down a noisy run
tarn run --watch                             # rerun on file changes
tarn run --parallel                          # run files in parallel
tarn list --tag smoke                        # what would run, without running
tarn fmt --check                             # canonical YAML, CI-gateable

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: