## 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

## Setup & teardown

Use `@setup` to share commands across test files. Use `@teardown` to clean up after tests — it runs regardless of pass/fail.

    # setup.shout
    export DB_URL=sqlite:data/test.db
    @teardown rm -f "$SHOUT_PROJECT_DIR/data/test.db"

    @setup setup.shout
    @teardown rm -f /tmp/extra-cleanup

    $ create-db && run-tests
    ...

`@teardown` can appear in both `.shout` files and setup files. Teardown failures produce warnings but don't affect test results.

## 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")
      -t, --filter     Only run files matching <pattern> (substring match)
      -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.