101 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3============================4Run Tests without kunit_tool5============================6 7If we do not want to use kunit_tool (For example: we want to integrate8with other systems, or run tests on real hardware), we can9include KUnit in any kernel, read out results, and parse manually.10 11.. note:: KUnit is not designed for use in a production system. It is12 possible that tests may reduce the stability or security of13 the system.14 15Configure the Kernel16====================17 18KUnit tests can run without kunit_tool. This can be useful, if:19 20- We have an existing kernel configuration to test.21- Need to run on real hardware (or using an emulator/VM kunit_tool22 does not support).23- Wish to integrate with some existing testing systems.24 25KUnit is configured with the ``CONFIG_KUNIT`` option, and individual26tests can also be built by enabling their config options in our27``.config``. KUnit tests usually (but don't always) have config options28ending in ``_KUNIT_TEST``. Most tests can either be built as a module,29or be built into the kernel.30 31.. note ::32 33 We can enable the ``KUNIT_ALL_TESTS`` config option to34 automatically enable all tests with satisfied dependencies. This is35 a good way of quickly testing everything applicable to the current36 config.37 38Once we have built our kernel (and/or modules), it is simple to run39the tests. If the tests are built-in, they will run automatically on the40kernel boot. The results will be written to the kernel log (``dmesg``)41in TAP format.42 43If the tests are built as modules, they will run when the module is44loaded.45 46.. code-block :: bash47 48 # modprobe example-test49 50The results will appear in TAP format in ``dmesg``.51 52debugfs53=======54 55KUnit can be accessed from userspace via the debugfs filesystem (See more56information about debugfs at Documentation/filesystems/debugfs.rst).57 58If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is59mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform60the following actions.61 62Retrieve Test Results63=====================64 65You can use debugfs to retrieve KUnit test results. The test results are66accessible from the debugfs filesystem in the following read-only file:67 68.. code-block :: bash69 70 /sys/kernel/debug/kunit/<test_suite>/results71 72The test results are printed in a KTAP document. Note this document is separate73to the kernel log and thus, may have different test suite numbering.74 75Run Tests After Kernel Has Booted76=================================77 78You can use the debugfs filesystem to trigger built-in tests to run after79boot. To run the test suite, you can use the following command to write to80the ``/sys/kernel/debug/kunit/<test_suite>/run`` file:81 82.. code-block :: bash83 84 echo "any string" > /sys/kernel/debugfs/kunit/<test_suite>/run85 86As a result, the test suite runs and the results are printed to the kernel87log.88 89However, this feature is not available with KUnit suites that use init data,90because init data may have been discarded after the kernel boots. KUnit91suites that use init data should be defined using the92kunit_test_init_section_suites() macro.93 94Also, you cannot use this feature to run tests concurrently. Instead a test95will wait to run until other tests have completed or failed.96 97.. note ::98 99 For test authors, to use this feature, tests will need to correctly initialise100 and/or clean up any data, so the test runs correctly a second time.101