What is Tarn?

What is Tarn?

Tarn is a CLI-first API testing tool. Tests are written in YAML files (.tarn.yaml), results come back as structured JSON. One binary, zero runtime dependencies.

$ tarn run --format json tests/health.tarn.yaml

A minimal test file maps directly to the shape of an HTTP exchange. No framework, no test runner bootstrap, no language runtime:

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

That is the entire surface area for the most common API test. Complexity scales only when your scenario needs it — auth chains, polling, multipart uploads, multi-user sessions, GraphQL.

What problems does it solve?

Before Tarn, every API-testing approach had a fundamental mismatch with how AI agents and modern CI systems consume output:

• Postman/Newman — GUI-dependent authoring, heavy Node runtime, tests locked in JSON blobs with no structured failure taxonomy.
• curl scripts — fragile shell parsing, no structured assertions, no machine-readable output.
• REST Client — editor-locked, no CI integration, no parallel execution.
• Playwright API tests — browser runtime overhead, Python/JS dependency, not designed for API-only workflows.
• Hurl — no MCP or LSP tools, no structured JSON failures with stable categories, no fix plan engine.

Tarn replaces all of them with a single binary and a consistent contract:

• YAML that reads like a spec — request/assert blocks are declarative, not procedural.
• Structured JSON failures — every failure carries a category, error code, and remediation hints. Agents and dashboards branch on taxonomy, not regex.
• MCP tools — tarn-mcp exposes list, validate, run, and fix_plan as structured protocol tools. No stdout scraping.
• LSP server — tarn-lsp provides diagnostics, hover, completion, code lens, and quick fixes for every LSP 3.17 editor.
• Single binary, no runtime — install once, run anywhere. No Node, no Python, no JVM.

Typical use cases

• API smoke tests in CI — run tarn run --format json --json-mode compact as a CI step. Output feeds directly into dashboards and alerting.
• Integration test suites — chain setup steps, captures, and assertions across multiple endpoints. Reuse shared auth flows with includes.
• Contract and acceptance testing — assert response shape with JSONPath, type checks, and schema validation. Catch regressions before they reach production.
• Demo and onboarding suites — the repo ships runnable example suites for health checks, auth flows, polling, multipart, and CRUD. Point at a real API and go.
• Agent-driven test generation and debugging — LLMs write .tarn.yaml files, run them via MCP, and iterate on structured failure reports. No human in the loop required.

Key features

• YAML-first authoring — tests are plain YAML with no wrapping test framework.
• Rich assertions with JSONPath — exact match, type check, substring, regex, numeric comparison, schema validation.
• Capture chaining — type-preserving captures from JSONPath, headers, cookies, regex, status, and URL. Pipe syntax for transforms.
• Cookie handling — automatic jar by default. Named jars for multi-user session testing. Per-step disable.
• Polling and retries — poll until assertions pass. Step-level retries with configurable intervals and limits.
• Multipart upload — combine form fields and file attachments in a single request.
• Includes for shared steps — reuse setup, teardown, and auth flows across test files.
• Environment variables with priority chain — --var > shell env > tarn.env.local.yaml > tarn.env.{name}.yaml > tarn.env.yaml > inline env: block.
• Built-in functions — UUID v4/v7, timestamps, ISO 8601 dates, random hex/ints, full faker locale (email, name, phone, address, lorem, and more).
• Lua scripting — custom logic and transforms at any point in the step lifecycle.
• GraphQL support — send GraphQL queries with the same assertion and capture machinery.
• 9 output formats — human, JSON (compact or pretty), JUnit XML, TAP, HTML report, curl export, compact, LLM-friendly, AgentReport.
• MCP server — tarn-mcp for direct agent integration.
• LSP server — tarn-lsp with diagnostics, hover, completion, code lens, formatting, and quick fixes.
• Bench tool — timing and throughput measurements for endpoints.
• Post-run analysis — tarn failures, tarn diff, tarn inspect, tarn pack-context for debugging and context sharing.

How Tarn compares