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         git clone -b master https://kunit.googlesource.com/kunitconfig $PATH_TO_KUNITCONFIG_REPO
  36         cd $PATH_TO_LINUX_REPO
  37         ln -s $PATH_TO_KUNIT_CONFIG_REPO/kunitconfig kunitconfig
  38
  39 You may want to add kunitconfig to your local gitignore.
  40
  41 Verifying KUnit Works
  42 ---------------------
  43
  44 To make sure that everything is set up correctly, simply invoke the Python
  45 wrapper from your kernel repo:
  46
  47 .. code-block:: bash
  48
  49         ./tools/testing/kunit/kunit.py run
  50
  51 .. note::
  52    You may want to run ``make mrproper`` first.
  53
  54 If everything worked correctly, you should see the following:
  55
  56 .. code-block:: bash
  57
  58         Generating .config ...
  59         Building KUnit Kernel ...
  60         Starting KUnit Kernel ...
  61
  62 followed by a list of tests that are run. All of them should be passing.
  63
  64 .. note::
  65         Because it is building a lot of sources for the first time, the
  66         ``Building KUnit kernel`` step may take a while.
  67
  68 Writing your first test
  69 =======================
  70
  71 In your kernel repo let's add some code that we can test. Create a file
  72 ``drivers/misc/example.h`` with the contents:
  73
  74 .. code-block:: c
  75
  76         int misc_example_add(int left, int right);
  77
  78 create a file ``drivers/misc/example.c``:
  79
  80 .. code-block:: c
  81
  82         #include <linux/errno.h>
  83
  84         #include "example.h"
  85
  86         int misc_example_add(int left, int right)
  87         {
  88                 return left + right;
  89         }
  90
  91 Now add the following lines to ``drivers/misc/Kconfig``:
  92
  93 .. code-block:: kconfig
  94
  95         config MISC_EXAMPLE
  96                 bool "My example"
  97
  98 and the following lines to ``drivers/misc/Makefile``:
  99
 100 .. code-block:: make
 101
 102         obj-$(CONFIG_MISC_EXAMPLE) += example.o
 103
 104 Now we are ready to write the test. The test will be in
 105 ``drivers/misc/example-test.c``:
 106
 107 .. code-block:: c
 108
 109         #include <kunit/test.h>
 110         #include "example.h"
 111
 112         /* Define the test cases. */
 113
 114         static void misc_example_add_test_basic(struct kunit *test)
 115         {
 116                 KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0));
 117                 KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1));
 118                 KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1));
 119                 KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX));
 120                 KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN));
 121         }
 122
 123         static void misc_example_test_failure(struct kunit *test)
 124         {
 125                 KUNIT_FAIL(test, "This test never passes.");
 126         }
 127
 128         static struct kunit_case misc_example_test_cases[] = {
 129                 KUNIT_CASE(misc_example_add_test_basic),
 130                 KUNIT_CASE(misc_example_test_failure),
 131                 {}
 132         };
 133
 134         static struct kunit_suite misc_example_test_suite = {
 135                 .name = "misc-example",
 136                 .test_cases = misc_example_test_cases,
 137         };
 138         kunit_test_suite(misc_example_test_suite);
 139
 140 Now add the following to ``drivers/misc/Kconfig``:
 141
 142 .. code-block:: kconfig
 143
 144         config MISC_EXAMPLE_TEST
 145                 bool "Test for my example"
 146                 depends on MISC_EXAMPLE && KUNIT
 147
 148 and the following to ``drivers/misc/Makefile``:
 149
 150 .. code-block:: make
 151
 152         obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o
 153
 154 Now add it to your ``kunitconfig``:
 155
 156 .. code-block:: none
 157
 158         CONFIG_MISC_EXAMPLE=y
 159         CONFIG_MISC_EXAMPLE_TEST=y
 160
 161 Now you can run the test:
 162
 163 .. code-block:: bash
 164
 165         ./tools/testing/kunit/kunit.py run
 166
 167 You should see the following failure:
 168
 169 .. code-block:: none
 170
 171         ...
 172         [16:08:57] [PASSED] misc-example:misc_example_add_test_basic
 173         [16:08:57] [FAILED] misc-example:misc_example_test_failure
 174         [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17
 175         [16:08:57]      This test never passes.
 176         ...
 177
 178 Congrats! You just wrote your first KUnit test!
 179
 180 Next Steps
 181 ==========
 182 *   Check out the :doc:`usage` page for a more
 183     in-depth explanation of KUnit.