97 lines
1.9 KiB
Markdown
97 lines
1.9 KiB
Markdown
# shout
|
|
|
|
`shout` is kinda like really basic integration testing for your cli.
|
|
|
|
Write `.shout` files that look like shell sessions and run `shout` to test 'em.
|
|
|
|
## Install
|
|
|
|
```
|
|
bun install -g @because/shout
|
|
```
|
|
|
|
## Features
|
|
|
|
Everything you could ever ask for:
|
|
|
|
```
|
|
$ echo hello
|
|
hello
|
|
|
|
$ brew --version
|
|
Homebrew 5...
|
|
|
|
$ ls missing
|
|
ls: missing: No such file or directory
|
|
[1]
|
|
```
|
|
|
|
`...` matches anything — a whole line inline, or any number of lines on its own.
|
|
|
|
`[1]` after the expected output matches the exit code.
|
|
|
|
## Usage
|
|
|
|
```
|
|
$ shout test
|
|
...............
|
|
15 passed in 23ms
|
|
```
|
|
|
|
`shout test` runs code in a temp directory. `-k`/`--keep` keeps it around.
|
|
|
|
`--update` will modify `.shout` files to match reality, without running any tests.
|
|
|
|
Each line in a `.shout` file is run sequentially, unless `--parallel` is passed.
|
|
|
|
## Directives
|
|
|
|
Directives go at the top of a `.shout` file, before any commands.
|
|
|
|
### `@env`
|
|
|
|
Set environment variables for the test:
|
|
|
|
```
|
|
@env GREETING=hello
|
|
@env TARGET=world
|
|
|
|
$ echo "$GREETING $TARGET"
|
|
hello world
|
|
```
|
|
|
|
### `@setup`
|
|
|
|
Prepend commands (and `@env` directives) from another `.shout` file:
|
|
|
|
```
|
|
@setup setup-shared.shout
|
|
```
|
|
|
|
Setup commands run first and their failures abort the test. Setup files cannot themselves contain `@setup` — no nesting. If both the setup file and the user file define the same `@env`, the user file wins.
|
|
|
|
```
|
|
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
|
|
--parallel Run files in parallel
|
|
-h, --help display help for command
|
|
```
|
|
|
|
Print an example `.shout` file:
|
|
|
|
```
|
|
$ shout example
|
|
```
|