Documentation/dev-tools/kunit/running_tips.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============================
   4 Tips For Running KUnit Tests
   5 ============================
   6
   7 Using ``kunit.py run`` ("kunit tool")
   8 =====================================
   9
  10 Running from any directory
  11 --------------------------
  12
  13 It can be handy to create a bash function like:
  14
  15 .. code-block:: bash
  16
  17         function run_kunit() {
  18           ( cd "$(git rev-parse --show-toplevel)" && ./tools/testing/kunit/kunit.py run $@ )
  19         }
  20
  21 .. note::
  22         Early versions of ``kunit.py`` (before 5.6) didn't work unless run from
  23         the kernel root, hence the use of a subshell and ``cd``.
  24
  25 Running a subset of tests
  26 -------------------------
  27
  28 ``kunit.py run`` accepts an optional glob argument to filter tests. Currently
  29 this only matches against suite names, but this may change in the future.
  30
  31 Say that we wanted to run the sysctl tests, we could do so via:
  32
  33 .. code-block:: bash
  34
  35         $ echo -e 'CONFIG_KUNIT=y\nCONFIG_KUNIT_ALL_TESTS=y' > .kunit/.kunitconfig
  36         $ ./tools/testing/kunit/kunit.py run 'sysctl*'
  37
  38 We're paying the cost of building more tests than we need this way, but it's
  39 easier than fiddling with ``.kunitconfig`` files or commenting out
  40 ``kunit_suite``'s.
  41
  42 However, if we wanted to define a set of tests in a less ad hoc way, the next
  43 tip is useful.
  44
  45 Defining a set of tests
  46 -----------------------
  47
  48 ``kunit.py run`` (along with ``build``, and ``config``) supports a
  49 ``--kunitconfig`` flag. So if you have a set of tests that you want to run on a
  50 regular basis (especially if they have other dependencies), you can create a
  51 specific ``.kunitconfig`` for them.
  52
  53 E.g. kunit has one for its tests:
  54
  55 .. code-block:: bash
  56
  57         $ ./tools/testing/kunit/kunit.py run --kunitconfig=lib/kunit/.kunitconfig
  58
  59 Alternatively, if you're following the convention of naming your
  60 file ``.kunitconfig``, you can just pass in the dir, e.g.
  61
  62 .. code-block:: bash
  63
  64         $ ./tools/testing/kunit/kunit.py run --kunitconfig=lib/kunit
  65
  66 .. note::
  67         This is a relatively new feature (5.12+) so we don't have any
  68         conventions yet about on what files should be checked in versus just
  69         kept around locally. It's up to you and your maintainer to decide if a
  70         config is useful enough to submit (and therefore have to maintain).
  71
  72 .. note::
  73         Having ``.kunitconfig`` fragments in a parent and child directory is
  74         iffy. There's discussion about adding an "import" statement in these
  75         files to make it possible to have a top-level config run tests from all
  76         child directories. But that would mean ``.kunitconfig`` files are no
  77         longer just simple .config fragments.
  78
  79         One alternative would be to have kunit tool recursively combine configs
  80         automagically, but tests could theoretically depend on incompatible
  81         options, so handling that would be tricky.
  82
  83 Generating code coverage reports under UML
  84 ------------------------------------------
  85
  86 .. note::
  87         TODO(brendanhiggins@google.com): There are various issues with UML and
  88         versions of gcc 7 and up. You're likely to run into missing ``.gcda``
  89         files or compile errors. We know one `faulty GCC commit
  90         <https://github.com/gcc-mirror/gcc/commit/8c9434c2f9358b8b8bad2c1990edf10a21645f9d>`_
  91         but not how we'd go about getting this fixed. The compile errors still
  92         need some investigation.
  93
  94 .. note::
  95         TODO(brendanhiggins@google.com): for recent versions of Linux
  96         (5.10-5.12, maybe earlier), there's a bug with gcov counters not being
  97         flushed in UML. This translates to very low (<1%) reported coverage. This is
  98         related to the above issue and can be worked around by replacing the
  99         one call to ``uml_abort()`` (it's in ``os_dump_core()``) with a plain
 100         ``exit()``.
 101
 102
 103 This is different from the "normal" way of getting coverage information that is
 104 documented in Documentation/dev-tools/gcov.rst.
 105
 106 Instead of enabling ``CONFIG_GCOV_KERNEL=y``, we can set these options:
 107
 108 .. code-block:: none
 109
 110         CONFIG_DEBUG_KERNEL=y
 111         CONFIG_DEBUG_INFO=y
 112         CONFIG_GCOV=y
 113
 114
 115 Putting it together into a copy-pastable sequence of commands:
 116
 117 .. code-block:: bash
 118
 119         # Append coverage options to the current config
 120         $ echo -e "CONFIG_DEBUG_KERNEL=y\nCONFIG_DEBUG_INFO=y\nCONFIG_GCOV=y" >> .kunit/.kunitconfig
 121         $ ./tools/testing/kunit/kunit.py run
 122         # Extract the coverage information from the build dir (.kunit/)
 123         $ lcov -t "my_kunit_tests" -o coverage.info -c -d .kunit/
 124
 125         # From here on, it's the same process as with CONFIG_GCOV_KERNEL=y
 126         # E.g. can generate an HTML report in a tmp dir like so:
 127         $ genhtml -o /tmp/coverage_html coverage.info
 128
 129
 130 If your installed version of gcc doesn't work, you can tweak the steps:
 131
 132 .. code-block:: bash
 133
 134         $ ./tools/testing/kunit/kunit.py run --make_options=CC=/usr/bin/gcc-6
 135         $ lcov -t "my_kunit_tests" -o coverage.info -c -d .kunit/ --gcov-tool=/usr/bin/gcov-6
 136
 137
 138 Running tests manually
 139 ======================
 140
 141 Running tests without using ``kunit.py run`` is also an important use case.
 142 Currently it's your only option if you want to test on architectures other than
 143 UML.
 144
 145 As running the tests under UML is fairly straightforward (configure and compile
 146 the kernel, run the ``./linux`` binary), this section will focus on testing
 147 non-UML architectures.
 148
 149
 150 Running built-in tests
 151 ----------------------
 152
 153 When setting tests to ``=y``, the tests will run as part of boot and print
 154 results to dmesg in TAP format. So you just need to add your tests to your
 155 ``.config``, build and boot your kernel as normal.
 156
 157 So if we compiled our kernel with:
 158
 159 .. code-block:: none
 160
 161         CONFIG_KUNIT=y
 162         CONFIG_KUNIT_EXAMPLE_TEST=y
 163
 164 Then we'd see output like this in dmesg signaling the test ran and passed:
 165
 166 .. code-block:: none
 167
 168         TAP version 14
 169         1..1
 170             # Subtest: example
 171             1..1
 172             # example_simple_test: initializing
 173             ok 1 - example_simple_test
 174         ok 1 - example
 175
 176 Running tests as modules
 177 ------------------------
 178
 179 Depending on the tests, you can build them as loadable modules.
 180
 181 For example, we'd change the config options from before to
 182
 183 .. code-block:: none
 184
 185         CONFIG_KUNIT=y
 186         CONFIG_KUNIT_EXAMPLE_TEST=m
 187
 188 Then after booting into our kernel, we can run the test via
 189
 190 .. code-block:: none
 191
 192         $ modprobe kunit-example-test
 193
 194 This will then cause it to print TAP output to stdout.
 195
 196 .. note::
 197         The ``modprobe`` will *not* have a non-zero exit code if any test
 198         failed (as of 5.13). But ``kunit.py parse`` would, see below.
 199
 200 .. note::
 201         You can set ``CONFIG_KUNIT=m`` as well, however, some features will not
 202         work and thus some tests might break. Ideally tests would specify they
 203         depend on ``KUNIT=y`` in their ``Kconfig``'s, but this is an edge case
 204         most test authors won't think about.
 205         As of 5.13, the only difference is that ``current->kunit_test`` will
 206         not exist.
 207
 208 Pretty-printing results
 209 -----------------------
 210
 211 You can use ``kunit.py parse`` to parse dmesg for test output and print out
 212 results in the same familiar format that ``kunit.py run`` does.
 213
 214 .. code-block:: bash
 215
 216         $ ./tools/testing/kunit/kunit.py parse /var/log/dmesg
 217
 218
 219 Retrieving per suite results
 220 ----------------------------
 221
 222 Regardless of how you're running your tests, you can enable
 223 ``CONFIG_KUNIT_DEBUGFS`` to expose per-suite TAP-formatted results:
 224
 225 .. code-block:: none
 226
 227         CONFIG_KUNIT=y
 228         CONFIG_KUNIT_EXAMPLE_TEST=m
 229         CONFIG_KUNIT_DEBUGFS=y
 230
 231 The results for each suite will be exposed under
 232 ``/sys/kernel/debug/kunit/<suite>/results``.
 233 So using our example config:
 234
 235 .. code-block:: bash
 236
 237         $ modprobe kunit-example-test > /dev/null
 238         $ cat /sys/kernel/debug/kunit/example/results
 239         ... <TAP output> ...
 240
 241         # After removing the module, the corresponding files will go away
 242         $ modprobe -r kunit-example-test
 243         $ cat /sys/kernel/debug/kunit/example/results
 244         /sys/kernel/debug/kunit/example/results: No such file or directory
 245
 246 Generating code coverage reports
 247 --------------------------------
 248
 249 See Documentation/dev-tools/gcov.rst for details on how to do this.
 250
 251 The only vaguely KUnit-specific advice here is that you probably want to build
 252 your tests as modules. That way you can isolate the coverage from tests from
 253 other code executed during boot, e.g.
 254
 255 .. code-block:: bash
 256
 257         # Reset coverage counters before running the test.
 258         $ echo 0 > /sys/kernel/debug/gcov/reset
 259         $ modprobe kunit-example-test