Writing a test case is not hard, you just have to provide the system will the info it needs to run the test and check to see if the result is what was expected. It is your job to fill in the NAME, DESCRIPTION, COMMANDS, and EXPECTED_RESULT fields in the following template.
test NAME DESCRIPTION {
COMMANDS
} EXPECTED_RESULT
Don't worry if any of that looks confusing at first. It is really quite
simple once you get the hang of it.
The NAME
field is a unique identifier for this test
case. It is critically important that the name be unique. Typically,
tests names include some meaningful prefix and the a number which
is incremented as tests are added. For example, a test for the
% svn help
command might be named client-help-1.
If you are adding tests to an existing tests.tcl
file,
use the naming convention other tests cases in that file use.
Otherwise, pick a set of names that you think makes sense. The
maintainers will just rename submitted tests cases if they
don't like the names you picked.
The DESCRIPTION
field is simply a string of {} delimited
text that explains what the test is actually checking for. It is the tests
writer's responsibility to explain why the test does what it does
in the DESCRIPTION
field. Don't skimp on the description,
your test will surely be clear to you it is future maintainers that
you will help by writing a good description.
The COMMANDS
field is a set of Tcl commands that return
a result. The exact Tcl commands you will be using will depend on
what you are testing and which helper commands are available.
We will avoid trying to describe specific Tcl commands here
and continue to focus on the test framework itself.
The EXPECTED_RESULT
field is a string that will be compared
to the result of running the COMMANDS
. A test passes when
the expected result exactly matches the result of running the commands.
If the tests results do not exactly match, the tests will fail.
In the following example, the svn client is tested. This test assumes
that the variable help
has already been set to the
exact textual output of the % svn help
command.
This tests also depends on a helper command named check_err
which returns a pair consisting of the exit status of the subprocess
that was invoked and the text that was printed to stdout
.
Also note that we use the standard Tcl command list
, it
returns a pair consisting of the integer 0 and the contents of the
variable help
.
test client-help-1 { print help text } {
check_err {svn help}
} [list 0 $help]
In some cases, a given test or set of test cases can not be run in
some environment. For example, you can't invoke a subprocess with
exec
on a Mac.
A developer can mark tests such that they would only be run when a
given constraint was enabled. A tests that makes use of constraints
simply has an additional CONSTRAINTS argument:
test NAME DESCRIPTION CONSTRAINTS {
COMMANDS
} EXPECTED_RESULT
The following example shows how a developer could add the
built-in execCommandExists
constraint so that
the given test case would not be run on a Mac.
test client-help-1 { print help text } execCommandExists {
check_err {svn help}
} [list 0 $help]