run_manual.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3============================
  4Run Tests without kunit_tool
  5============================
  6
  7If we do not want to use kunit_tool (For example: we want to integrate
  8with other systems, or run tests on real hardware), we can
  9include KUnit in any kernel, read out results, and parse manually.
 10
 11.. note:: KUnit is not designed for use in a production system. It is
 12          possible that tests may reduce the stability or security of
 13          the system.
 14
 15Configure the Kernel
 16====================
 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_tool
 22  does not support).
 23- Wish to integrate with some existing testing systems.
 24
 25KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
 26tests can also be built by enabling their config options in our
 27``.config``. KUnit tests usually (but don't always) have config options
 28ending 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 to
 34	automatically enable all tests with satisfied dependencies. This is
 35	a good way of quickly testing everything applicable to the current
 36	config.
 37
 38	KUnit can be enabled or disabled at boot time, and this behavior is
 39	controlled by the kunit.enable kernel parameter.
 40	By default, kunit.enable is set to 1 because KUNIT_DEFAULT_ENABLED is
 41	enabled by default. To ensure that tests are executed as expected,
 42	verify that kunit.enable=1 at boot time.
 43
 44Once we have built our kernel (and/or modules), it is simple to run
 45the tests. If the tests are built-in, they will run automatically on the
 46kernel boot. The results will be written to the kernel log (``dmesg``)
 47in TAP format.
 48
 49If the tests are built as modules, they will run when the module is
 50loaded.
 51
 52.. code-block :: bash
 53
 54	# modprobe example-test
 55
 56The results will appear in TAP format in ``dmesg``.
 57
 58debugfs
 59=======
 60
 61KUnit can be accessed from userspace via the debugfs filesystem (See more
 62information about debugfs at Documentation/filesystems/debugfs.rst).
 63
 64If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is
 65mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform
 66the following actions.
 67
 68Retrieve Test Results
 69=====================
 70
 71You can use debugfs to retrieve KUnit test results. The test results are
 72accessible from the debugfs filesystem in the following read-only file:
 73
 74.. code-block :: bash
 75
 76	/sys/kernel/debug/kunit/<test_suite>/results
 77
 78The test results are printed in a KTAP document. Note this document is separate
 79to the kernel log and thus, may have different test suite numbering.
 80
 81Run Tests After Kernel Has Booted
 82=================================
 83
 84You can use the debugfs filesystem to trigger built-in tests to run after
 85boot. To run the test suite, you can use the following command to write to
 86the ``/sys/kernel/debug/kunit/<test_suite>/run`` file:
 87
 88.. code-block :: bash
 89
 90	echo "any string" > /sys/kernel/debugfs/kunit/<test_suite>/run
 91
 92As a result, the test suite runs and the results are printed to the kernel
 93log.
 94
 95However, this feature is not available with KUnit suites that use init data,
 96because init data may have been discarded after the kernel boots. KUnit
 97suites that use init data should be defined using the
 98kunit_test_init_section_suites() macro.
 99
100Also, you cannot use this feature to run tests concurrently. Instead a test
101will wait to run until other tests have completed or failed.
102
103.. note ::
104
105	For test authors, to use this feature, tests will need to correctly initialise
106	and/or clean up any data, so the test runs correctly a second time.