ktest — list and
run kernel tests
ktest list |
[-H] [[-p]
-o field[,...]]
[triple...] |
ktest run |
[-H] [[-p]
-o field[,...]] [-i
input] triple... |
ktest run-file |
[-H] [[-p]
-o field[,...]]
[runfile] |
The ktest facility provides in situ kernel
testing by running test code in kernel context; essentially unit tests for
the kernel. The ktest command is used to list or run
registered kernel tests. The ktest command interacts
with the in-kernel ktest facility by way of the
/dev/ktest pseudo device. A process must run in the
Global Zone and have the
PRIV_SYS_DEVICES
privilege in order to access the device.
The following is a list of output fields used by the
ktest command along with their meanings.
- MODULE
- The module name of the test. This is typically the same name as the
module-under-test.
- SUITE
- The suite name of the test.
- TEST
- The name of the test.
- INPUT
- For the
list
command this indicates if the test requires an input stream: [Y]es or
[N]o. For the run and run-file
commands it is the path to the input stream.
- LINE
- The source code line number that produced the test
RESULT. All PASS and
NONE results have a value of 0. Upon detection of
multiple results this value indicates the line that overwrote the previous
result and the RESULT field contains a message with the
line number of the previous result. This field applies only to the
run and run-file commands.
- RESULT
- The test result. The TEST RESULTS section explains the
different types of results. This field applies only to the
run and run-file commands.
- REASON
- Additional context when the test result is one of FAIL,
ERROR, or SKIP. This field applies
only to the run and run-file
commands.
The different types of results that a test can produce.
- PASS
- The test passed.
- FAIL
- The test had a logical failure (one of its assertions failed).
- ERROR
- The test had an unexpected, non-logical error. This is typically caused by
a failure to acquire resources or an error attempting some operation that
is tangential to the logic under test.
- SKIP
- The test decided to skip itself because it lacks the context required to
run the test. For example, some type of missing resource or hardware.
- NONE
- The test failed to produce a result. This is a bug in the test and should
be fixed.
The following is a list of options shared across all subcommands.
This field applies only to the run and
run-file commands.
-H
Omit column headers when printing output.
-o field[,...]
A case-insensitive, comma-separated list of output
fields to display.
-p
Display in a machine-parsable format and elide test
stats output when executing the run or
run-file commands. The -o option is
required with -p.
ktest help
Print command usage.
ktest list [-H]
[[-p] -o
field[,...]] [triple...]
List all registered tests. One or more triples may
be specified to narrow the listing.
ktest run [-H]
[[-p] -o
field[,...]] [-i
file] triple...
Run registered tests. One or more triples may be
specified to limit which tests are run. At least one triple must be specified.
-i file
Specify a file to act as the
input stream for all tests requiring one.
ktest run-file
[-H] [[-p]
-o field[,...]]
[runfile]
Run the tests specified by the
runfile. If no runfile is
specified, then use stdin as the contents of the
runfile.
The following exit values are returned:
- 0
- Successful completion of the command. For the run and
run-file commands this also indicates that all tests
produced a PASS or SKIP result.
- 1
- An error occurred while executing the command. For the
run and run-file commands this also
indicates that one or more tests produced a result other than PASS or
SKIP.
- 2
- An invalid combination of command line options or arguments were
specified.
List all tests registered with the ktest framework.
Run all tests registered with the ktest framework.
This example runs only tests registered under the
mac test module. This includes all suites under the
mac module and all tests under each suite.
Executes the run file named
mac.runfile
and outputs the results in parsable format to stdout. This is useful for
integrating ktest into a larger testing framework.
ktest run-file -Hpo result,module,suite,test,input,line,reason mac.runfile
Execute a specific test which requires an input stream.
ktest run -i data.pcap mac:checksum:mac_sw_cksum_ipv4_snoop_test
The command syntax is Uncommitted. The output
format is Uncommitted.