API testing in JSON/YAML.
Run in one command.

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"

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

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, and editor support:

$ 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.