shtst
is a command-line tool for testing command-line programs
against a simple specification of their expected output and exit code
given certain options and input.
It is inspired by (and similar to) shelltestrunner.
# '#' starts a comment line; blank lines are ignored
# '$' starts a command line
$ true
# '?' specifies the expected return code [default: 0]
$ false
? 1
# '>' starts a stdout specification (which ends at the first line that
# is either blank or starts with a '#', '$', '?', '<', or '>')
$ echo foo
>
foo
# '<' starts an input specification (which ends the same way)
$ cat
<
foo
bar
>
foo
bar
# input from the previous command (if any) is reused if not specified
$ wc -l
2
# prefixing the input/output lines with '|' allows blank lines and
# other input/output that would otherwise end the specification (and
# lines that start with '|')
$ printf "foo\n\n<>\n"
>
|foo
|
|<>
# instead of literal lines of output, you can provide a regex
# (delimited by '/' and optionally followed by flags: 'i' for case
# insensitive, 'm' for multiline, and 's' for dotall) immediately
# after '>' or '>2'
$ printf "Line 1 foo\nLine 2 bar\nLine 3 baz\n"
> /^line 1.*^line 2/ims
# use '>2' instead of '>' to specify stderr instead of stdout
$ cat --oops
>2 /unrecognized option/
? 1
# use a '!' before the exit code to negate the test
$ echo 'does not return 42'
? !42
# no stdout/stderr specification means anything is accepted;
# explicitly use an empty specification if necessary
$ echo OK
>2
A test case always starts with a command line. All input/output/exit code specifications belong to the preceding command line. With one exception: you can specify input before the first command, which will then be used for all subsequent commands until the next input specification.
<
foo
bar
baz
$ cat
>
foo
bar
baz
$ wc -l
> 3
$ shtst --help
NB: the syntax for the environment variable changed in click >= 8.0,
use e.g. source_bash
instead of bash_source
for older versions.
For Bash, add this to ~/.bashrc
:
eval "$(_SHTST_COMPLETE=bash_source shtst)"
For Zsh, add this to ~/.zshrc
:
eval "$(_SHTST_COMPLETE=zsh_source shtst)"
For Fish, add this to ~/.config/fish/completions/shtst.fish
:
eval (env _SHTST_COMPLETE=fish_source shtst)
$ apt install python3-click
$ pip install shtst
NB: depending on your system you may need to use e.g. pip3 --user
instead of just pip
.
NB: this installs the latest development version, not the latest release.
$ git clone https://github.com/obfusk/shtst.git
$ cd shtst
$ pip install -e .
NB: you may need to add e.g. ~/.local/bin
to your $PATH
in order
to run shtst
.
To update to the latest development version:
$ cd shtst
$ git pull --rebase