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] [[-p] -o field[,...]] [-i input] triple...

ktest run-file [-H] [[-p] -o field[,...]] [runfile]

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.

OUTPUT 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 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.

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.

OPTIONS

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.

SUBCOMMANDS

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.

EXIT STATUS

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.

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::'

Execute a run file

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

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 13, 2023 illumos