01
Overview
What Tarn is, what problems it solves, and how it compares to Postman, curl, Hurl, and Playwright.
CLI-first · AI-native · Zero dependencies
API Testing for the AI Age
YAML-simple test authoring. Structured JSON failures with stable error codes and remediation hints. MCP tools. One binary, zero runtime dependencies.
terminal
$ tarn init
# scaffold project with example tests
$ tarn run --format json --json-mode compact
# structured output for agents and CI
$ tarn run --ndjson --select tests/auth.tarn.yaml::login
# stream events for a single scoped test
$ tarn fmt --check
# normalize YAML formatting
$ tarn validate --format json
# catch config issues before execution
# scaffold project with example tests
$ tarn run --format json --json-mode compact
# structured output for agents and CI
$ tarn run --ndjson --select tests/auth.tarn.yaml::login
# stream events for a single scoped test
$ tarn fmt --check
# normalize YAML formatting
$ tarn validate --format json
# catch config issues before execution
1 binary
No runtime, no test framework project to bootstrap.
7 formats
Human, JSON, JUnit, TAP, HTML, curl, and curl-all.
MCP & LSP
Portable .mcp.json, tarn_fix_plan, and a tarn-lsp language server.
Editor-ready
VS Code extension, Claude Code plugin, Neovim, Helix, Zed.
Why Tarn
Built for the agent loop.
Tarn's wedge is not "YAML tests exist." It is that failures come back as structured data with a stable taxonomy an agent can reason over.
✦
Structured Failures
Every failure includes a category, error code, and remediation hints. Agents branch on taxonomy, not regex.
⌘
MCP Tools
tarn-mcp exposes list, validate, run, and fix_plan as structured tools. No stdout scraping needed.
⬡
Rich Assertions
JSONPath, status shorthand, type checks, UUID validation, date matching, schema validation, and unified diffs.
⇄
Capture Chains
Type-preserving captures from JSONPath, headers, cookies, regex, status, and URL. Chain with transforms.
◎
Cookie Jars
Automatic cookie jar by default. Named jars for multi-user session testing. Per-step disable switch.
↻
Polling & Retries
Poll until assertions pass. Step-level retries for transient failures. Configurable intervals and limits.
▢
Editor Intelligence
tarn-lsp is a standalone LSP 3.17 server. VS Code extension and Claude Code plugin on top. Diagnostics, hover, completion, code lens, quick fixes.
➤
Streaming & Scoped Runs
--ndjson emits one event per line for live UIs. --select file::test::step ANDs with --tag for surgical reruns. --only-failed keeps tight iteration.
☰
Canonical Formatting
tarn fmt normalizes YAML aliases and field order. --check mode fails in CI when files drift.
Guides
Follow the shortest path first.
Optimized for onboarding. The repository markdown remains the deeper source for strategy and workflow details.
02
Getting Started
Install Tarn, scaffold a project, run your first test, and understand the core loop — fmt, validate, run.
03
Writing Tests
Complete guide to YAML test files: requests, assertions, captures, variables, cookies, multipart, includes, and built-in functions.
04
CLI Reference
Full reference for all tarn commands: run, validate, format, list, init, bench, lint, scaffold, and more.
05
AI Workflows
Structured JSON output, failure categories, fix plans, and agent loops for AI-driven test development.
06
MCP Integration
Portable .mcp.json setup for Claude Code, opencode, Cursor, Windsurf — structured tools for agents.
07
LSP & Editor Support
Standalone LSP server for diagnostics, hover, completion, code actions, and JSONPath evaluation in any editor.
08
CI Integration
GitHub Actions, environment secrets, artifact reports, format gating, and best practices for CI pipelines.
09
Examples
Copy-paste ready test files: health check, CRUD, auth flow, faker data, and the local demo-server suites.
10
Troubleshooting
Common issues and fixes: parse errors, connection failures, capture problems, assertion mismatches, and more.
11
Reference
Compact reference pages: assertion operators, built-in functions, YAML format, JSON report, failure categories, MCP tools, LSP capabilities.
GitHub Repository
Full source, strategy docs, roadmap, comparison matrix, and release notes.