Documentation/dev-tools/kunit/start.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============
   4 Getting Started
   5 ===============
   6
   7 Installing dependencies
   8 =======================
   9 KUnit has the same dependencies as the Linux kernel. As long as you can build
  10 the kernel, you can run KUnit.
  11
  12 KUnit Wrapper
  13 =============
  14 Included with KUnit is a simple Python wrapper that helps format the output to
  15 easily use and read KUnit output. It handles building and running the kernel, as
  16 well as formatting the output.
  17
  18 The wrapper can be run with:
  19
  20 .. code-block:: bash
  21
  22         ./tools/testing/kunit/kunit.py run --defconfig
  23
  24 For more information on this wrapper (also called kunit_tool) checkout the
  25 :doc:`kunit-tool` page.
  26
  27 Creating a .kunitconfig
  28 =======================
  29 The Python script is a thin wrapper around Kbuild. As such, it needs to be
  30 configured with a ``.kunitconfig`` file. This file essentially contains the
  31 regular Kernel config, with the specific test targets as well.
  32
  33 .. code-block:: bash
  34
  35         cd $PATH_TO_LINUX_REPO
  36         cp arch/um/configs/kunit_defconfig .kunitconfig
  37
  38 Verifying KUnit Works
  39 ---------------------
  40
  41 To make sure that everything is set up correctly, simply invoke the Python
  42 wrapper from your kernel repo:
  43
  44 .. code-block:: bash
  45
  46         ./tools/testing/kunit/kunit.py run
  47
  48 .. note::
  49    You may want to run ``make mrproper`` first.
  50
  51 If everything worked correctly, you should see the following:
  52
  53 .. code-block:: bash
  54
  55         Generating .config ...
  56         Building KUnit Kernel ...
  57         Starting KUnit Kernel ...
  58
  59 followed by a list of tests that are run. All of them should be passing.
  60
  61 .. note::
  62         Because it is building a lot of sources for the first time, the
  63         ``Building KUnit kernel`` step may take a while.
  64
  65 Writing your first test
  66 =======================
  67
  68 In your kernel repo let's add some code that we can test. Create a file
  69 ``drivers/misc/example.h`` with the contents:
  70
  71 .. code-block:: c
  72
  73         int misc_example_add(int left, int right);
  74
  75 create a file ``drivers/misc/example.c``:
  76
  77 .. code-block:: c
  78
  79         #include <linux/errno.h>
  80
  81         #include "example.h"
  82
  83         int misc_example_add(int left, int right)
  84         {
  85                 return left + right;
  86         }
  87
  88 Now add the following lines to ``drivers/misc/Kconfig``:
  89
  90 .. code-block:: kconfig
  91
  92         config MISC_EXAMPLE
  93                 bool "My example"
  94
  95 and the following lines to ``drivers/misc/Makefile``:
  96
  97 .. code-block:: make
  98
  99         obj-$(CONFIG_MISC_EXAMPLE) += example.o
 100
 101 Now we are ready to write the test. The test will be in
 102 ``drivers/misc/example-test.c``:
 103
 104 .. code-block:: c
 105
 106         #include <kunit/test.h>
 107         #include "example.h"
 108
 109         /* Define the test cases. */
 110
 111         static void misc_example_add_test_basic(struct kunit *test)
 112         {
 113                 KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0));
 114                 KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1));
 115                 KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1));
 116                 KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX));
 117                 KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN));
 118         }
 119
 120         static void misc_example_test_failure(struct kunit *test)
 121         {
 122                 KUNIT_FAIL(test, "This test never passes.");
 123         }
 124
 125         static struct kunit_case misc_example_test_cases[] = {
 126                 KUNIT_CASE(misc_example_add_test_basic),
 127                 KUNIT_CASE(misc_example_test_failure),
 128                 {}
 129         };
 130
 131         static struct kunit_suite misc_example_test_suite = {
 132                 .name = "misc-example",
 133                 .test_cases = misc_example_test_cases,
 134         };
 135         kunit_test_suite(misc_example_test_suite);
 136
 137 Now add the following to ``drivers/misc/Kconfig``:
 138
 139 .. code-block:: kconfig
 140
 141         config MISC_EXAMPLE_TEST
 142                 bool "Test for my example"
 143                 depends on MISC_EXAMPLE && KUNIT
 144
 145 and the following to ``drivers/misc/Makefile``:
 146
 147 .. code-block:: make
 148
 149         obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o
 150
 151 Now add it to your ``.kunitconfig``:
 152
 153 .. code-block:: none
 154
 155         CONFIG_MISC_EXAMPLE=y
 156         CONFIG_MISC_EXAMPLE_TEST=y
 157
 158 Now you can run the test:
 159
 160 .. code-block:: bash
 161
 162         ./tools/testing/kunit/kunit.py run
 163
 164 You should see the following failure:
 165
 166 .. code-block:: none
 167
 168         ...
 169         [16:08:57] [PASSED] misc-example:misc_example_add_test_basic
 170         [16:08:57] [FAILED] misc-example:misc_example_test_failure
 171         [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17
 172         [16:08:57]      This test never passes.
 173         ...
 174
 175 Congrats! You just wrote your first KUnit test!
 176
 177 Next Steps
 178 ==========
 179 *   Check out the :doc:`usage` page for a more
 180     in-depth explanation of KUnit.