start.rst 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ===============
  3. Getting Started
  4. ===============
  5. Installing dependencies
  6. =======================
  7. KUnit has the same dependencies as the Linux kernel. As long as you can build
  8. the kernel, you can run KUnit.
  9. Running tests with the KUnit Wrapper
  10. ====================================
  11. Included with KUnit is a simple Python wrapper which runs tests under User Mode
  12. Linux, and formats the test results.
  13. The wrapper can be run with:
  14. .. code-block:: bash
  15. ./tools/testing/kunit/kunit.py run
  16. For more information on this wrapper (also called kunit_tool) check out the
  17. :doc:`kunit-tool` page.
  18. Creating a .kunitconfig
  19. -----------------------
  20. If you want to run a specific set of tests (rather than those listed in the
  21. KUnit defconfig), you can provide Kconfig options in the ``.kunitconfig`` file.
  22. This file essentially contains the regular Kernel config, with the specific
  23. test targets as well. The ``.kunitconfig`` should also contain any other config
  24. options required by the tests.
  25. A good starting point for a ``.kunitconfig`` is the KUnit defconfig:
  26. .. code-block:: bash
  27. cd $PATH_TO_LINUX_REPO
  28. cp arch/um/configs/kunit_defconfig .kunitconfig
  29. You can then add any other Kconfig options you wish, e.g.:
  30. .. code-block:: none
  31. CONFIG_LIST_KUNIT_TEST=y
  32. :doc:`kunit_tool <kunit-tool>` will ensure that all config options set in
  33. ``.kunitconfig`` are set in the kernel ``.config`` before running the tests.
  34. It'll warn you if you haven't included the dependencies of the options you're
  35. using.
  36. .. note::
  37. Note that removing something from the ``.kunitconfig`` will not trigger a
  38. rebuild of the ``.config`` file: the configuration is only updated if the
  39. ``.kunitconfig`` is not a subset of ``.config``. This means that you can use
  40. other tools (such as make menuconfig) to adjust other config options.
  41. Running the tests (KUnit Wrapper)
  42. ---------------------------------
  43. To make sure that everything is set up correctly, simply invoke the Python
  44. wrapper from your kernel repo:
  45. .. code-block:: bash
  46. ./tools/testing/kunit/kunit.py run
  47. .. note::
  48. You may want to run ``make mrproper`` first.
  49. If everything worked correctly, you should see the following:
  50. .. code-block:: bash
  51. Generating .config ...
  52. Building KUnit Kernel ...
  53. Starting KUnit Kernel ...
  54. followed by a list of tests that are run. All of them should be passing.
  55. .. note::
  56. Because it is building a lot of sources for the first time, the
  57. ``Building KUnit kernel`` step may take a while.
  58. Running tests without the KUnit Wrapper
  59. =======================================
  60. If you'd rather not use the KUnit Wrapper (if, for example, you need to
  61. integrate with other systems, or use an architecture other than UML), KUnit can
  62. be included in any kernel, and the results read out and parsed manually.
  63. .. note::
  64. KUnit is not designed for use in a production system, and it's possible that
  65. tests may reduce the stability or security of the system.
  66. Configuring the kernel
  67. ----------------------
  68. In order to enable KUnit itself, you simply need to enable the ``CONFIG_KUNIT``
  69. Kconfig option (it's under Kernel Hacking/Kernel Testing and Coverage in
  70. menuconfig). From there, you can enable any KUnit tests you want: they usually
  71. have config options ending in ``_KUNIT_TEST``.
  72. KUnit and KUnit tests can be compiled as modules: in this case the tests in a
  73. module will be run when the module is loaded.
  74. Running the tests (w/o KUnit Wrapper)
  75. -------------------------------------
  76. Build and run your kernel as usual. Test output will be written to the kernel
  77. log in `TAP <https://testanything.org/>`_ format.
  78. .. note::
  79. It's possible that there will be other lines and/or data interspersed in the
  80. TAP output.
  81. Writing your first test
  82. =======================
  83. In your kernel repo let's add some code that we can test. Create a file
  84. ``drivers/misc/example.h`` with the contents:
  85. .. code-block:: c
  86. int misc_example_add(int left, int right);
  87. create a file ``drivers/misc/example.c``:
  88. .. code-block:: c
  89. #include <linux/errno.h>
  90. #include "example.h"
  91. int misc_example_add(int left, int right)
  92. {
  93. return left + right;
  94. }
  95. Now add the following lines to ``drivers/misc/Kconfig``:
  96. .. code-block:: kconfig
  97. config MISC_EXAMPLE
  98. bool "My example"
  99. and the following lines to ``drivers/misc/Makefile``:
  100. .. code-block:: make
  101. obj-$(CONFIG_MISC_EXAMPLE) += example.o
  102. Now we are ready to write the test. The test will be in
  103. ``drivers/misc/example-test.c``:
  104. .. code-block:: c
  105. #include <kunit/test.h>
  106. #include "example.h"
  107. /* Define the test cases. */
  108. static void misc_example_add_test_basic(struct kunit *test)
  109. {
  110. KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0));
  111. KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1));
  112. KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1));
  113. KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX));
  114. KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN));
  115. }
  116. static void misc_example_test_failure(struct kunit *test)
  117. {
  118. KUNIT_FAIL(test, "This test never passes.");
  119. }
  120. static struct kunit_case misc_example_test_cases[] = {
  121. KUNIT_CASE(misc_example_add_test_basic),
  122. KUNIT_CASE(misc_example_test_failure),
  123. {}
  124. };
  125. static struct kunit_suite misc_example_test_suite = {
  126. .name = "misc-example",
  127. .test_cases = misc_example_test_cases,
  128. };
  129. kunit_test_suite(misc_example_test_suite);
  130. Now add the following to ``drivers/misc/Kconfig``:
  131. .. code-block:: kconfig
  132. config MISC_EXAMPLE_TEST
  133. bool "Test for my example"
  134. depends on MISC_EXAMPLE && KUNIT=y
  135. and the following to ``drivers/misc/Makefile``:
  136. .. code-block:: make
  137. obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o
  138. Now add it to your ``.kunitconfig``:
  139. .. code-block:: none
  140. CONFIG_MISC_EXAMPLE=y
  141. CONFIG_MISC_EXAMPLE_TEST=y
  142. Now you can run the test:
  143. .. code-block:: bash
  144. ./tools/testing/kunit/kunit.py run
  145. You should see the following failure:
  146. .. code-block:: none
  147. ...
  148. [16:08:57] [PASSED] misc-example:misc_example_add_test_basic
  149. [16:08:57] [FAILED] misc-example:misc_example_test_failure
  150. [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17
  151. [16:08:57] This test never passes.
  152. ...
  153. Congrats! You just wrote your first KUnit test!
  154. Next Steps
  155. ==========
  156. * Check out the :doc:`usage` page for a more
  157. in-depth explanation of KUnit.