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 17, 2023 15.Dt KTEST 9 16.Os 17.Sh NAME 18.Nm ktest 19.Nd kernel test facility 20.Sh DESCRIPTION 21The ktest facility provides the means for writing and executing kernel 22test modules. 23A kernel test module is a kernel module that contains test functions 24designed to execute and verify some aspect of the kernel. 25You can test any aspect of the kernel for which you can create the 26requisite context, whether that be its local arguments or shared 27state. 28.Pp 29The key design idea behind ktest is to put the test in the same 30context as the code it's testing: kernel context. 31By writing tests as kernel functions it allows one to more thoroughly test 32particular aspects of the kernel. 33The ktest facility complements user-space testing by allowing targeted 34testing of the kernel that is not as easily exercised via user-space. 35.Pp 36The ktest facility provides a kernel API for creating tests as well as 37a character device for interacting with the facility from user-space. 38The latter of which should be done by way of the 39.Xr ktest 8 40command. 41.Pp 42This page concerns itself with the various kernel-side concepts of the 43ktest facility and acts as a guide to the various 9F APIs. 44.Ss The Test Triple 45A test is uniquely identified by its test triple. 46The triple is a three-level namespace comprising of the module name, 47suite name, and test name. 48Each part of the namespace is separated by the ':' character. 49.Bd -literal -offset 4m 50<module>:<suite>:<test> 51.Ed 52.Bl -tag -width 6m 53.It module 54The top of the namespace. 55If the test module is primarily focused on testing one kernel module, 56then its module name is typically named after the module-under-test. 57For example, a test module designed to test all aspects of the 58.Sy mac 59kernel module might use "mac" as the module name. 60This is merely a convention; at the end of the day the module name is 61simply a string meant to represent the general theme of its underlying 62tests. 63.It suite 64Each module consists of one or more suites. 65The suite name provides a second level of organization for grouping 66related tests. 67For example, your "mac" test module may have several tests for 68checksum-related routines. 69In that case it might help to organize all those tests under the 70"checksum" suite. 71.It test 72The name of the test. 73This can be any name you find descriptive of the test. 74For tests that focus on a single function you could use the name of 75the function-under-test with the "_test" suffix attached. 76For tests that exercise many functions do your best to make the name 77descriptive. 78The test functions are typically suffixed with "_test" to visually 79separate them from test-helper functions; and the test name is often 80the same as the test function. 81.El 82.Pp 83For a name to be considered valid it must meet the following criteria. 84.Bl -enum 85.It 86It must be 63 characters or less (the 64th byte must hold the 87.Sy NUL 88character). 89.It 90It must contain only the following ASCII 91characters: 'A-Z', 'a-z', '0-9', '.', '_'. 92.El 93.Ss The Context Handle 94The context handle provides the means through which the test 95communicates with the ktest facility. 96All test functions must conform to the following prototype. 97.Bd -literal -offset 4m 98typedef void (*ktest_fn_t)(ktest_ctx_hdl_t *ctx); 99.Ed 100.Pp 101The test interacts with 102.Fa ctx 103through various ktest routines documented in their requisite sections. 104.Ss Setting Test Results 105The ultimate goal of a test function is to return a result. 106See 107.Xr ktest_result_pass 9f 108for the complete guide to setting test results. 109.Ss Test Input 110Some tests require an input stream to test against. 111The input stream is provided at runtime by the user. 112The user may run the same test against one or more different input 113streams. 114.Pp 115This is useful when a test applies to many different scenarios with 116the same general logic. 117For example, a test that verifies a checksum routine applies to any 118byte stream; or a test that verifies TCP header parsing applies to any 119byte stream as well. 120.Pp 121Writing a test against an input stream provides several benefits. 122.Bl -enum 123.It 124It allows one test to verify innumerable scenarios, reducing the need 125to replicate test logic. 126.It 127It avoids the need to hard-code test input in the test module itself. 128.It 129With the ability to change the input stream at runtime it allows 130testing new scenarios on the spot, avoiding the need for writing a new 131test. 132.El 133.Pp 134A test that requires input must specify the 135.Sy KTEST_FLAG_INPUT 136flag when calling 137.Xr ktest_add_test 9f . 138To retrieve the input stream the test uses the 139.Xr ktest_get_input 9f 140function. 141.Ss Testing Private Functions 142A test facility that can't test private ( 143.Ft static 144) functions is going to be pretty limited. 145Some of the most useful functions to test are those that act as 146"helpers" to other, larger functions. 147These functions are often declared 148.Ft static 149and not directly accessible to the test module which is built as its 150own compilation unit. 151.Pp 152One solution would be to alter ktest to also allow declaring test 153functions inside the regular kernel modules themselves, but it 154currently does not offer that capability. 155Instead, ktest provides the 156.Xr ktest_get_fn 9f 157function for obtaining a handle to private functions. 158See that page for more detail. 159.Ss Registering Tests 160Only registered tests are accessible to the user. 161See 162.Xr ktest_create_module 9f 163for more information. 164.Ss Test Module Conventions 165There are several conventions to follow when creating a new test 166module. 167.Bl -enum 168.It 169The test module should be a miscellaneous-type module using the 170.Xr modlmisc 9S 171linkage structure. 172.It 173Test functions are prefixed with their test module name. 174.It 175Test functions are suffixed with "_test" to distinguish them from test 176helper functions. 177.It 178Test registration should happen in 179.Xr _init 9E . 180.It 181Test deregistration should happen in 182.Xr _fini 9E . 183.El 184.Sh SEE ALSO 185.Xr KT_ASSERT 9F , 186.Xr KT_ERROR 9F , 187.Xr KT_FAIL 9F , 188.Xr KT_PASS 9F , 189.Xr KT_SKIP 9F , 190.Xr ktest_add_suite 9F , 191.Xr ktest_add_test 9F , 192.Xr ktest_create_module 9F , 193.Xr ktest_get_fn 9F , 194.Xr ktest_get_input 9F , 195.Xr ktest_hold_mod 9F , 196.Xr ktest_msg_clear 9F , 197.Xr ktest_msg_prepend 9F , 198.Xr ktest_register_module 9F , 199.Xr ktest_release_mod 9F , 200.Xr ktest_unregister_module 9F , 201.Xr modlmisc 9S 202