A .shout file is a shell session.
Commands start with $.
Everything else is the expected output.
+Each .shout file is a session.
Commands start with $.
Everything else is expected output.
... matches anything — inline or across lines.
[1] asserts the exit code. Default expects 0.
Lines starting with # are comments.
(\# matches output starting with #.)
$ echo hello
@@ -306,43 +310,68 @@
Use @setup to share commands across test files. Use @teardown to clean up after tests — it runs regardless of pass/fail.
# setup.shout
+
+
+
+ ✓ Setup & teardown
+ Use @setup to share commands across test files.
+ Use @teardown to clean up after tests — it runs regardless of pass/fail.
+ @teardown can appear in both .shout files and setup files. Teardown failures produce warnings but don't affect test results.
+
+
+ # setup.shout
export DB_URL=sqlite:data/test.db
@teardown rm -f "$SHOUT_PROJECT_DIR/data/test.db"
- @setup setup.shout
+ @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.
-
+
+
+
-
- Macros
- Use @def to define reusable command macros.
- @def greet echo "hello world"
+
+
+
+ ✓ Macros
+ Use @def to define reusable command macros.
+ If a command matches a macro name exactly, the body is substituted. Use \ for multi-line bodies. Macros from setup files are inherited; user-file macros override them.
+
+
+ @def greet echo "hello world"
$ greet
hello world
- If a command matches a macro name exactly, the body is substituted. Use \ for multi-line bodies — the body can start on the same line or on the next continuation line. Macros from setup files are inherited; user-file macros override them.
-
+
+
+
-
- Run it
- $ shout test
+
+
+
+ ✓ Run it
+ Each file gets a fresh temp directory and its own /bin/sh session. State carries between commands within a file.
+
+
+ $ 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.
-
+
+
+
+ ✓ Update expectations
+ Rewrites your .shout files with the actual output. No more copy-pasting from the terminal.
+
+
+ $ shout test --update
+
+
+
Usage
@@ -370,12 +399,12 @@ Options:
Environment
Shout sets these variables before running your commands:
- HOME → temp directory for this test file
-SHOUT_DIR → same temp directory
+ 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
+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.