Documentation/dev-tools/kunit/run_manual.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============================
   4 Run Tests without kunit_tool
   5 ============================
   6
   7 If we do not want to use kunit_tool (For example: we want to integrate
   8 with other systems, or run tests on real hardware), we can
   9 include 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
  15 Configure the Kernel
  16 ====================
  17
  18 KUnit 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
  25 KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
  26 tests can also be built by enabling their config options in our
  27 ``.config``. KUnit tests usually (but don't always) have config options
  28 ending in ``_KUNIT_TEST``. Most tests can either be built as a module,
  29 or 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 Once we have built our kernel (and/or modules), it is simple to run
  39 the tests. If the tests are built-in, they will run automatically on the
  40 kernel boot. The results will be written to the kernel log (``dmesg``)
  41 in TAP format.
  42
  43 If the tests are built as modules, they will run when the module is
  44 loaded.
  45
  46 .. code-block :: bash
  47
  48         # modprobe example-test
  49
  50 The results will appear in TAP format in ``dmesg``.
  51
  52 debugfs
  53 =======
  54
  55 KUnit can be accessed from userspace via the debugfs filesystem (See more
  56 information about debugfs at Documentation/filesystems/debugfs.rst).
  57
  58 If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is
  59 mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform
  60 the following actions.
  61
  62 Retrieve Test Results
  63 =====================
  64
  65 You can use debugfs to retrieve KUnit test results. The test results are
  66 accessible from the debugfs filesystem in the following read-only file:
  67
  68 .. code-block :: bash
  69
  70         /sys/kernel/debug/kunit/<test_suite>/results
  71
  72 The test results are printed in a KTAP document. Note this document is separate
  73 to the kernel log and thus, may have different test suite numbering.
  74
  75 Run Tests After Kernel Has Booted
  76 =================================
  77
  78 You can use the debugfs filesystem to trigger built-in tests to run after
  79 boot. To run the test suite, you can use the following command to write to
  80 the ``/sys/kernel/debug/kunit/<test_suite>/run`` file:
  81
  82 .. code-block :: bash
  83
  84         echo "any string" > /sys/kernel/debugfs/kunit/<test_suite>/run
  85
  86 As a result, the test suite runs and the results are printed to the kernel
  87 log.
  88
  89 However, this feature is not available with KUnit suites that use init data,
  90 because init data may have been discarded after the kernel boots. KUnit
  91 suites that use init data should be defined using the
  92 kunit_test_init_section_suites() macro.
  93
  94 Also, you cannot use this feature to run tests concurrently. Instead a test
  95 will 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 initialise
 100         and/or clean up any data, so the test runs correctly a second time.