$ shout

Write a test

A .shout file is just a shell session. Commands start with $, everything else is expected output.

$ echo hello
hello

$ ls missing
ls: missing: No such file or directory
[1]

$ brew --version
Homebrew 5...

... matches anything — inline or across lines.

[1] asserts the exit code.

$# starts a comment line — not executed, no output expected.

$# start the server
$ my-server &
$# now test it
$ curl localhost:8080
OK

Run it

$ shout test
...............
15 passed in 23ms

Each file gets a fresh temp directory and its own /bin/sh session. State carries between commands within a file.

Update expectations

$ shout test --update

Rewrites your .shout files with the actual output. No more copy-pasting from the terminal.

Usage

$ shout test --help
Usage: shout test [options] [files...]

Run .shout test files

Arguments:
  files            Files or directories to test

Options:
  -u, --update     Rewrite expected output in-place with actual output
  -k, --keep       Keep temp directories after run
  --clean-env      Start with empty environment
  --path <path>    Prepend <path> to PATH (repeatable)
  --timeout <dur>  Per-command timeout (default: "10s")
  -v, --verbose    Print each command as it runs
  --port-from <n>  Auto-assign $PORT starting from n (default: "5400")
  --parallel       Run files in parallel
  -h, --help       display help for command

Environment

Shout sets these variables before running your commands:

HOME      → temp directory for this test file
SHOUT_DIR      → same temp directory
SHOUT_SOURCE_DIR  → directory containing the .shout file
SHOUT_PROJECT_DIR → directory where shout was invoked
PORT           → auto-assigned from 5400 (or --port-from), increments per file
PATH           → prepended with --path dirs, if any

Each file runs in its own temp directory. --clean-env starts with an empty environment instead of inheriting yours.