shell output tester
-shell output tester
+$ curl -fsSL https://because.sh/shout | sh
+
A .shout file is just a shell session. Commands start with $, everything else is expected output.
$ echo hello
+
+
+
+
+ ✓ Write a test
+ 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
hello
$ ls missing
@@ -193,55 +299,79 @@
[1]
$ brew --version
-Homebrew 5...
- ... matches anything — inline or across lines.
- [1] asserts the exit code.
- # at the start of a line is a comment — not executed, no output expected.
- # start the server
+Homebrew 5...
+
+# start the server
$ my-server &
-# now test it
$ curl localhost:8080
OK
- If expected output starts with #, escape it with \#. # elsewhere in output is literal.
-
+
+
+
+
-
- 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
+
+
+
+ ✓ 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
@@ -269,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.
@@ -282,5 +412,13 @@ Options:
GitHub · npm
+
+