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.