Documentation/dev-tools/kunit/run_wrapper.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =============================
   4 Running tests with kunit_tool
   5 =============================
   6
   7 We can either run KUnit tests using kunit_tool or can run tests
   8 manually, and then use kunit_tool to parse the results. To run tests
   9 manually, see: Documentation/dev-tools/kunit/run_manual.rst.
  10 As long as we can build the kernel, we can run KUnit.
  11
  12 kunit_tool is a Python script which configures and builds a kernel, runs
  13 tests, and formats the test results.
  14
  15 Run command:
  16
  17 .. code-block::
  18
  19         ./tools/testing/kunit/kunit.py run
  20
  21 We should see the following:
  22
  23 .. code-block::
  24
  25         Configuring KUnit Kernel ...
  26         Building KUnit kernel...
  27         Starting KUnit kernel...
  28
  29 We may want to use the following options:
  30
  31 .. code-block::
  32
  33         ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all`
  34
  35 - ``--timeout`` sets a maximum amount of time for tests to run.
  36 - ``--jobs`` sets the number of threads to build the kernel.
  37
  38 kunit_tool will generate a ``.kunitconfig`` with a default
  39 configuration, if no other ``.kunitconfig`` file exists
  40 (in the build directory). In addition, it verifies that the
  41 generated ``.config`` file contains the ``CONFIG`` options in the
  42 ``.kunitconfig``.
  43 It is also possible to pass a separate ``.kunitconfig`` fragment to
  44 kunit_tool. This is useful if we have several different groups of
  45 tests we want to run independently, or if we want to use pre-defined
  46 test configs for certain subsystems.
  47
  48 To use a different ``.kunitconfig`` file (such as one
  49 provided to test a particular subsystem), pass it as an option:
  50
  51 .. code-block::
  52
  53         ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
  54
  55 To view kunit_tool flags (optional command-line arguments), run:
  56
  57 .. code-block::
  58
  59         ./tools/testing/kunit/kunit.py run --help
  60
  61 Creating a ``.kunitconfig`` file
  62 ================================
  63
  64 If we want to run a specific set of tests (rather than those listed
  65 in the KUnit ``defconfig``), we can provide Kconfig options in the
  66 ``.kunitconfig`` file. For default .kunitconfig, see:
  67 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config.
  68 A ``.kunitconfig`` is a ``minconfig`` (a .config
  69 generated by running ``make savedefconfig``), used for running a
  70 specific set of tests. This file contains the regular Kernel configs
  71 with specific test targets. The ``.kunitconfig`` also
  72 contains any other config options required by the tests (For example:
  73 dependencies for features under tests, configs that enable/disable
  74 certain code blocks, arch configs and so on).
  75
  76 To create a ``.kunitconfig``, using the KUnit ``defconfig``:
  77
  78 .. code-block::
  79
  80         cd $PATH_TO_LINUX_REPO
  81         cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig
  82
  83 We can then add any other Kconfig options. For example:
  84
  85 .. code-block::
  86
  87         CONFIG_LIST_KUNIT_TEST=y
  88
  89 kunit_tool ensures that all config options in ``.kunitconfig`` are
  90 set in the kernel ``.config`` before running the tests. It warns if we
  91 have not included the options dependencies.
  92
  93 .. note:: Removing something from the ``.kunitconfig`` will
  94    not rebuild the ``.config file``. The configuration is only
  95    updated if the ``.kunitconfig`` is not a subset of ``.config``.
  96    This means that we can use other tools
  97    (For example: ``make menuconfig``) to adjust other config options.
  98    The build dir needs to be set for ``make menuconfig`` to
  99    work, therefore  by default use ``make O=.kunit menuconfig``.
 100
 101 Configuring, building, and running tests
 102 ========================================
 103
 104 If we want to make manual changes to the KUnit build process, we
 105 can run part of the KUnit build process independently.
 106 When running kunit_tool, from a ``.kunitconfig``, we can generate a
 107 ``.config`` by using the ``config`` argument:
 108
 109 .. code-block::
 110
 111         ./tools/testing/kunit/kunit.py config
 112
 113 To build a KUnit kernel from the current ``.config``, we can use the
 114 ``build`` argument:
 115
 116 .. code-block::
 117
 118         ./tools/testing/kunit/kunit.py build
 119
 120 If we already have built UML kernel with built-in KUnit tests, we
 121 can run the kernel, and display the test results with the ``exec``
 122 argument:
 123
 124 .. code-block::
 125
 126         ./tools/testing/kunit/kunit.py exec
 127
 128 The ``run`` command discussed in section: **Running tests with kunit_tool**,
 129 is equivalent to running the above three commands in sequence.
 130
 131 Parsing test results
 132 ====================
 133
 134 KUnit tests output displays results in TAP (Test Anything Protocol)
 135 format. When running tests, kunit_tool parses this output and prints
 136 a summary. To see the raw test results in TAP format, we can pass the
 137 ``--raw_output`` argument:
 138
 139 .. code-block::
 140
 141         ./tools/testing/kunit/kunit.py run --raw_output
 142
 143 If we have KUnit results in the raw TAP format, we can parse them and
 144 print the human-readable summary with the ``parse`` command for
 145 kunit_tool. This accepts a filename for an argument, or will read from
 146 standard input.
 147
 148 .. code-block:: bash
 149
 150         # Reading from a file
 151         ./tools/testing/kunit/kunit.py parse /var/log/dmesg
 152         # Reading from stdin
 153         dmesg | ./tools/testing/kunit/kunit.py parse
 154
 155 Filtering tests
 156 ===============
 157
 158 By passing a bash style glob filter to the ``exec`` or ``run``
 159 commands, we can run a subset of the tests built into a kernel . For
 160 example: if we only want to run KUnit resource tests, use:
 161
 162 .. code-block::
 163
 164         ./tools/testing/kunit/kunit.py run 'kunit-resource*'
 165
 166 This uses the standard glob format with wildcard characters.
 167
 168 .. _kunit-on-qemu:
 169
 170 Running tests on QEMU
 171 =====================
 172
 173 kunit_tool supports running tests on  qemu as well as
 174 via UML. To run tests on qemu, by default it requires two flags:
 175
 176 - ``--arch``: Selects a configs collection (Kconfig, qemu config options
 177   and so on), that allow KUnit tests to be run on the specified
 178   architecture in a minimal way. The architecture argument is same as
 179   the option name passed to the ``ARCH`` variable used by Kbuild.
 180   Not all architectures currently support this flag, but we can use
 181   ``--qemu_config`` to handle it. If ``um`` is passed (or this flag
 182   is ignored), the tests will run via UML. Non-UML architectures,
 183   for example: i386, x86_64, arm and so on; run on qemu.
 184
 185 - ``--cross_compile``: Specifies the Kbuild toolchain. It passes the
 186   same argument as passed to the ``CROSS_COMPILE`` variable used by
 187   Kbuild. As a reminder, this will be the prefix for the toolchain
 188   binaries such as GCC. For example:
 189
 190   - ``sparc64-linux-gnu`` if we have the sparc toolchain installed on
 191     our system.
 192
 193   - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``
 194     if we have downloaded the microblaze toolchain from the 0-day
 195     website to a directory in our home directory called toolchains.
 196
 197 This means that for most architectures, running under qemu is as simple as:
 198
 199 .. code-block:: bash
 200
 201         ./tools/testing/kunit/kunit.py run --arch=x86_64
 202
 203 When cross-compiling, we'll likely need to specify a different toolchain, for
 204 example:
 205
 206 .. code-block:: bash
 207
 208         ./tools/testing/kunit/kunit.py run \
 209                 --arch=s390 \
 210                 --cross_compile=s390x-linux-gnu-
 211
 212 If we want to run KUnit tests on an architecture not supported by
 213 the ``--arch`` flag, or want to run KUnit tests on qemu using a
 214 non-default configuration; then we can write our own``QemuConfig``.
 215 These ``QemuConfigs`` are written in Python. They have an import line
 216 ``from..qemu_config import QemuArchParams`` at the top of the file.
 217 The file must contain a variable called ``QEMU_ARCH`` that has an
 218 instance of ``QemuArchParams`` assigned to it. See example in:
 219 ``tools/testing/kunit/qemu_configs/x86_64.py``.
 220
 221 Once we have a ``QemuConfig``, we can pass it into kunit_tool,
 222 using the ``--qemu_config`` flag. When used, this flag replaces the
 223 ``--arch`` flag. For example: using
 224 ``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear
 225 as
 226
 227 .. code-block:: bash
 228
 229         ./tools/testing/kunit/kunit.py run \
 230                 --timeout=60 \
 231                 --jobs=12 \
 232                 --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
 233
 234 Running command-line arguments
 235 ==============================
 236
 237 kunit_tool has a number of other command-line arguments which can
 238 be useful for our test environment. Below are the most commonly used
 239 command line arguments:
 240
 241 - ``--help``: Lists all available options. To list common options,
 242   place ``--help`` before the command. To list options specific to that
 243   command, place ``--help`` after the command.
 244
 245   .. note:: Different commands (``config``, ``build``, ``run``, etc)
 246             have different supported options.
 247 - ``--build_dir``: Specifies kunit_tool build directory. It includes
 248   the ``.kunitconfig``, ``.config`` files and compiled kernel.
 249
 250 - ``--make_options``: Specifies additional options to pass to make, when
 251   compiling a kernel (using ``build`` or ``run`` commands). For example:
 252   to enable compiler warnings, we can pass ``--make_options W=1``.
 253
 254 - ``--alltests``: Enable a predefined set of options in order to build
 255   as many tests as possible.
 256
 257   .. note:: The list of enabled options can be found in
 258             ``tools/testing/kunit/configs/all_tests.config``.
 259
 260             If you only want to enable all tests with otherwise satisfied
 261             dependencies, instead add ``CONFIG_KUNIT_ALL_TESTS=y`` to your
 262             ``.kunitconfig``.
 263
 264 - ``--kunitconfig``: Specifies the path or the directory of the ``.kunitconfig``
 265   file. For example:
 266
 267   - ``lib/kunit/.kunitconfig`` can be the path of the file.
 268
 269   - ``lib/kunit`` can be the directory in which the file is located.
 270
 271   This file is used to build and run with a predefined set of tests
 272   and their dependencies. For example, to run tests for a given subsystem.
 273
 274 - ``--kconfig_add``: Specifies additional configuration options to be
 275   appended to the ``.kunitconfig`` file. For example:
 276
 277   .. code-block::
 278
 279         ./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y
 280
 281 - ``--arch``: Runs tests on the specified architecture. The architecture
 282   argument is same as the Kbuild ARCH environment variable.
 283   For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu.
 284   Default is `um`.
 285
 286 - ``--cross_compile``: Specifies the Kbuild toolchain. It passes the
 287   same argument as passed to the ``CROSS_COMPILE`` variable used by
 288   Kbuild. This will be the prefix for the toolchain
 289   binaries such as GCC. For example:
 290
 291   - ``sparc64-linux-gnu-`` if we have the sparc toolchain installed on
 292     our system.
 293
 294   - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``
 295     if we have downloaded the microblaze toolchain from the 0-day
 296     website to a specified path in our home directory called toolchains.
 297
 298 - ``--qemu_config``: Specifies the path to a file containing a
 299   custom qemu architecture definition. This should be a python file
 300   containing a `QemuArchParams` object.
 301
 302 - ``--qemu_args``: Specifies additional qemu arguments, for example, ``-smp 8``.
 303
 304 - ``--jobs``: Specifies the number of jobs (commands) to run simultaneously.
 305   By default, this is set to the number of cores on your system.
 306
 307 - ``--timeout``: Specifies the maximum number of seconds allowed for all tests to run.
 308   This does not include the time taken to build the tests.
 309
 310 - ``--kernel_args``: Specifies additional kernel command-line arguments. May be repeated.
 311
 312 - ``--run_isolated``: If set, boots the kernel for each individual suite/test.
 313   This is useful for debugging a non-hermetic test, one that
 314   might pass/fail based on what ran before it.
 315
 316 - ``--raw_output``: If set, generates unformatted output from kernel. Possible options are:
 317
 318    - ``all``: To view the full kernel output, use ``--raw_output=all``.
 319
 320    - ``kunit``: This is the default option and filters to KUnit output. Use ``--raw_output`` or ``--raw_output=kunit``.
 321
 322 - ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or
 323   saves to a file if a filename is specified.
 324
 325 - ``--filter``: Specifies filters on test attributes, for example, ``speed!=slow``.
 326   Multiple filters can be used by wrapping input in quotes and separating filters
 327   by commas. Example: ``--filter "speed>slow, module=example"``.
 328
 329 - ``--filter_action``: If set to ``skip``, filtered tests will be shown as skipped
 330   in the output rather than showing no output.
 331
 332 - ``--list_tests``: If set, lists all tests that will be run.
 333
 334 - ``--list_tests_attr``: If set, lists all tests that will be run and all of their
 335   attributes.