Assertions

Hone provides a rich set of assertions for verifying command output, exit codes, timing, and file contents.

Output Assertions

stdout

Assert on the standard output of the most recent (or named) command:

# Contains - check if output includes text
ASSERT stdout contains "success"
ASSERT stdout contains "Hello, World!"

# Equals - exact match
ASSERT stdout == "exact output"
ASSERT stdout != "not this"

# Regex - pattern matching
ASSERT stdout matches /version \d+\.\d+\.\d+/
ASSERT stdout matches /hello world/i  # case insensitive

stderr

Assert on the standard error output:

# Same operators work for stderr
ASSERT stderr contains "warning"
ASSERT stderr == ""
ASSERT stderr matches /error: .*/

Raw Output

By default, ANSI escape codes are stripped from output. Use .raw to preserve them:

# Access raw output with ANSI codes preserved
ASSERT stdout.raw contains "\x1b[32m"

Exit Code Assertions

Verify the exit status of commands:

# Check exit status
ASSERT exit_code == 0
ASSERT exit_code != 0
ASSERT exit_code == 42

Duration Assertions

Check how long a command took to execute. Supports ms, s, m, and h units:

# Time constraints
ASSERT duration < 500ms
ASSERT duration <= 2s
ASSERT duration < 1m

File Assertions

Existence

Check if a file exists:

# Check file existence
ASSERT file "output.txt" exists
ASSERT file "/tmp/cache.json" exists

Content

Assert on file contents using the same operators as stdout:

# Check file contents
ASSERT file "config.yaml" contains "enabled: true"
ASSERT file "output.json" == '{"status": "ok"}'
ASSERT file "version.txt" matches /v\d+\.\d+/

Named Run Targets

When you have multiple RUN commands, use named runs to assert on specific ones:

RUN compile: gcc main.c -o main
RUN test: ./main --test

# Reference specific commands
ASSERT compile.exit_code == 0
ASSERT compile.stdout contains "compiled"
ASSERT compile.duration < 30s

ASSERT test.exit_code == 0
ASSERT test.stdout contains "PASSED"

Assertion Operators

Operator	Description	Example
contains	Substring match	stdout contains "ok"
==	Exact equality	exit_code == 0
!=	Not equal	stderr != ""
matches	Regex pattern	stdout matches /v\d+/
exists	File exists	file "x.txt" exists
<	Less than	duration < 5s
<=	Less than or equal	duration <= 10s

Next Steps

Learn about configuration options in the Configuration guide.