KTEST(8) Maintenance Commands and Procedures KTEST(8)
NAME
ktest - list and run kernel tests
SYNOPSIS
ktest help ktest list [
-H] [[
-p]
-o field[,...]] [
triple...]
ktest run [
-H] [
-n] [[
-p]
-o field[,...]] [-i
input]
triple... ktest load [
-a] [
name]
ktest unload [
-a] [
name]
DESCRIPTION
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.
SUBCOMMANDS
ktest help Print command usage.
The
list and
run subcommands share the options described in
OUTPUT OPTIONS.
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] [
-n] [[
-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.
-n Omit tests which require input when none provided via
-i.
ktest load [
-a] [
name]
Load one or more ktest modules to make their tests available to
list and
run.
-a Load all available modules
name Load a specific module
ktest unload [
-a] [
name]
Unload one or more ktest modules.
-a Unload all modules
name Unoad a specific module
OUTPUT
Available tests and the results of running said tests are emitted by
the
list and
run commands, respectively.
OPTIONS
Output from the
list and
run commands is controlled by the following
options:
-H Omit column headers when printing output.
-o field[,...]
A case-insensitive, comma-separated list of output fields
to display.
The available fields and their contents are described in
FIELDS section below.
-p Display in a machine-parsable format and elide test stats
output when executing the
run command.
The
-o option is required with
-p.
FIELDS
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 command, it
is the path to the input stream.
The following fields are only applicable to the
run command.
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.
RESULT The test result. The
TEST RESULTS section explains the
different types of results.
REASON Additional context when the test result is one of
FAIL,
ERROR, or
SKIP.
TEST RESULTS
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.
EXIT STATUS
The following exit values are returned:
0 Successful completion of the command. For the
run command,
this also indicates that all tests produced a PASS or SKIP
result.
1 An error occurred while executing the command. For the
run command, 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.
EXAMPLES
List all Tests
List all tests registered with the ktest framework.
ktest list
Run all Tests
Run all tests registered with the ktest framework.
ktest run '*'
Run specific test module
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.
ktest run 'mac::'
Run a test with an input file
Execute a specific test which requires an input stream.
ktest run -i data.pcap mac:checksum:mac_sw_cksum_ipv4_snoop_test
INTERFACE STABILITY
The command syntax is
Uncommitted. The output format is
Uncommitted.
illumos February 12, 2025 illumos