Provided by: zfs-test_0.8.3-1ubuntu12.17_amd64 
NAME
run - find, execute, and log the results of tests
SYNOPSIS
run [-dgq] [-o outputdir] [-pP script] [-t seconds] [-uxX username]
pathname ...
run -w runfile [-gq] [-o outputdir] [-pP script] [-t seconds]
[-uxX username] pathname ...
run -c runfile [-dq]
run [-h]
DESCRIPTION
The run command has three basic modes of operation. With neither the -c nor the -w option,
run processes the arguments provided on the command line, adding them to the list for this
run. If a specified pathname is an executable file, it is added as a test. If a specified
pathname is a directory, the behavior depends upon the -g option. If -g is specified, the
directory is treated as a test group. See the section on "Test Groups" below. Without the
-g option, run simply descends into the directory looking for executable files. The tests
are then executed, and the results are logged.
With the -w option, run finds tests in the manner described above. Rather than executing
the tests and logging the results, the test configuration is stored in a runfile which can
be used in future invocations, or edited to modify which tests are executed and which
options are applied. Options included on the command line with -w become defaults in the
runfile.
With the -c option, run parses a runfile, which can specify a series of tests and test
groups to be executed. The tests are then executed, and the results are logged.
Test Groups
A test group is comprised of a set of executable files, all of which exist in one
directory. The options specified on the command line or in a runfile apply to individual
tests in the group. The exception is options pertaining to pre and post scripts, which act
on all tests as a group. Rather than running before and after each test, these scripts are
run only once each at the start and end of the test group.
Test Execution
The specified tests run serially, and are typically assigned results according to exit
values. Tests that exit zero and non-zero are marked "PASS" and "FAIL" respectively. When
a pre script fails for a test group, only the post script is executed, and the remaining
tests are marked "SKIPPED." Any test that exceeds its timeout is terminated, and marked
"KILLED."
By default, tests are executed with the credentials of the run script. Executing tests
with other credentials is done via sudo(1m), which must be configured to allow execution
without prompting for a password. Environment variables from the calling shell are
available to individual tests. During test execution, the working directory is changed to
outputdir.
Output Logging
By default, run will print one line on standard output at the conclusion of each test
indicating the test name, result and elapsed time. Additionally, for each invocation of
run, a directory is created using the ISO 8601 date format. Within this directory is a
file named log containing all the test output with timestamps, and a directory for each
test. Within the test directories, there is one file each for standard output, standard
error and merged output. The default location for the outputdir is /var/tmp/test_results.
Runfiles
The runfile is an ini style configuration file that describes a test run. The file has
one section named "DEFAULT," which contains configuration option names and their values in
"name = value" format. The values in this section apply to all the subsequent sections,
unless they are also specified there, in which case the default is overridden. The
remaining section names are the absolute pathnames of files and directories, describing
tests and test groups respectively. The legal option names are:
outputdir = pathname
The name of the directory that holds test logs.
pre = script
Run script prior to the test or test group.
pre_user = username
Execute the pre script as username.
post = script
Run script after the test or test group.
post_user = username
Execute the post script as username.
quiet = [True|False]
If set to True, only the results summary is printed to standard out.
tests = ['filename' [,...]]
Specify a list of filenames for this test group. Only the basename of the absolute
path is required. This option is only valid for test groups, and each filename must be
single quoted.
timeout = n
A timeout value of n seconds.
user = username
Execute the test or test group as username.
OPTIONS
The following options are available for the run command.
-c runfile
Specify a runfile to be consumed by the run command.
-d
Dry run mode. Execute no tests, but print a description of each test that would have
been run.
-g
Create test groups from any directories found while searching for tests.
-o outputdir
Specify the directory in which to write test results.
-p script
Run script prior to any test or test group.
-P script
Run script after any test or test group.
-q
Print only the results summary to the standard output.
-t n
Specify a timeout value of n seconds per test.
-u username
Execute tests or test groups as username.
-w runfile
Specify the name of the runfile to create.
-x username
Execute the pre script as username.
-X username
Execute the post script as username.
EXAMPLES
Example 1 Running ad-hoc tests.
This example demonstrates the simplest invocation of run.
% run my-tests
Test: /home/jkennedy/my-tests/test-01 [00:02] [PASS]
Test: /home/jkennedy/my-tests/test-02 [00:04] [PASS]
Test: /home/jkennedy/my-tests/test-03 [00:01] [PASS]
Results Summary
PASS 3
Running Time: 00:00:07
Percent passed: 100.0%
Log directory: /var/tmp/test_results/20120923T180654
Example 2 Creating a runfile for future use.
This example demonstrates creating a runfile with non default options.
% run -p setup -x root -g -w new-tests.run new-tests
% cat new-tests.run
[DEFAULT]
pre = setup
post_user =
quiet = False
user =
timeout = 60
post =
pre_user = root
outputdir = /var/tmp/test_results
[/home/jkennedy/new-tests]
tests = ['test-01', 'test-02', 'test-03']
EXIT STATUS
The following exit values are returned:
0
Successful completion.
1
An error occurred.
SEE ALSO
sudo(1m)
23 Sep 2012 run(1)