Test API flows,
not just endpoints.

Test File Structure

A test file has a simple structure: environment variables, optional setup, and an array of test suites.

{
  "$schema": "https://unpkg.com/@nanotiny/tiny-api-test/schema.json",
  "env": { "baseUrl": "https://api.example.com" },
  "setup": "node scripts/get-token.js",
  "timeout": 5000,
  "suites": [ ... ]
}

env:
  baseUrl: https://api.example.com

setup: node scripts/get-token.js
timeout: 5000

suites:
  - ...

Top-Level Fields

Suite Fields

Test Fields

Assertions

Each assertion is evaluated against the response context. Body fields from object responses are spread at the root for easy access.

Response Context

// Response: { status: 200, body: { id: 1, name: "Alice" } }
// Available in assertions:
$status   = 200            // HTTP status code
$headers  = { ... }         // Response headers
$body     = { id: 1, ... }  // Full response body
$duration = 142            // Request time in ms
id        = 1              // Body fields spread at root
name      = "Alice"        // Body fields spread at root

Operators

Duration Assertions

Use $duration to assert response time:

"assert": ["$status == 200", "$duration < 500"]

assert:
  - "$status == 200"
  - "$duration < 500"

Failed Assertion Output

When an assertion fails, tat prints the referenced actual values on the same line so you can see what the API returned without rerunning in a debugger.

$ tat run tests.tat.yml

Users
  ✘ Get user (86ms)
    ✘ $status == 200 (actual: $status=500)
    ✘ name == "Alice" (actual: name="Bob")

Response Output

Use response on a test when you want to print response details in the test output. response: true keeps the compact shortcut for body and headers; use the object form to request status, body, and headers individually.

• response: true includes body and headers.
• response: { status: true } includes only the response status code.
• response: { body: true } includes only the response body.
• response: { headers: true } includes only the response headers.

{
  "name": "Inspect status",
  "method": "GET",
  "url": "{{baseUrl}}/users/1",
  "response": { "status": true },
  "assert": ["$status == 200"]
}

- name: Inspect status
  method: GET
  url: "{{baseUrl}}/users/1"
  response:
    status: true
  assert:
    - "$status == 200"

Users
  ✔ Inspect status (72ms)
    Response status: 200

Capture & Variables

Use capture to extract values from a response and reuse them in later tests with {{variable}} interpolation.

Basic Capture

// Create a user and capture the ID
{
  "name": "Create user",
  "method": "POST",
  "url": "{{baseUrl}}/users",
  "body": { "name": "Alice" },
  "assert": ["$status == 201"],
  "capture": { "userId": "id" }
}

// Use the captured ID in a later test
{
  "name": "Get user",
  "method": "GET",
  "url": "{{baseUrl}}/users/{{userId}}",
  "assert": ["$status == 200", "name == 'Alice'"]
}

# Create a user and capture the ID
- name: Create user
  method: POST
  url: "{{baseUrl}}/users"
  body:
    name: Alice
  assert:
    - "$status == 201"
  capture:
    userId: id

# Use the captured ID in a later test
- name: Get user
  method: GET
  url: "{{baseUrl}}/users/{{userId}}"
  assert:
    - "$status == 200"
    - "name == 'Alice'"

Advanced Capture Expressions

Capture uses @nanotiny/json-expression query syntax — filter arrays, use indexes, traverse nested paths:

"capture": {
  "companyName": "companies.name | id == 'c2'",       // filter by field
  "thirdId":     "companies.id | $index == 2",         // by array index
  "firstType":   "types.type.name",                    // nested path
  "hpStat":      "stats.base_stat | $index == 0"       // indexed nested
}

capture:
  companyName: "companies.name | id == 'c2'"       # filter by field
  thirdId:     "companies.id | $index == 2"         # by array index
  firstType:   types.type.name                    # nested path
  hpStat:      "stats.base_stat | $index == 0"       # indexed nested

Environment Variables

Define variables in the env field (inline or external file). Variables are interpolated in url, headers, and body:

{
  "env": { "baseUrl": "https://api.example.com", "token": "abc123" },
  // or load from file:
  "env": "./env.local.json"
}

env:
  baseUrl: https://api.example.com
  token: abc123

# or load from file:
env: ./env.local.json

Single Test Runs

When you run a single test with --suite and --test, tat keeps that run isolated. Earlier tests are not executed automatically, so capture-derived values must come from env, setup, --env-cmd, or manual --variables input.

$ tat run tests.tat.yml --suite "Workspace flow" --test "Create project" --variables workspaceId=ws-123

CLI Reference

tat run <file>

Run tests from a JSON/YAML file, or from a directory (discovers all .tat.json, .tat.yml, .tat.yaml files recursively).

tat validate <file>

Check syntax, schema validity, and warn about undefined {{variables}} without running tests.

$ tat validate tests.tat.json
tests.tat.json: valid

$ tat validate tests.tat.json
tests.tat.json: valid (1 warning)
  [warn] test "Get user": variable "{{token}}" is not defined

Exit Codes

Timeout Priority

Highest to lowest: per-test timeout field → --timeout CLI flag → file-level timeout → no timeout.

Authentication

Static Token

For APIs where you already have a token — put it in your env:

{
  "env": { "token": "eyJhbG..." }
}

env:
  token: eyJhbG...

Setup Hook (OAuth / 2FA)

The setup command runs before tests. Its JSON stdout merges into env. Interactive prompts work because stdin/stderr are inherited:

{
  "setup": "node scripts/get-token.js",
  "suites": [...]
}

setup: node scripts/get-token.js

suites:
  - ...

// scripts/get-token.js — print JSON to stdout
// ... do OAuth flow, prompt for 2FA ...
console.log(JSON.stringify({ token: access_token }));

CI / --env-cmd

Same as setup but from the command line — useful when auth differs per environment:

$ tat run tests.json --env-cmd "node scripts/ci-token.js"

# Or inline for simple cases:
$ tat run tests.json --env-cmd \
    "node -e \"console.log(JSON.stringify({token:process.env.API_TOKEN}))\""

Strategy by Scenario

CI Integration

Use JUnit output for CI systems. Here's a GitHub Actions example:

name: API Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm i -g @nanotiny/tiny-api-test@latest
      - run: tat run tests.tat.json --output junit --out results.xml
      - uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: results.xml

VS Code Extension

Get Test Explorer integration, CodeLens, editor support, and prompts for missing capture-derived values during isolated single-test runs:

$ code --install-extension nanotiny.tat-test-runner

Agent Skill (tat-create)

tat is agent-friendly. Install the tat-create skill to let AI coding assistants like Claude Code, Copilot CLI, or Gemini CLI generate .tat.json and .tat.yml files from your API specs, OpenAPI/Swagger docs, endpoint descriptions, or request/response examples:

$ npx skills add https://github.com/nanotinydev/tat-skills

Once installed, prompt your assistant with something like:

# Example prompt for your AI assistant:
Use tat-create to generate a tat test file from this API specification.
Include login, get user profile, and create order flows.
Use YAML format and add assertions for status codes and key response fields.
If authentication is required, create a setup hook and reuse the token.

The skill handles suites, requests, assertions, captures, and authentication flows — turning your API spec into runnable tests in seconds.