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
  10 build the kernel, you can run KUnit.
  11
  12 Running tests with kunit_tool
  13 =============================
  14 kunit_tool is a Python script, which configures and builds a kernel, runs
  15 tests, and formats the test results. From the kernel repository, you
  16 can run kunit_tool:
  17
  18 .. code-block:: bash
  19
  20         ./tools/testing/kunit/kunit.py run
  21
  22 For more information on this wrapper, see:
  23 Documentation/dev-tools/kunit/run_wrapper.rst.
  24
  25 Creating a ``.kunitconfig``
  26 ---------------------------
  27
  28 By default, kunit_tool runs a selection of tests. However, you can specify which
  29 unit tests to run by creating a ``.kunitconfig`` file with kernel config options
  30 that enable only a specific set of tests and their dependencies.
  31 The ``.kunitconfig`` file contains a list of kconfig options which are required
  32 to run the desired targets. The ``.kunitconfig`` also contains any other test
  33 specific config options, such as test dependencies. For example: the
  34 ``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on
  35 ``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS``
  36 or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
  37
  38 .. code-block:: none
  39
  40         CONFIG_KUNIT=y
  41         CONFIG_MSDOS_FS=y
  42         CONFIG_FAT_KUNIT_TEST=y
  43
  44 1. A good starting point for the ``.kunitconfig`` is the KUnit default config.
  45    You can generate it by running:
  46
  47 .. code-block:: bash
  48
  49         cd $PATH_TO_LINUX_REPO
  50         tools/testing/kunit/kunit.py config
  51         cat .kunit/.kunitconfig
  52
  53 .. note ::
  54    ``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is
  55    ``.kunit`` by default.
  56
  57 .. note ::
  58    You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as
  59    it will enable a number of additional tests that you may not want.
  60
  61 2. You can then add any other Kconfig options, for example:
  62
  63 .. code-block:: none
  64
  65         CONFIG_LIST_KUNIT_TEST=y
  66
  67 Before running the tests, kunit_tool ensures that all config options
  68 set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn
  69 you if you have not included dependencies for the options used.
  70
  71 .. note ::
  72    If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the
  73    ``.config`` file. But you can edit the ``.config`` file directly or with
  74    tools like ``make menuconfig O=.kunit``. As long as its a superset of
  75    ``.kunitconfig``, kunit.py won't overwrite your changes.
  76
  77 Running Tests (KUnit Wrapper)
  78 -----------------------------
  79 1. To make sure that everything is set up correctly, invoke the Python
  80    wrapper from your kernel repository:
  81
  82 .. code-block:: bash
  83
  84         ./tools/testing/kunit/kunit.py run
  85
  86 If everything worked correctly, you should see the following:
  87
  88 .. code-block::
  89
  90         Generating .config ...
  91         Building KUnit Kernel ...
  92         Starting KUnit Kernel ...
  93
  94 The tests will pass or fail.
  95
  96 .. note ::
  97    Because it is building a lot of sources for the first time, the
  98    ``Building KUnit kernel`` may take a while.
  99
 100 Running Tests without the KUnit Wrapper
 101 =======================================
 102 If you do not want to use the KUnit Wrapper (for example: you want code
 103 under test to integrate with other systems, or use a different/
 104 unsupported architecture or configuration), KUnit can be included in
 105 any kernel, and the results are read out and parsed manually.
 106
 107 .. note ::
 108    ``CONFIG_KUNIT`` should not be enabled in a production environment.
 109    Enabling KUnit disables Kernel Address-Space Layout Randomization
 110    (KASLR), and tests may affect the state of the kernel in ways not
 111    suitable for production.
 112
 113 Configuring the Kernel
 114 ----------------------
 115 To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig
 116 option (under Kernel Hacking/Kernel Testing and Coverage in
 117 ``menuconfig``). From there, you can enable any KUnit tests. They
 118 usually have config options ending in ``_KUNIT_TEST``.
 119
 120 KUnit and KUnit tests can be compiled as modules. The tests in a module
 121 will run when the module is loaded.
 122
 123 Running Tests (without KUnit Wrapper)
 124 -------------------------------------
 125 Build and run your kernel. In the kernel log, the test output is printed
 126 out in the TAP format. This will only happen by default if KUnit/tests
 127 are built-in. Otherwise the module will need to be loaded.
 128
 129 .. note ::
 130    Some lines and/or data may get interspersed in the TAP output.
 131
 132 Writing Your First Test
 133 =======================
 134 In your kernel repository, let's add some code that we can test.
 135
 136 1. Create a file ``drivers/misc/example.h``, which includes:
 137
 138 .. code-block:: c
 139
 140         int misc_example_add(int left, int right);
 141
 142 2. Create a file ``drivers/misc/example.c``, which includes:
 143
 144 .. code-block:: c
 145
 146         #include <linux/errno.h>
 147
 148         #include "example.h"
 149
 150         int misc_example_add(int left, int right)
 151         {
 152                 return left + right;
 153         }
 154
 155 3. Add the following lines to ``drivers/misc/Kconfig``:
 156
 157 .. code-block:: kconfig
 158
 159         config MISC_EXAMPLE
 160                 bool "My example"
 161
 162 4. Add the following lines to ``drivers/misc/Makefile``:
 163
 164 .. code-block:: make
 165
 166         obj-$(CONFIG_MISC_EXAMPLE) += example.o
 167
 168 Now we are ready to write the test cases.
 169
 170 1. Add the below test case in ``drivers/misc/example_test.c``:
 171
 172 .. code-block:: c
 173
 174         #include <kunit/test.h>
 175         #include "example.h"
 176
 177         /* Define the test cases. */
 178
 179         static void misc_example_add_test_basic(struct kunit *test)
 180         {
 181                 KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0));
 182                 KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1));
 183                 KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1));
 184                 KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX));
 185                 KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN));
 186         }
 187
 188         static void misc_example_test_failure(struct kunit *test)
 189         {
 190                 KUNIT_FAIL(test, "This test never passes.");
 191         }
 192
 193         static struct kunit_case misc_example_test_cases[] = {
 194                 KUNIT_CASE(misc_example_add_test_basic),
 195                 KUNIT_CASE(misc_example_test_failure),
 196                 {}
 197         };
 198
 199         static struct kunit_suite misc_example_test_suite = {
 200                 .name = "misc-example",
 201                 .test_cases = misc_example_test_cases,
 202         };
 203         kunit_test_suite(misc_example_test_suite);
 204
 205 2. Add the following lines to ``drivers/misc/Kconfig``:
 206
 207 .. code-block:: kconfig
 208
 209         config MISC_EXAMPLE_TEST
 210                 tristate "Test for my example" if !KUNIT_ALL_TESTS
 211                 depends on MISC_EXAMPLE && KUNIT=y
 212                 default KUNIT_ALL_TESTS
 213
 214 3. Add the following lines to ``drivers/misc/Makefile``:
 215
 216 .. code-block:: make
 217
 218         obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o
 219
 220 4. Add the following lines to ``.kunitconfig``:
 221
 222 .. code-block:: none
 223
 224         CONFIG_MISC_EXAMPLE=y
 225         CONFIG_MISC_EXAMPLE_TEST=y
 226
 227 5. Run the test:
 228
 229 .. code-block:: bash
 230
 231         ./tools/testing/kunit/kunit.py run
 232
 233 You should see the following failure:
 234
 235 .. code-block:: none
 236
 237         ...
 238         [16:08:57] [PASSED] misc-example:misc_example_add_test_basic
 239         [16:08:57] [FAILED] misc-example:misc_example_test_failure
 240         [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17
 241         [16:08:57]      This test never passes.
 242         ...
 243
 244 Congrats! You just wrote your first KUnit test.
 245
 246 Next Steps
 247 ==========
 248
 249 *   Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
 250 *   Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
 251 *   Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
 252 *   Documentation/dev-tools/kunit/usage.rst - write tests.
 253 *   Documentation/dev-tools/kunit/tips.rst - best practices with
 254     examples.
 255 *   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
 256     used for testing.
 257 *   Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
 258     script.
 259 *   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
 260     answers.