Package testscript provides support for defining filesystem-based tests by
creating scripts in a directory.
To invoke the tests, call testscript.Run. For example:
A testscript directory holds test scripts *.txt run during 'go test'.
Each script defines a subtest; the exact set of allowable commands in a
script are defined by the parameters passed to the Run function.
To run a specific script foo.txt
where TestName is the name of the test that Run is called from.
To define an executable command (or several) that can be run as part of the script,
call RunMain with the functions that implement the command's functionality.
The command functions will be called in a separate process, so are
free to mutate global variables without polluting the top level test binary.
In general script files should have short names: a few words, not whole sentences.
The first word should be the general category of behavior being tested,
often the name of a subcommand to be tested or a concept (vendor, pattern).
Each script is a text archive (go doc github.com/rogpeppe/testscript//txtar).
The script begins with an actual command script to run
followed by the content of zero or more supporting files to
create in the script's temporary file system before it starts executing.
As an example:
Each script runs in a fresh temporary work directory tree, available to scripts as $WORK.
Scripts also have access to these other environment variables:
The environment variable $exe (lowercase) is an empty string on most
systems, ".exe" on Windows.
The script's supporting files are unpacked relative to $WORK
and then the script begins execution in that
directory as well. Thus the example above runs in $WORK
with $WORK/hello.txt containing the listed contents.
The lines at the top of the script are a sequence of commands to be
executed by a small script engine in the testscript package (not the system
shell). The script stops and the overall test fails if any particular
command fails.
Each line is parsed into a sequence of space-separated command words,
with environment variable expansion and # marking an end-of-line comment.
Adding single quotes around text keeps spaces in that text from being
treated as word separators and also disables environment variable
expansion. Inside a single-quoted block of text, a repeated single
quote indicates a literal single quote, as in:
A line beginning with # is a comment and conventionally explains what is
being done or tested at the start of a new phase in the script.
A special form of environment variable syntax can be used to quote
regexp metacharacters inside environment variables. The "@R" suffix
is special, and indicates that the variable should be quoted.
The command prefix ! indicates that the command on the rest of the line
(typically go or a matching predicate) must fail, not succeed. Only certain
commands support this prefix. They are indicated below by [!] in the synopsis.
The command prefix [cond] indicates that the command on the rest of the line
should only run when the condition is satisfied. The predefined conditions are:
A condition can be negated: [!short] means to run the rest of the line
when testing.Short() is false.
Additional conditions can be added by passing a function to Params.Condition.
The predefined commands are:
- chmod mode file
[!] exec program [args...] [&]
Run the given executable program with the arguments.
It must (or must not) succeed.
Note that 'exec' does not terminate the script (unlike in Unix shells).
If the last token is '&', the program executes in the background. The standard
output and standard error of the previous command is cleared, but the output
of the background process is buffered — and checking of its exit status is
delayed — until the next call to 'wait', 'skip', or 'stop' or the end of the
test. At the end of the test, any remaining background processes are
terminated using os.Interrupt (if supported) or os.Kill.
Standard input can be provided using the stdin command; this will be
cleared after exec has been called.
When TestScript runs a script and the script fails, by default TestScript shows
the execution of the most recent phase of the script (since the last # comment)
and only shows the # comments for earlier phases. For example, here is a
multi-phase script with a bug in it (TODO: make this example less go-command
specific):
The bug is that the final phase installs p11 instead of p1. The test failure looks like:
Note that the commands in earlier phases have been hidden, so that the relevant
commands are more easily found, and the elapsed time for a completed phase
is shown next to the phase heading. To see the entire execution, use "go test -v",
which also adds an initial environment dump to the beginning of the log.
Note also that in reported output, the actual name of the per-script temporary directory
has been consistently replaced with the literal string $WORK.
If Params.TestWork is true, it causes each test to log the name of its $WORK directory and other
environment variable settings and also to leave that directory behind when it exits,
for manual debugging of failing tests: