Test Style and Nomenclature

To make finding, writing, and using KUnit tests as simple as possible, it isstrongly encouraged that they are named and written according to the guidelinesbelow. While it is possible to write KUnit tests which do not follow these rules,they may break some tooling, may conflict with other tests, and may not be runautomatically by testing systems.

It is recommended that you only deviate from these guidelines when:

  1. Porting tests to KUnit which are already known with an existing name.

  2. Writing tests which would cause serious problems if automatically run. Forexample, non-deterministically producing false positives or negatives, ortaking a long time to run.

Subsystems, Suites, and Tests

To make tests easy to find, they are grouped into suites and subsystems. A testsuite is a group of tests which test a related area of the kernel. A subsystemis a set of test suites which test different parts of a kernel subsystemor a driver.

Subsystems

Every test suite must belong to a subsystem. A subsystem is a collection of oneor more KUnit test suites which test the same driver or part of the kernel. Atest subsystem should match a single kernel module. If the code being testedcannot be compiled as a module, in many cases the subsystem should correspond toa directory in the source tree or an entry in theMAINTAINERS file. Ifunsure, follow the conventions set by tests in similar areas.

Test subsystems should be named after the code being tested, either after themodule (wherever possible), or after the directory or files being tested. Testsubsystems should be named to avoid ambiguity where necessary.

If a test subsystem name has multiple components, they should be separated byunderscores.Do not include “test” or “kunit” directly in the subsystem nameunless we are actually testing other tests or the kunit framework itself. Forexample, subsystems could be called:

ext4

Matches the module and filesystem name.

apparmor

Matches the module name and LSM name.

kasan

Common name for the tool, prominent part of the pathmm/kasan

snd_hda_codec_hdmi

Has several components (snd,hda,codec,hdmi) separated byunderscores. Matches the module name.

Avoid names as shown in examples below:

linear-ranges

Names should use underscores, not dashes, to separate words. Preferlinear_ranges.

qos-kunit-test

This name should use underscores, and not have “kunit-test” as asuffix.qos is also ambiguous as a subsystem name, because several partsof the kernel have aqos subsystem.power_qos would be a better name.

pc_parallel_port

The corresponding module name isparport_pc, so this subsystem should alsobe namedparport_pc.

Note

The KUnit API and tools do not explicitly know about subsystems. They area way of categorizing test suites and naming modules which provides asimple, consistent way for humans to find and run tests. This may changein the future.

Suites

KUnit tests are grouped into test suites, which cover a specific area offunctionality being tested. Test suites can have shared initialization andshutdown code which is run for all tests in the suite. Not all subsystems needto be split into multiple test suites (for example, simple drivers).

Test suites are named after the subsystem they are part of. If a subsystemcontains several suites, the specific area under test should be appended to thesubsystem name, separated by an underscore.

In the event that there are multiple types of test using KUnit within asubsystem (for example, both unit tests and integration tests), they should beput into separate suites, with the type of test as the last element in the suitename. Unless these tests are actually present, avoid using_test,_unittestor similar in the suite name.

The full test suite name (including the subsystem name) should be specified asthe.name member of thekunit_suite struct, and forms the base for themodule name. For example, test suites could include:

ext4_inode

Part of theext4 subsystem, testing theinode area.

kunit_try_catch

Part of thekunit implementation itself, testing thetry_catch area.

apparmor_property_entry

Part of theapparmor subsystem, testing theproperty_entry area.

kasan

Thekasan subsystem has only one suite, so the suite name is the same asthe subsystem name.

Avoid names, for example:

ext4_ext4_inode

There is no reason to state the subsystem twice.

property_entry

The suite name is ambiguous without the subsystem name.

kasan_integration_test

Because there is only one suite in thekasan subsystem, the suite shouldjust be called askasan. Do not redundantly addintegration_test. It should be a separate test suite. For example, if theunit tests are added, then that suite could be named askasan_unittest orsimilar.

Test Cases

Individual tests consist of a single function which tests a constrainedcodepath, property, or function. In the test output, an individual test’sresults will show up as subtests of the suite’s results.

Tests should be named after what they are testing. This is often the name of thefunction being tested, with a description of the input or codepath being tested.As tests are C functions, they should be named and written in accordance withthe kernel coding style.

Note

As tests are themselves functions, their names cannot conflict withother C identifiers in the kernel. This may require some creativenaming. It is a good idea to make your test functionsstatic to avoidpolluting the global namespace.

Example test names include:

unpack_u32_with_null_name

Tests theunpack_u32 function when a NULL name is passed in.

test_list_splice

Tests thelist_splice macro. It has the prefixtest_ to avoid aname conflict with the macro itself.

Should it be necessary to refer to a test outside the context of its test suite,thefully-qualified name of a test should be the suite name followed by thetest name, separated by a colon (i.e.suite:test).

Test Kconfig Entries

Every test suite should be tied to a Kconfig entry.

This Kconfig entry must:

  • be namedCONFIG_<name>_KUNIT_TEST: where <name> is the name of the testsuite.

  • be listed either alongside the config entries for the driver/subsystem beingtested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]

  • depend onCONFIG_KUNIT.

  • be visible only ifCONFIG_KUNIT_ALL_TESTS is not enabled.

  • have a default value ofCONFIG_KUNIT_ALL_TESTS.

  • have a brief description of KUnit in the help text.

If we are not able to meet above conditions (for example, the test is unable tobe built as a module), Kconfig entries for tests should be tristate.

For example, a Kconfig entry might look like:

config FOO_KUNIT_TEST        tristate "KUnit test for foo" if !KUNIT_ALL_TESTS        depends on KUNIT        default KUNIT_ALL_TESTS        help          This builds unit tests for foo.          For more information on KUnit and unit tests in general,          please refer to the KUnit documentation in Documentation/dev-tools/kunit/.          If unsure, say N.

Test File and Module Names

KUnit tests are often compiled as a separate module. To avoid conflictingwith regular modules, KUnit modules should be named after the test suite,followed by_kunit (e.g. if “foobar” is the core module, then“foobar_kunit” is the KUnit test module).

Test source files, whether compiled as a separate module or an#include in another source file, are best kept in atests/subdirectory to not conflict with other source files (e.g. fortab-completion).

Note that the_test suffix has also been used in some existingtests. The_kunit suffix is preferred, as it makes the distinctionbetween KUnit and non-KUnit tests clearer.

So for the common case, name the file containing the test suitetests/<suite>_kunit.c. Thetests directory should be placed atthe same level as the code under test. For example, tests forlib/string.c live inlib/tests/string_kunit.c.

If the suite name contains some or all of the name of the test’s parentdirectory, it may make sense to modify the source filename to reduceredundancy. For example, afoo_firmware suite could be in thefoo/tests/firmware_kunit.c file.