Commands

`clear-queue`

ztr clear-queue

Clear the queue.

`clear-summary`

ztr clear-summary

Clear results.

% ztr test true
PASS true
% ztr clear-summary
% ztr test false
FAIL false
% ztr summary
1 test total
1 (100%) failed
0 were skipped
0 passed

`help`

ztr ( --help | -h | help)

Show the manpage.

`queue`

ztr queue [[(--quiet | -q)] [--emulate <shell>] [--quiet-emulate] <arg> [<name> [<notes>]]]

Without arguments: print the queued tests.

With arguments: as ztr test but the test is queued rather than run.

`run-queue`

ztr run-queue [(--quiet | -q)]

Run all queued tests, and then clear the queue.

--quiet runs all tests with the --quiet flag.

Bootstrap and clean

If ZTR_BOOTSTRAP_FN is defined, it is run before the first queued test.

If ZTR_CLEAN_FN is defined, it is run after the last queued test.

`skip`

ztr skip [(--quiet | -q)] <arg> [<name> [<notes>]]

Skip <arg>. Pretty-print result and notes unless “quiet”.

% ztr skip my_test
SKIP my_test

`summary`

ztr summary

Pretty-print summary of results.

% ztr test true
PASS true
% ztr test false
FAIL false
% ztr summary
2 tests total
1 (50%) failed
0 were skipped
1 (50%) passed

`test`

ztr test [(--quiet | -q)] [--emulate <shell>] [--quiet-emulate] <arg> [<name> [<notes>]]

Test <arg>. Pretty-print result and notes unless “quiet”.

% ztr test true
PASS true
% ztr test false
FAIL false

In practice <arg> will most likely be a shell test expression.

% ztr test '[[ 1 == 1 ]]'
PASS [[ 1 == 1 ]]

% ztr test [[ 1 == 1 ]]
zsh: = not found # same error you get if you run `eval [[ 1 == 1 ]]`
% ztr test '[[ 1 == 1 ]]'
PASS [[ 1 == 1 ]]

<arg> can be a value, a function, a [ ] or [[ ]] test, anything that you can pass to eval.

% ztr test 'test -f myfile.txt'
% ztr test '[ -f myfile.txt ]'
% ztr test '[[ -f myfile.txt ]]'
% ztr test my_function
# etc

Choose your quote level to control what is logged.

% my_var=1
% ztr test "[[ $my_var == 1 ]]"
PASS [[ 1 == 1 ]]
% ztr test '[[ $my_var == 1 ]]'
PASS [[ $my_var == 1 ]]

A passing test has a passing exit code; a failing test has a failing exit code:

% ztr test true 'passing exit code'
PASS passing exit code
% echo $?
0
% ztr test false 'failing exit code'
FAIL failing exit code
% echo $?
1

Setup and teardown

If ZTR_SETUP_FN is defined, ZTR_SETUP_FN $ZTR_SETUP_ARGS runs before <arg> is evaluated.

If ZTR_TEARDOWN_FN is defined, ZTR_TEARDOWN_FN $ZTR_TEARDOWN_ARGS runs after <arg> is evaluated.

Quieting tests

ztr test (--quiet | -q)

Optionally silence output.

% ztr test true
PASS true
% ztr test --quiet true
% ztr test true
PASS true

Testing with shell emulation

ztr test --emulate <shell>

Use one of zsh’s emulation modes (see ”emulate” in The Z Shell Manual, chapter 17 “Shell Builtin Commands”).

For example, <shell> could be csh, ksh, or sh.

Note that zsh’s emulate builtin treats anything starting with s or b is treated as sh (the Bourne shell).

If an unsupported option is passed, zsh is the fallback. If anything other than zsh is used a note is printed after the result, indented.

The following examples rely on the fact that when called without any arguments the zsh builtin emulate prints the current emulation mode.

% ztr test '[[ $(emulate) == zsh ]]'
PASS [[ $(emulate) == zsh ]]
% ztr test --emulate sh '[[ $(emulate) == zsh ]]'
FAIL [[ $(emulate) == zsh ]]
    emulation mode: sh
% ztr test --emulate sh '[[ $(emulate) == sh ]]'
PASS [[ $(emulate) == sh ]]
    emulation mode: sh

If you regularly emulate a different shell, consider setting ZTR_EMULATION_MODE instead of always passing the --emulate option (see Configuration).

Quieting shell emulation

ztr test --quiet-emuluate

Optionally do not warn when a non-zsh shell is emulated.

% ztr test --emulate sh --quiet-emulate '[[ $(emulate) == zsh ]]'
FAIL [[ $(emulate) == zsh ]]

Named tests

ztr test <arg> <name>

Optionally pass a name as a second parameter.

% ztr test '[[ 1 == 1 ]]' '<name> appears instead of <arg>'
PASS <name> appears instead of <arg>

Test notes

ztr test <arg> <name> <notes>

Optionally pass notes as a third parameter. For example, noting dependencies can help with troubleshooting. In the output notes are indented.

% cat my_tests.ztr
# --- snip ---
ztr test my_test_10
# --- snip ---
ztr test my_test_20 my_test_20 'Dependencies: my_test_10'
# --- snip ---
ztr test my_test_30 my_test_30 'Dependencies: my_test_10'
# --- snip ---

% ./my_tests.ztr
# --- snip ---
FAIL my_test_10
# --- snip ---
FAIL my_test_20
    'Dependencies: my_test_10'
# --- snip ---
FAIL my_test_30
    'Dependencies: my_test_10'
# Ok let's see if fixing my_test_10 fixes my_test_20 and my_test_30

`version`

ztr ( --version | -v | version )

Print the command name and current version.

Usage

Reference