Selection flags compose with any spec: --filter NAME (repeatable, and comma-separated for OR — --filter a,b or --filter a --filter b runs scenarios whose name contains a or b), --tag T and --skip-tag T (tags match exactly, not by substring — atago list shows the available tags), --parallel N, --fail-fast, and --rerun-failed. atago run --rerun-failed re-runs only the scenarios the previous run recorded as failed in .atago/last-failed.json, so the fix-and-recheck loop replays just the failures instead of the whole suite. While authoring, --verbose traces every command, capture, and assertion verdict — for passing scenarios too. Under --ci, a selection that matches no scenario fails the run (exit 3) rather than passing an empty suite.
snapshot matchers compare output against committed golden files; ANSI colors, temp paths, UUIDs, timestamps, ports, and CRLF are normalized so snapshots stay stable across machines. Record or refresh them with:
atago snapshot update spec.atago.yaml
For volatile patterns the built-ins do not cover — auto-increment IDs, request identifiers, epoch times — declare spec-wide scrub: rules that rewrite each regex match to a placeholder before the compare (applied after secrets: masking):
Every key a spec file accepts, generated from the committed
JSON Schema
— the same document that powers editor completion, so this reference cannot
drift from what the loader accepts. Indentation shows nesting; a type that
links (like step) is documented in its own section rather than
repeated inline.
All keys belong to spec format version 1 — the only format version so far;
version: "1" is the first line of every spec. Since is the atago release
that introduced the key (unreleased = merged to main, not yet in a tagged
release).
Spec-wide default fragments merged into every matching element at load time — authoring sugar to cut repetition. An explicitly authored value always wins; maps merge per key; a defaulted boolean cannot be turned off per element.
v0.1.0
permissions
object
The spec’s security policy.
v0.1.0
network
object
Network egress policy for the spec.
v0.1.0
allow
array of string
Hosts that scenarios may contact; egress to any other host is a policy violation (exit 6).
Named runner configurations. cmd is the implicit default for run steps; http supplies a base_url for http steps; db a dsn for query steps; ssh, grpc, and browser configure their step types.
Required. The named behaviors under test. Each scenario runs in its own isolated temporary workdir.
v0.1.0
scrub
array of objects
Declarative output-normalization rules (#137): each replaces every regex match in captured output with a literal placeholder before a snapshot is compared or written. Where secrets masks known values, scrub normalizes volatile patterns the built-in normalizers do not cover (auto-increment IDs, request identifiers, custom timestamps). Rules apply in order, after secret masking and before the built-in ANSI/UUID/timestamp/port/path normalization.
v0.5.0
pattern
string
Required. A Go (RE2) regular expression; every match is replaced. Required.
v0.5.0
placeholder
string
Literal replacement text (no $1 expansion), e.g. “<ID>”. Defaults to empty, which deletes matches.
v0.5.0
secrets
array of string
Environment variable names whose VALUES are masked as *** in output, reports, and snapshots.
v0.1.0
suite
object
Required. Groups the file’s scenarios under a name, with optional suite-wide env, default step timeout, and one-time setup/teardown steps.
v0.1.0
env
map of string
Environment exported to every scenario, setup, and teardown step (a scenario’s own env wins per key).
v0.2.0
name
string
Required. The suite name shown in reports and generated docs.
Steps run ONCE before any scenario, in order, inside the ${suitedir} scratch dir. Allowed kinds: fixture, run, store, assert, and service (a suite-wide background process started at that point in the sequence). A failing setup step errors every scenario.
Steps that always run after the last scenario, while suite services are still up (services stop last, LIFO). Failures are reported but never change the suite verdict.
v0.2.0
timeout
string
Suite-level default step timeout (#17): every run/http/query/grpc step without a more specific timeout (step > runner > defaults.run > suite) is bounded by this Go duration. “0” disables. When no level configures one, a built-in 60s default applies.
v0.3.0
version
1 | 1
Required. Spec format version. Write “1” (quoted); a bare 1 is accepted for convenience — the loader coerces it to “1”.
Declarative stub HTTP servers (#24): canned routes on an ephemeral loopback port, every request recorded for the mock: assertion target; ${<name>.url} / ${<name>.port} are seeded before steps run.
v0.3.0
name
string
Required. The scenario name shown in reports; with matrix:, ${var} placeholders make each instance’s name unique.
Steps that always run after steps — pass, fail, error, or interrupt — sharing the scenario’s variable store. For external side effects the isolated workdir cannot undo. A teardown failure is reported but does not change the scenario’s verdict.
Runs a command inside a real pseudo-terminal and drives it with a declarative expect/send session — for prompts, REPLs, and TUIs. Works on Linux, macOS, and Windows (ConPTY).
Start the child from an empty environment instead of inheriting the host environment (#16). On Windows a small system-critical set (SystemRoot, SystemDrive, TEMP, TMP, PATHEXT) is always retained.
v0.3.0
command
string
Required. The program to run. Tokenized and exec’d directly unless shell: true.
v0.1.0
cwd
string
Working directory relative to the scenario workdir (default: the workdir itself).
v0.1.0
env
map of string
Environment variables for the child process, layered over the scenario env; values get ${name} expansion.
v0.1.0
pass_env
array of string
Host variables copied into the cleared environment (#16). Requires clear_env: true; unset host variables are skipped.
Re-runs the command until the until assertion passes — declarative polling for async behavior. The last attempt’s result is what later steps observe.
v0.1.0
runner
string
Names a declared runner to execute through (e.g. an ssh runner runs the command remotely). Default: local execution.
v0.1.0
sandbox_home
boolean
Point the child’s home and per-OS config/cache/data/state dirs at ${workdir}/.atago-home so a CLI touching ~/.config, ~/.cache, or %APPDATA% runs hermetically (#71). Precedence: step env > sandbox > pass_env > host; composes with clear_env.
v0.3.0
shell
boolean
Runs the command through the shell (/bin/sh on POSIX, cmd.exe on Windows) — for pipes, redirects, and builtins.
v0.1.0
stderr_to
string
Write the command’s captured stderr to this workdir-relative file (create/truncate), without needing shell redirection.
v0.1.0
stdin
string | object
Standard input for the command (#18): a plain string (inline text), {file: path} (workdir-relative, path-confined), or {base64: data} for binary bytes.
v0.1.0
file
string
Required. Feeds the command’s stdin from a workdir-relative file.
v0.3.0
base64
string
Required. Feeds the command’s stdin with exact binary bytes, base64-encoded.
v0.3.0
stdout_to
string
Write the command’s captured stdout to this workdir-relative file (create/truncate), without needing shell redirection.
v0.1.0
timeout
string
Bounds this command as a Go duration. Precedence: step > runner > defaults.run > suite > built-in 60s.
Runs one command inside a real pseudo-terminal and drives it with a declarative expect/send session (#8) — for CLIs that branch on TTY-ness or present interactive prompts. POSIX-only at runtime; Windows reports a clear execution error.
Key
Type
Description
Since
clear_env
boolean
Start the child from an empty environment instead of inheriting the host environment (#16). On Windows a small system-critical set (SystemRoot, SystemDrive, TEMP, TMP, PATHEXT) is always retained.
v0.3.0
cols
integer
Terminal width in columns (default 80).
v0.2.0
command
string
Required. The program to run inside a real pseudo-terminal (a ConPTY on Windows). The captured transcript becomes the step’s stdout.
v0.2.0
cwd
string
Working directory relative to the scenario workdir.
v0.2.0
env
map of string
Environment variables for the pty child. The child gets TERM=xterm-256color by default; override here if needed.
v0.2.0
pass_env
array of string
Host variables copied into the cleared environment (#16). Requires clear_env: true; unset host variables are skipped.
v0.3.0
rows
integer
Terminal height in rows (default 24). Also sizes the screen: assertion’s emulator.
v0.2.0
sandbox_home
boolean
Point the pty child’s home and per-OS config/cache/data/state dirs at ${workdir}/.atago-home so a CLI touching ~/.config, ~/.cache, or %APPDATA% runs hermetically (#71).
v0.3.0
session
array of objects
Ordered expect/send script. Each entry waits for the transcript to match (expect) or types into the terminal (send). Deliberately no branching.
v0.2.0
expect
string
Waits until the transcript (scanned after the previous match) matches this Go regular expression; a never-matching expect fails when the session timeout elapses.
v0.2.0
send
string | object
Writes to the terminal: a string verbatim ("" sends EOF/^D; ${name} expansion applies) or {key: <name>} for a named key — enter, tab, esc, arrows, f1-f12, ctrl-a..ctrl-z.
Required. Browser actions run in order against one session; the value captured by the last text/eval/attribute/title action feeds the value: assert and store from.value.
v0.1.0
attribute
object
Captures an element attribute value.
v0.1.0
name
string
Required. The attribute name to capture.
v0.1.0
selector
string
Required. The element to read.
v0.1.0
check
string
Ticks the checkbox matched by the selector.
v0.1.0
click
string
Clicks the element matched by the selector.
v0.1.0
download
object
Clicks to trigger a download and captures the file using the server-suggested filename; the captured value is the final filename.
v0.1.0
click
string
Required. The element to click to start the download.
v0.1.0
dir
string
Workdir-relative directory to save into (default: the workdir root).
v0.1.0
eval
string
Evaluates a JavaScript expression and captures the result as JSON.
v0.1.0
navigate
string
Loads a URL.
v0.1.0
press
object
Presses a single key on an element.
v0.1.0
key
string
Required. The key to press (e.g. “Enter”, “Tab”, or a printable character).
v0.1.0
selector
string
Required. The element to receive the key press.
v0.1.0
screenshot
object
Writes a PNG of the page (or one element) into the workdir for file/image assertions.
v0.1.0
path
string
Required. The workdir-relative PNG path to write.
v0.1.0
selector
string
Limits the screenshot to this element (default: the whole page).
v0.1.0
select
object
Chooses an <option> in a <select>.
v0.1.0
selector
string
Required. The <select> element.
v0.1.0
value
string
Required. The option value to choose.
v0.1.0
send_keys
object
Types text into an element.
v0.1.0
selector
string
Required. The element to type into.
v0.1.0
value
string
Required. The text to type.
v0.1.0
text
string
Captures the text of the element matched by the selector.
v0.1.0
title
boolean
Captures the page title.
v0.1.0
uncheck
string
Unticks the checkbox matched by the selector.
v0.1.0
upload
object
Sets a file on an <input type=file> — no scripted file dialogs.
v0.1.0
file
string
Required. The workdir-relative file to attach; must exist.
Sends a named POSIX signal to a managed service’s process group (#23) - the race-free alternative to kill/killall for graceful-shutdown tests. POSIX-only at runtime; Windows reports a clear execution error.
Key
Type
Description
Since
service
string
Required. A service declared in the scenario’s services: list or started by a suite.setup service: step.
v0.3.0
signal
string
Required. TERM, INT, HUP, USR1, USR2, or KILL (optional SIG prefix accepted).
v0.3.0
wait
object
Block until the signaled process exits; a still-running process fails the step.
Start the child from an empty environment instead of inheriting the host environment (#16). On Windows a small system-critical set (SystemRoot, SystemDrive, TEMP, TMP, PATHEXT) is always retained.
v0.3.0
command
string
Required. The program to run. Tokenized and exec’d directly unless shell: true.
v0.1.0
cwd
string
Working directory relative to the scenario workdir.
v0.1.0
env
map of string
Environment variables, layered over the scenario env, with ${name} expansion.
v0.1.0
max_log_bytes
integer
Maximum bytes of combined stdout/stderr atago retains for this service. The oldest bytes are dropped first and the retained log starts with a truncation notice, so readiness excerpts and preserved log artifacts (which only ever need the tail) stay bounded. Omit for the 8 MiB default.
v0.10.0
name
string
Required. Identifies the service in diagnostics and signal: steps; unique per scenario.
v0.1.0
pass_env
array of string
Host variables copied into the cleared environment (#16). Requires clear_env: true; unset host variables are skipped.
v0.3.0
ready
object
How to wait until the service accepts work before steps run. When omitted, steps start as soon as the process is spawned.
v0.1.0
delay
string
Simply waits this Go duration — a last resort when no observable readiness signal exists.
v0.1.0
file
string
Ready when this workdir-relative file exists and is non-empty — the canonical pattern for a server publishing its listen address.
v0.1.0
log
string
Ready when the service’s combined stdout/stderr matches this regular expression.
v0.1.0
port
string
Ready when this TCP address (host:port) accepts a connection.
v0.1.0
store
string
Used with file: captures the ready file’s trimmed content into ${<name>} so steps can reference a dynamic address or port.
v0.1.0
timeout
string
Bounds the readiness wait as a Go duration (default “5s”).
v0.1.0
shell
boolean
Runs the command through the POSIX shell (pipes, redirects, ${}).
A declarative stub HTTP server (#24): routes match on exact method+path (query string excluded); an unmatched request answers 404 and is still recorded.
Key
Type
Description
Since
name
string
Required. Identifies the server: seeds ${<name>.url} / ${<name>.port} and is referenced by mock: asserts. Unique per scenario.
Canned responses, matched top-down on exact method+path (query string excluded; deliberately no patterns). An unmatched request answers 404 and is still recorded.
Valid after a run/pty step: pins exactly which files that step created, modified, and deleted in the scenario workdir. Each set list is exhaustive in both directions.
Inspects a generated image’s decoded properties (format, dimensions, alpha) and optionally compares its pixels against a baseline. Every set field must hold.
Asserts what the CLI under test actually sent to a declared mock server: request count, and header/body matchers on the last matching recorded request.
The rendered terminal screen of the preceding pty step (#27): the transcript replayed through a vt10x emulator, asserted as plain text (line.n = screen row).
v0.3.0
status
integer
Asserts the HTTP response status code of the preceding http step.
Requires the stream NOT to match this Go (RE2) regular expression.
v0.1.0
snapshot
string
Compares the stream against a committed golden file (spec-relative path). Volatile details (ANSI, temp paths, UUIDs, timestamps, ports, CRLF) are normalized; refresh with atago snapshot update.
Child paths (relative to path) that must exist; nested paths are allowed and confined to the directory.
v0.1.0
count
integer
Asserts the exact number of direct entries (files only under recursive: true).
v0.1.0
exists
boolean
Asserts the path exists and is a directory (false asserts it is absent).
v0.1.0
glob
string
Requires at least one entry to match this shell glob (basename match for patterns without /).
v0.1.0
ignore
array of string
Glob patterns excluded from the recursive walk and the snapshot manifest (*.log, .git/**).
v0.3.0
max_count
integer
Upper bound on the number of entries.
v0.1.0
min_count
integer
Lower bound on the number of entries.
v0.1.0
not_contains
array of string
Child paths (relative to path) that must NOT exist.
v0.1.0
path
string
Required. The directory under test, resolved against the scenario workdir when relative.
v0.1.0
recursive
boolean
Apply contains/not_contains/count/glob to the whole tree (#25): counts see files only; glob matches relative paths, or basenames for patterns without /.
v0.3.0
snapshot
string
Golden tree manifest (#25): sorted relative paths, one line per entry (dir/file sha256/link). Composes only with ignore; refresh with –update-snapshots.
Pins the exact workdir delta of the immediately preceding run/pty step (#70): which files it created, modified, and deleted. Each set field is EXHAUSTIVE in both directions (every observed path must match an entry, every entry must match a path), so modified: [] asserts “modified nothing”. An omitted field is unconstrained. Entries are workdir-relative doublestar globs, always /-separated: a single * stays within one path segment while ** crosses / at any depth (site/** covers the whole tree, dist/**/*.css composes with a suffix). A backslash escapes a literal metacharacter (\[, \?, \*) — a\[1\].txt matches the file a[1].txt; the escape is portable because entries are always /-separated.
Bounds the wall-clock time of the immediately preceding run/http/query/grpc/pty step (#31). At least one bound; lt/lte and gt/gte are mutually exclusive. Values are Go duration strings (2s, 100ms).
Key
Type
Description
Since
gt
string
Exclusive lower bound as a Go duration.
v0.3.0
gte
string
Inclusive lower bound as a Go duration.
v0.3.0
lt
string
Exclusive upper bound as a Go duration (e.g. “2s”).
Checks what the CLI under test sent to a mock server (#24): filter by path/method, pin the exact count (or require at least one match), and match header/body of the LAST matching request.
A runner is discriminated by type: only the fields for that type are allowed, so cross-type fields are rejected and editors can narrow completion (#44).
Key
Type
Description
Since
type: cmd
cwd
string
Working directory for commands run through this runner, relative to the scenario workdir.
v0.1.0
timeout
string
Default timeout for steps using this runner, as a Go duration.
v0.1.0
type
any
Selects the cmd runner: local command execution (the implicit default for run steps).
v0.1.0
type: http
base_url
string
Base URL every http step’s path is appended to.
v0.1.0
cwd
string
Unused for http runners; accepted for uniformity.
v0.1.0
timeout
string
Request timeout as a Go duration.
v0.1.0
type
any
Selects the http runner: HTTP requests from http steps.
v0.1.0
type: db
cwd
string
Unused for db runners; accepted for uniformity.
v0.1.0
driver
sqlite | sqlite3 | postgres | postgresql | mysql
Names the database/sql driver explicitly (sqlite, postgres, or mysql), overriding scheme inference from the dsn.
v0.1.0
dsn
string
Required. Data source name, e.g. “sqlite:${workdir}/app.db”, “postgres://user:pass@host/db”, or “mysql://user:pass@host:3306/db”. Pure-Go drivers are bundled.
v0.1.0
timeout
string
Statement timeout as a Go duration.
v0.1.0
type
any
Selects the db runner: SQL from query steps.
v0.1.0
type: ssh
cwd
string
Remote working directory for commands.
v0.1.0
host
string
Required. Remote host, as host or host:port (default port 22).
v0.1.0
insecure_host_key
boolean
Must be set to true to connect without a known_hosts file, explicitly disabling host-key verification.
v0.1.0
key_file
string
Path to a private key for key authentication.
v0.1.0
known_hosts
string
known_hosts file verifying the host key (recommended).
v0.1.0
password
string
Password authentication (prefer key_file, and keep the value in an env var).
v0.1.0
timeout
string
Command timeout as a Go duration.
v0.1.0
type
any
Selects the ssh runner: running commands on a remote host.
v0.1.0
user
string
Required. Login user.
v0.1.0
type: grpc
cwd
string
Unused for grpc runners; accepted for uniformity.
v0.1.0
target
string
Required. host:port of the gRPC server; the schema is resolved via server reflection.
v0.1.0
timeout
string
Call timeout as a Go duration.
v0.1.0
tls
boolean
Connect with TLS (default plaintext).
v0.1.0
type
any
Selects the grpc runner: unary gRPC calls from grpc steps.
v0.1.0
type: browser
browser_args
array of string
Extra Chrome launch flags (bare names, no leading ‘–’), e.g. ‘disable-gpu’ or ‘window-size=1280,720’.
v0.1.0
cwd
string
Unused for browser runners; accepted for uniformity.
v0.1.0
exec_path
string
Path to a specific Chrome/Chromium binary instead of the one discovered on PATH.
v0.1.0
headless
boolean
Run Chrome without a visible window (default true); set false to debug headed.
v0.1.0
timeout
string
Session timeout as a Go duration.
v0.1.0
type
any
Selects the browser runner: headless Chrome driven by cdp steps.
Spec-wide default fragments merged into every matching element at load time (#39). Authoring sugar only: an explicit value always wins, maps shallow-merge, and a boolean default is OR-ed in. Not a macro/include system.
Key
Type
Description
Since
run
object
Layered beneath every run step. command and retry are per-step and rejected here. The environment-shaping subset (env, clear_env, pass_env, sandbox_home) also layers onto pty steps, which share the same environment surface (#77); the run-only fields (runner, shell, cwd, timeout, stdin, redirects) stay per-step and never reach pty steps.
v0.1.0
clear_env
boolean
Start the child from an empty environment instead of inheriting the host environment (#16). On Windows a small system-critical set (SystemRoot, SystemDrive, TEMP, TMP, PATHEXT) is always retained.
v0.3.0
cwd
string
Default working directory for every run step.
v0.1.0
env
map of string
Default env map shallow-merged beneath every run step’s own env.
v0.1.0
pass_env
array of string
Host variables copied into the cleared environment (#16). Requires clear_env: true; unset host variables are skipped.
v0.3.0
runner
string
Default runner name for every run step.
v0.1.0
sandbox_home
boolean
Point the child’s home and per-OS config/cache/data/state dirs at ${workdir}/.atago-home so a CLI touching ~/.config, ~/.cache, or %APPDATA% runs hermetically (#71). Precedence: step env > sandbox > pass_env > host; composes with clear_env.
v0.3.0
shell
boolean
Default shell for every run step (an authored shell: false on a step cannot override a defaulted true).
v0.1.0
timeout
string
Default timeout for every run step (a step’s own timeout wins).
v0.1.0
scenario
object
Scenario-level defaults. Only env is supported; it shallow-merges beneath each scenario’s own env.
v0.1.0
env
map of string
Env map shallow-merged beneath every scenario’s own env.
v0.1.0
service
object
Layered beneath every service. name and command identify a service and are rejected here; a whole ready probe is copied in when a service declares none.
v0.1.0
clear_env
boolean
Start the child from an empty environment instead of inheriting the host environment (#16). On Windows a small system-critical set (SystemRoot, SystemDrive, TEMP, TMP, PATHEXT) is always retained.
v0.3.0
cwd
string
Default working directory for every service.
v0.1.0
env
map of string
Default env map for every service.
v0.1.0
pass_env
array of string
Host variables copied into the cleared environment (#16). Requires clear_env: true; unset host variables are skipped.
v0.3.0
ready
object
Default readiness probe for every service (a service’s own ready wins).
A JSON Schema lives at schema/atago.schema.json. With the YAML language server you get completion and validation as you type — step types, every matcher, and the ${workdir} / ${env:NAME} / ${name} / $${...} expansion rules. atago init and atago record already emit this header as the first line of every generated spec, so scaffolded specs get completion out of the box. To add it to an existing spec, use the absolute URL (it resolves in any project, unlike a repo-relative path):