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