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