1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2025 Oxide Computer Company 13.\" 14.Dd February 12, 2025 15.Dt KTEST 8 16.Os 17.Sh NAME 18.Nm ktest 19.Nd list and run kernel tests 20.Sh SYNOPSIS 21.Nm ktest Cm help 22.Pp 23.Nm Cm list 24.Op Fl H 25.Op Oo Fl p Oc Fl o Ar field Ns Op ,... 26.Op Ar triple... 27.Pp 28.Nm Cm run 29.Op Fl H 30.Op Fl n 31.Op Oo Fl p Oc Fl o Ar field Ns Op ,... 32.Op -i Ar input 33.Ar triple... 34.Pp 35.Nm Cm load 36.Op Fl a 37.Op Ar name 38.Nm Cm unload 39.Op Fl a 40.Op Ar name 41.Sh DESCRIPTION 42The 43.Nm 44facility provides in situ kernel testing by running test code in 45kernel context; essentially unit tests for the kernel. 46The 47.Nm 48command is used to list or run registered kernel tests. 49The 50.Nm 51command interacts with the in-kernel ktest facility by way of the 52.Pa /dev/ktest 53pseudo device. 54A process must run in the Global Zone and have the 55.Sy PRIV_SYS_DEVICES 56privilege in order to access the device. 57.Sh SUBCOMMANDS 58.Nm ktest help 59.Bd -ragged -offset 2m 60Print command usage. 61.Ed 62.Pp 63The 64.Cm list 65and 66.Cm run 67subcommands share the options described in 68.Sx OUTPUT OPTIONS . 69.Pp 70.Nm Cm list 71.Op Fl H 72.Op Oo Fl p Oc Fl o Ar field Ns Op ,... 73.Op Ar triple... 74.Bd -ragged -offset 2m 75List all registered tests. 76One or more triples may be specified to narrow the listing. 77.Pp 78.Ed 79.Pp 80.Nm Cm run 81.Op Fl H 82.Op Fl n 83.Op Oo Fl p Oc Fl o Ar field Ns Op ,... 84.Op Fl i Ar file 85.Ar triple... 86.Bd -ragged -offset 2m 87Run registered tests. 88One or more triples may be specified to limit which tests are run. 89At least one triple must be specified. 90.Bl -tag -width Ds 91.It Fl i Ar file 92Specify a 93.Ar file 94to act as the input stream for all tests requiring one. 95.It Fl n 96Omit tests which require input when none provided via 97.Fl i . 98.El 99.Ed 100.Pp 101.Nm Cm load 102.Op Fl a 103.Op Ar name 104.Bd -ragged -offset 2m 105Load one or more ktest modules to make their tests available to 106.Cm list 107and 108.Cm run . 109.Bl -tag -width Ds 110.It Fl a 111Load all available modules 112.It Ar name 113Load a specific module 114.El 115.Ed 116.Pp 117.Nm Cm unload 118.Op Fl a 119.Op Ar name 120.Bd -ragged -offset 2m 121Unload one or more ktest modules. 122.Bl -tag -width Ds 123.It Fl a 124Unload all modules 125.It Ar name 126Unoad a specific module 127.El 128.Ed 129.Sh OUTPUT 130Available tests and the results of running said tests are emitted by the 131.Cm list 132and 133.Cm run 134commands, respectively. 135.Ss OPTIONS 136Output from the 137.Cm list 138and 139.Cm run 140commands is controlled by the following options: 141.Bl -tag -width Ar 142.It Fl H 143Omit column headers when printing output. 144.It Fl o Ar field Ns Op ,... 145A case-insensitive, comma-separated list of output fields to display. 146.Pp 147The available fields and their contents are described in 148.Sx FIELDS 149section below. 150.It Fl p 151Display in a machine-parsable format and elide test stats output when 152executing the 153.Cm run 154command. 155.Pp 156The 157.Fl o 158option is required with 159.Fl p . 160.El 161.Ss FIELDS 162The following is a list of output fields used by the 163.Nm 164command along with their meanings. 165.Bl -tag -offset 4m -width 8m 166.It Sy MODULE 167The module name of the test. 168This is typically the same name as the module-under-test. 169.It Sy SUITE 170The suite name of the test. 171.It Sy TEST 172The name of the test. 173.It Sy INPUT 174For the 175.Sy list 176command this indicates if the test requires an input stream: [Y]es or [N]o. 177For the 178.Sy run 179command, it is the path to the input stream. 180.El 181The following fields are only applicable to the 182.Cm run 183command. 184.Bl -tag -offset 4m -width 8m 185.It Sy LINE 186The source code line number that produced the test 187.Sy RESULT . 188All 189.Sy PASS 190and 191.Sy NONE 192results have a value of 0. 193Upon detection of multiple results this value indicates the line that 194overwrote the previous result and the 195.Sy RESULT 196field contains a message with the line number of the previous result. 197.It Sy RESULT 198The test result. 199The 200.Sx TEST RESULTS 201section explains the different types of results. 202.It Sy REASON 203Additional context when the test result is one of 204.Sy FAIL , 205.Sy ERROR , 206or 207.Sy SKIP . 208.El 209.Ss TEST RESULTS 210The different types of results that a test can produce. 211.Bl -tag -offset 4m -width 8m 212.It Sy PASS 213The test passed. 214.It Sy FAIL 215The test had a logical failure (one of its assertions failed). 216.It Sy ERROR 217The test had an unexpected, non-logical error. 218This is typically caused by a failure to acquire resources or an error 219attempting some operation that is tangential to the logic under test. 220.It Sy SKIP 221The test decided to skip itself because it lacks the context required to run 222the test. 223For example, some type of missing resource or hardware. 224.It Sy NONE 225The test failed to produce a result. 226This is a bug in the test and should be fixed. 227.El 228.Sh EXIT STATUS 229The following exit values are returned: 230.Bl -tag -width indent 231.It 0 232Successful completion of the command. 233For the 234.Sy run 235command, this also indicates that all tests produced a PASS or SKIP result. 236.It 1 237An error occurred while executing the command. 238For the 239.Sy run 240command, this also indicates that one or more tests produced 241a result other than PASS or SKIP. 242.It 2 243An invalid combination of command line options or arguments were 244specified. 245.El 246.Sh EXAMPLES 247.Ss List all Tests 248List all tests registered with the ktest framework. 249.Bd -literal -offset ident 250ktest list 251.Ed 252.Ss Run all Tests 253Run all tests registered with the ktest framework. 254.Bd -literal -offset ident 255ktest run '*' 256.Ed 257.Ss Run specific test module 258This example runs only tests registered under the 259.Sy mac 260test module. 261This includes all suites under the 262.Sy mac 263module and all tests under each suite. 264.Bd -literal -offset ident 265ktest run 'mac::' 266.Ed 267.Ss Run a test with an input file 268Execute a specific test which requires an input stream. 269.Bd -literal -offset ident 270ktest run -i data.pcap mac:checksum:mac_sw_cksum_ipv4_snoop_test 271.Ed 272.Sh INTERFACE STABILITY 273The command syntax is 274.Sy Uncommitted . 275The output format is 276.Sy Uncommitted . 277