wsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget)/translations/zh_CN/dev-tools/kunit/startmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/zh_TW/dev-tools/kunit/startmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/it_IT/dev-tools/kunit/startmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ja_JP/dev-tools/kunit/startmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ko_KR/dev-tools/kunit/startmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/pt_BR/dev-tools/kunit/startmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/sp_SP/dev-tools/kunit/startmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhC/var/lib/git/docbuild/linux/Documentation/dev-tools/kunit/start.rsthKubhsection)}(hhh](htitle)}(hGetting Startedh]hGetting Started}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThis page contains an overview of the kunit_tool and KUnit framework, teaching how to run existing tests and then how to write a simple test case, and covers common problems users face when using KUnit for the first time.h]hThis page contains an overview of the kunit_tool and KUnit framework, teaching how to run existing tests and then how to write a simple test case, and covers common problems users face when using KUnit for the first time.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hInstalling Dependenciesh]hInstalling Dependencies}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh)}(hlKUnit has the same dependencies as the Linux kernel. As long as you can build the kernel, you can run KUnit.h]hlKUnit has the same dependencies as the Linux kernel. As long as you can build the kernel, you can run KUnit.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubeh}(h]installing-dependenciesah ]h"]installing dependenciesah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hRunning tests with kunit_toolh]hRunning tests with kunit_tool}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hkunit_tool is a Python script, which configures and builds a kernel, runs tests, and formats the test results. From the kernel repository, you can run kunit_tool:h]hkunit_tool is a Python script, which configures and builds a kernel, runs tests, and formats the test results. From the kernel repository, you can run kunit_tool:}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh literal_block)}(h"./tools/testing/kunit/kunit.py runh]h"./tools/testing/kunit/kunit.py run}hj5sbah}(h]h ]h"]h$]h&]hhƌforcelanguagebashhighlight_args}uh1j3hhhKhjhhubhnote)}(hXYou may see the following error: "The source tree is not clean, please run 'make ARCH=um mrproper'" This happens because internally kunit.py specifies ``.kunit`` (default option) as the build directory in the command ``make O=output/dir`` through the argument ``--build_dir``. Hence, before starting an out-of-tree build, the source tree must be clean. There is also the same caveat mentioned in the "Build directory for the kernel" section of the :doc:`admin-guide `, that is, its use, it must be used for all invocations of ``make``. The good news is that it can indeed be solved by running ``make ARCH=um mrproper``, just be aware that this will delete the current configuration and all generated files.h](h)}(hcYou may see the following error: "The source tree is not clean, please run 'make ARCH=um mrproper'"h]hkYou may see the following error: “The source tree is not clean, please run ‘make ARCH=um mrproper’”}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjJubh)}(hThis happens because internally kunit.py specifies ``.kunit`` (default option) as the build directory in the command ``make O=output/dir`` through the argument ``--build_dir``. Hence, before starting an out-of-tree build, the source tree must be clean.h](h3This happens because internally kunit.py specifies }(hj\hhhNhNubhliteral)}(h ``.kunit``h]h.kunit}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj\ubh8 (default option) as the build directory in the command }(hj\hhhNhNubje)}(h``make O=output/dir``h]hmake O=output/dir}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj\ubh through the argument }(hj\hhhNhNubje)}(h``--build_dir``h]h --build_dir}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj\ubhN. Hence, before starting an out-of-tree build, the source tree must be clean.}(hj\hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjJubh)}(hXvThere is also the same caveat mentioned in the "Build directory for the kernel" section of the :doc:`admin-guide `, that is, its use, it must be used for all invocations of ``make``. The good news is that it can indeed be solved by running ``make ARCH=um mrproper``, just be aware that this will delete the current configuration and all generated files.h](hcThere is also the same caveat mentioned in the “Build directory for the kernel” section of the }(hjhhhNhNubh)}(h(:doc:`admin-guide `h]hinline)}(hjh]h admin-guide}(hjhhhNhNubah}(h]h ](xrefstdstd-doceh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocdev-tools/kunit/start refdomainjreftypedoc refexplicitrefwarn reftarget/admin-guide/READMEuh1hhhhK#hjubh;, that is, its use, it must be used for all invocations of }(hjhhhNhNubje)}(h``make``h]hmake}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh;. The good news is that it can indeed be solved by running }(hjhhhNhNubje)}(h``make ARCH=um mrproper``h]hmake ARCH=um mrproper}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubhX, just be aware that this will delete the current configuration and all generated files.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK#hjJubeh}(h]h ]h"]h$]h&]uh1jHhjhhhhhNubh)}(h=If everything worked correctly, you should see the following:h]h=If everything worked correctly, you should see the following:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubj4)}(hPConfiguring KUnit Kernel ... Building KUnit Kernel ... Starting KUnit Kernel ...h]hPConfiguring KUnit Kernel ... Building KUnit Kernel ... Starting KUnit Kernel ...}hjsbah}(h]h ]h"]h$]h&]hhjCjDnonejF}uh1j3hhhK,hjhhubh)}(hThe tests will pass or fail.h]hThe tests will pass or fail.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjhhubjI)}(hpBecause it is building a lot of sources for the first time, the ``Building KUnit Kernel`` step may take a while.h]h)}(hpBecause it is building a lot of sources for the first time, the ``Building KUnit Kernel`` step may take a while.h](h@Because it is building a lot of sources for the first time, the }(hj3hhhNhNubje)}(h``Building KUnit Kernel``h]hBuilding KUnit Kernel}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj3ubh step may take a while.}(hj3hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK5hj/ubah}(h]h ]h"]h$]h&]uh1jHhjhhhhhNubh)}(h]For detailed information on this wrapper, see: Documentation/dev-tools/kunit/run_wrapper.rst.h]h]For detailed information on this wrapper, see: Documentation/dev-tools/kunit/run_wrapper.rst.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK8hjhhubh)}(hhh](h)}(hSelecting which tests to runh]hSelecting which tests to run}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjghhhhhKhjghhubh bullet_list)}(hhh](h list_item)}(h5`Customizing Kconfig`_ used to compile the kernel, orh]h)}(hjh](h reference)}(h`Customizing Kconfig`_h]hCustomizing Kconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameCustomizing Kconfigrefidcustomizing-kconfiguh1jhjresolvedKubh used to compile the kernel, or}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKBhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hO`Filtering tests by name`_ to select specifically which compiled tests to run. h]h)}(hN`Filtering tests by name`_ to select specifically which compiled tests to run.h](j)}(h`Filtering tests by name`_h]hFiltering tests by name}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFiltering tests by namejfiltering-tests-by-nameuh1jhjjKubh4 to select specifically which compiled tests to run.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKChjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKBhjghhubh)}(hhh](h)}(hCustomizing Kconfigh]hCustomizing Kconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKFubh)}(hA good starting point for the ``.kunitconfig`` is the KUnit default config. If you didn't run ``kunit.py run`` yet, you can generate it by running:h](hA good starting point for the }(hjhhhNhNubje)}(h``.kunitconfig``h]h .kunitconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh2 is the KUnit default config. If you didn’t run }(hjhhhNhNubje)}(h``kunit.py run``h]h kunit.py run}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh% yet, you can generate it by running:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKGhjhhubj4)}(hRcd $PATH_TO_LINUX_REPO tools/testing/kunit/kunit.py config cat .kunit/.kunitconfigh]hRcd $PATH_TO_LINUX_REPO tools/testing/kunit/kunit.py config cat .kunit/.kunitconfig}hj-sbah}(h]h ]h"]h$]h&]hhjCjDbashjF}uh1j3hhhKJhjhhubjI)}(h_``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is ``.kunit`` by default.h]h)}(h_``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is ``.kunit`` by default.h](je)}(h``.kunitconfig``h]h .kunitconfig}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjAubh lives in the }(hjAhhhNhNubje)}(h``--build_dir``h]h --build_dir}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjAubh used by kunit.py, which is }(hjAhhhNhNubje)}(h ``.kunit``h]h.kunit}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjAubh by default.}(hjAhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKQhj=ubah}(h]h ]h"]h$]h&]uh1jHhjhhhhhNubh)}(hBefore running the tests, kunit_tool ensures that all config options set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn you if you have not included dependencies for the options used.h](hLBefore running the tests, kunit_tool ensures that all config options set in }(hjhhhNhNubje)}(h``.kunitconfig``h]h .kunitconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh are set in the kernel }(hjhhhNhNubje)}(h ``.config``h]h.config}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubhN. It will warn you if you have not included dependencies for the options used.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKThjhhubh)}(h4There are many ways to customize the configurations:h]h4There are many ways to customize the configurations:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubhenumerated_list)}(hhh](j)}(hXpEdit ``.kunit/.kunitconfig``. The file should contain the list of kconfig options required to run the desired tests, including their dependencies. You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as it will enable a number of additional tests that you may not want. If you need to run on an architecture other than UML see :ref:`kunit-on-qemu`. h]h)}(hXoEdit ``.kunit/.kunitconfig``. The file should contain the list of kconfig options required to run the desired tests, including their dependencies. You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as it will enable a number of additional tests that you may not want. If you need to run on an architecture other than UML see :ref:`kunit-on-qemu`.h](hEdit }(hjhhhNhNubje)}(h``.kunit/.kunitconfig``h]h.kunit/.kunitconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh. The file should contain the list of kconfig options required to run the desired tests, including their dependencies. You may want to remove CONFIG_KUNIT_ALL_TESTS from the }(hjhhhNhNubje)}(h``.kunitconfig``h]h .kunitconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh as it will enable a number of additional tests that you may not want. If you need to run on an architecture other than UML see }(hjhhhNhNubh)}(h:ref:`kunit-on-qemu`h]j)}(hjh]h kunit-on-qemu}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj refdomainj reftyperef refexplicitrefwarnj kunit-on-qemuuh1hhhhKZhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKZhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hEnable additional kconfig options on top of ``.kunit/.kunitconfig``. For example, to include the kernel's linked-list test you can run:: ./tools/testing/kunit/kunit.py run \ --kconfig_add CONFIG_LIST_KUNIT_TEST=y h](h)}(hEnable additional kconfig options on top of ``.kunit/.kunitconfig``. For example, to include the kernel's linked-list test you can run::h](h,Enable additional kconfig options on top of }(hj0hhhNhNubje)}(h``.kunit/.kunitconfig``h]h.kunit/.kunitconfig}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj0ubhF. For example, to include the kernel’s linked-list test you can run:}(hj0hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK`hj,ubj4)}(hS./tools/testing/kunit/kunit.py run \ --kconfig_add CONFIG_LIST_KUNIT_TEST=yh]hS./tools/testing/kunit/kunit.py run \ --kconfig_add CONFIG_LIST_KUNIT_TEST=y}hjPsbah}(h]h ]h"]h$]h&]hhuh1j3hhhKchj,ubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXProvide the path of one or more .kunitconfig files from the tree. For example, to run only ``FAT_FS`` and ``EXT4`` tests you can run:: ./tools/testing/kunit/kunit.py run \ --kunitconfig ./fs/fat/.kunitconfig \ --kunitconfig ./fs/ext4/.kunitconfig h](h)}(hProvide the path of one or more .kunitconfig files from the tree. For example, to run only ``FAT_FS`` and ``EXT4`` tests you can run::h](h[Provide the path of one or more .kunitconfig files from the tree. For example, to run only }(hjhhhhNhNubje)}(h ``FAT_FS``h]hFAT_FS}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjhubh and }(hjhhhhNhNubje)}(h``EXT4``h]hEXT4}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjhubh tests you can run:}(hjhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKfhjdubj4)}(h./tools/testing/kunit/kunit.py run \ --kunitconfig ./fs/fat/.kunitconfig \ --kunitconfig ./fs/ext4/.kunitconfigh]h./tools/testing/kunit/kunit.py run \ --kunitconfig ./fs/fat/.kunitconfig \ --kunitconfig ./fs/ext4/.kunitconfig}hjsbah}(h]h ]h"]h$]h&]hhuh1j3hhhKihjdubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXIf you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the ``.config`` file. But you can edit the ``.config`` file directly or with tools like ``make menuconfig O=.kunit``. As long as its a superset of ``.kunitconfig``, kunit.py won't overwrite your changes. h]h)}(hXIf you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the ``.config`` file. But you can edit the ``.config`` file directly or with tools like ``make menuconfig O=.kunit``. As long as its a superset of ``.kunitconfig``, kunit.py won't overwrite your changes.h](hIf you change the }(hjhhhNhNubje)}(h``.kunitconfig``h]h .kunitconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh), kunit.py will trigger a rebuild of the }(hjhhhNhNubje)}(h ``.config``h]h.config}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh file. But you can edit the }(hjhhhNhNubje)}(h ``.config``h]h.config}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh" file directly or with tools like }(hjhhhNhNubje)}(h``make menuconfig O=.kunit``h]hmake menuconfig O=.kunit}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh. As long as its a superset of }(hjhhhNhNubje)}(h``.kunitconfig``h]h .kunitconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh*, kunit.py won’t overwrite your changes.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKmhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]enumtype loweralphaprefixhsuffix.uh1jhjhhhhhKZubjI)}(hTo save a .kunitconfig after finding a satisfactory configuration:: make savedefconfig O=.kunit cp .kunit/defconfig .kunit/.kunitconfigh](h)}(hCTo save a .kunitconfig after finding a satisfactory configuration::h]hBTo save a .kunitconfig after finding a satisfactory configuration:}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKuhj+ubj4)}(hCmake savedefconfig O=.kunit cp .kunit/defconfig .kunit/.kunitconfigh]hCmake savedefconfig O=.kunit cp .kunit/defconfig .kunit/.kunitconfig}hj=sbah}(h]h ]h"]h$]h&]hhuh1j3hhhKwhj+ubeh}(h]h ]h"]h$]h&]uh1jHhjhhhhhNubeh}(h]jah ]h"]customizing kconfigah$]h&]uh1hhjghhhhhKF referencedKubh)}(hhh](h)}(hFiltering tests by nameh]hFiltering tests by name}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjYhhhhhK{ubh)}(hXIf you want to be more specific than Kconfig can provide, it is also possible to select which tests to execute at boot-time by passing a glob filter (read instructions regarding the pattern in the manpage :manpage:`glob(7)`). If there is a ``"."`` (period) in the filter, it will be interpreted as a separator between the name of the test suite and the test case, otherwise, it will be interpreted as the name of the test suite. For example, let's assume we are using the default config:h](hIf you want to be more specific than Kconfig can provide, it is also possible to select which tests to execute at boot-time by passing a glob filter (read instructions regarding the pattern in the manpage }(hjjhhhNhNubhmanpage)}(h:manpage:`glob(7)`h]hglob(7)}(hjthhhNhNubah}(h]h ]jrah"]h$]h&]hhƌpathglob(7)pageglobsection7uh1jrhjjubh). If there is a }(hjjhhhNhNubje)}(h``"."``h]h"."}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjjubh (period) in the filter, it will be interpreted as a separator between the name of the test suite and the test case, otherwise, it will be interpreted as the name of the test suite. For example, let’s assume we are using the default config:}(hjjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK|hjYhhubj)}(hhh](j)}(hinform the name of a test suite, like ``"kunit_executor_test"``, to run every test case it contains:: ./tools/testing/kunit/kunit.py run "kunit_executor_test" h](h)}(heinform the name of a test suite, like ``"kunit_executor_test"``, to run every test case it contains::h](h&inform the name of a test suite, like }(hjhhhNhNubje)}(h``"kunit_executor_test"``h]h"kunit_executor_test"}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh%, to run every test case it contains:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubj4)}(h8./tools/testing/kunit/kunit.py run "kunit_executor_test"h]h8./tools/testing/kunit/kunit.py run "kunit_executor_test"}hjsbah}(h]h ]h"]h$]h&]hhuh1j3hhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hinform the name of a test case prefixed by its test suite, like ``"example.example_simple_test"``, to run specifically that test case:: ./tools/testing/kunit/kunit.py run "example.example_simple_test" h](h)}(hinform the name of a test case prefixed by its test suite, like ``"example.example_simple_test"``, to run specifically that test case::h](h@inform the name of a test case prefixed by its test suite, like }(hjhhhNhNubje)}(h!``"example.example_simple_test"``h]h"example.example_simple_test"}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh%, to run specifically that test case:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubj4)}(h@./tools/testing/kunit/kunit.py run "example.example_simple_test"h]h@./tools/testing/kunit/kunit.py run "example.example_simple_test"}hjsbah}(h]h ]h"]h$]h&]hhuh1j3hhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(huse wildcard characters (``*?[``) to run any test case that matches the pattern, like ``"*.*64*"`` to run test cases containing ``"64"`` in the name inside any test suite:: ./tools/testing/kunit/kunit.py run "*.*64*" h](h)}(huse wildcard characters (``*?[``) to run any test case that matches the pattern, like ``"*.*64*"`` to run test cases containing ``"64"`` in the name inside any test suite::h](huse wildcard characters (}(hjhhhNhNubje)}(h``*?[``h]h*?[}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh6) to run any test case that matches the pattern, like }(hjhhhNhNubje)}(h ``"*.*64*"``h]h"*.*64*"}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh to run test cases containing }(hjhhhNhNubje)}(h``"64"``h]h"64"}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh# in the name inside any test suite:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubj4)}(h+./tools/testing/kunit/kunit.py run "*.*64*"h]h+./tools/testing/kunit/kunit.py run "*.*64*"}hj_sbah}(h]h ]h"]h$]h&]hhuh1j3hhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]j&j'j(hj)j*uh1jhjYhhhhhKubeh}(h]jah ]h"]filtering tests by nameah$]h&]uh1hhjghhhhhK{jXKubeh}(h]selecting-which-tests-to-runah ]h"]selecting which tests to runah$]h&]uh1hhjhhhhhKSome lines and/or data may get interspersed in the TAP output.h]h)}(hjah]h>Some lines and/or data may get interspersed in the TAP output.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj_ubah}(h]h ]h"]h$]h&]uh1jHhj@hhhhhNubeh}(h]#running-tests-without-kunit-wrapperah ]h"]%running tests (without kunit wrapper)ah$]h&]uh1hhjhhhhhKubeh}(h]'running-tests-without-the-kunit-wrapperah ]h"]'running tests without the kunit wrapperah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hWriting Your First Testh]hWriting Your First Test}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h@In your kernel repository, let's add some code that we can test.h]hBIn your kernel repository, let’s add some code that we can test.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh]j)}(h:Create a file ``drivers/misc/example.h``, which includes: h]h)}(h9Create a file ``drivers/misc/example.h``, which includes:h](hCreate a file }(hjhhhNhNubje)}(h``drivers/misc/example.h``h]hdrivers/misc/example.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh, which includes:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]j&arabicj(hj)j*uh1jhjhhhhhKubj4)}(h*int misc_example_add(int left, int right);h]h*int misc_example_add(int left, int right);}hjsbah}(h]h ]h"]h$]h&]hhjCjDcjF}uh1j3hhhKhjhhubj)}(hhh]j)}(h:Create a file ``drivers/misc/example.c``, which includes: h]h)}(h9Create a file ``drivers/misc/example.c``, which includes:h](hCreate a file }(hjhhhNhNubje)}(h``drivers/misc/example.c``h]hdrivers/misc/example.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjubh, which includes:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]j&jj(hj)j*startKuh1jhjhhhhhKubj4)}(hz#include #include "example.h" int misc_example_add(int left, int right) { return left + right; }h]hz#include #include "example.h" int misc_example_add(int left, int right) { return left + right; }}hjsbah}(h]h ]h"]h$]h&]hhjCjDjjF}uh1j3hhhKhjhhubj)}(hhh]j)}(h5Add the following lines to ``drivers/misc/Kconfig``: h]h)}(h4Add the following lines to ``drivers/misc/Kconfig``:h](hAdd the following lines to }(hj3hhhNhNubje)}(h``drivers/misc/Kconfig``h]hdrivers/misc/Kconfig}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj3ubh:}(hj3hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj/ubah}(h]h ]h"]h$]h&]uh1jhj,hhhhhNubah}(h]h ]h"]h$]h&]j&jj(hj)j*jKuh1jhjhhhhhKubj4)}(h-config MISC_EXAMPLE bool "My example"h]h-config MISC_EXAMPLE bool "My example"}hj_sbah}(h]h ]h"]h$]h&]hhjCjDkconfigjF}uh1j3hhhKhjhhubj)}(hhh]j)}(h6Add the following lines to ``drivers/misc/Makefile``: h]h)}(h5Add the following lines to ``drivers/misc/Makefile``:h](hAdd the following lines to }(hjvhhhNhNubje)}(h``drivers/misc/Makefile``h]hdrivers/misc/Makefile}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjvubh:}(hjvhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjrubah}(h]h ]h"]h$]h&]uh1jhjohhhhhNubah}(h]h ]h"]h$]h&]j&jj(hj)j*jKuh1jhjhhhhhKubj4)}(h'obj-$(CONFIG_MISC_EXAMPLE) += example.oh]h'obj-$(CONFIG_MISC_EXAMPLE) += example.o}hjsbah}(h]h ]h"]h$]h&]hhjCjDmakejF}uh1j3hhhKhjhhubh)}(h)Now we are ready to write the test cases.h]h)Now we are ready to write the test cases.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh]j)}(h #include "example.h" /* Define the test cases. */ static void misc_example_add_test_basic(struct kunit *test) { KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0)); KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1)); KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1)); KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX)); KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN)); } static void misc_example_test_failure(struct kunit *test) { KUNIT_FAIL(test, "This test never passes."); } static struct kunit_case misc_example_test_cases[] = { KUNIT_CASE(misc_example_add_test_basic), KUNIT_CASE(misc_example_test_failure), {} }; static struct kunit_suite misc_example_test_suite = { .name = "misc-example", .test_cases = misc_example_test_cases, }; kunit_test_suite(misc_example_test_suite); MODULE_LICENSE("GPL");h]hX#include #include "example.h" /* Define the test cases. */ static void misc_example_add_test_basic(struct kunit *test) { KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0)); KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1)); KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1)); KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX)); KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN)); } static void misc_example_test_failure(struct kunit *test) { KUNIT_FAIL(test, "This test never passes."); } static struct kunit_case misc_example_test_cases[] = { KUNIT_CASE(misc_example_add_test_basic), KUNIT_CASE(misc_example_test_failure), {} }; static struct kunit_suite misc_example_test_suite = { .name = "misc-example", .test_cases = misc_example_test_cases, }; kunit_test_suite(misc_example_test_suite); MODULE_LICENSE("GPL");}hjsbah}(h]h ]h"]h$]h&]hhjCjDjjF}uh1j3hhhKhjhhubj)}(hhh]j)}(h5Add the following lines to ``drivers/misc/Kconfig``: h]h)}(h4Add the following lines to ``drivers/misc/Kconfig``:h](hAdd the following lines to }(hj hhhNhNubje)}(h``drivers/misc/Kconfig``h]hdrivers/misc/Kconfig}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubah}(h]h ]h"]h$]h&]j&jj(hj)j*jKuh1jhjhhhhhKubj4)}(hconfig MISC_EXAMPLE_TEST tristate "Test for my example" if !KUNIT_ALL_TESTS depends on MISC_EXAMPLE && KUNIT default KUNIT_ALL_TESTSh]hconfig MISC_EXAMPLE_TEST tristate "Test for my example" if !KUNIT_ALL_TESTS depends on MISC_EXAMPLE && KUNIT default KUNIT_ALL_TESTS}hj5 sbah}(h]h ]h"]h$]h&]hhjCjDkconfigjF}uh1j3hhhMhjhhubh)}(hNote: If your test does not support being built as a loadable module (which is discouraged), replace tristate by bool, and depend on KUNIT=y instead of KUNIT.h]hNote: If your test does not support being built as a loadable module (which is discouraged), replace tristate by bool, and depend on KUNIT=y instead of KUNIT.}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh]j)}(h6Add the following lines to ``drivers/misc/Makefile``: h]h)}(h5Add the following lines to ``drivers/misc/Makefile``:h](hAdd the following lines to }(hjZ hhhNhNubje)}(h``drivers/misc/Makefile``h]hdrivers/misc/Makefile}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhjZ ubh:}(hjZ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjV ubah}(h]h ]h"]h$]h&]uh1jhjS hhhhhNubah}(h]h ]h"]h$]h&]j&jj(hj)j*jKuh1jhjhhhhhM ubj4)}(h1obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.oh]h1obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o}hj sbah}(h]h ]h"]h$]h&]hhjCjDmakejF}uh1j3hhhM hjhhubj)}(hhh]j)}(h4Add the following lines to ``.kunit/.kunitconfig``: h]h)}(h3Add the following lines to ``.kunit/.kunitconfig``:h](hAdd the following lines to }(hj hhhNhNubje)}(h``.kunit/.kunitconfig``h]h.kunit/.kunitconfig}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jdhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubah}(h]h ]h"]h$]h&]j&jj(hj)j*jKuh1jhjhhhhhMubj4)}(h0CONFIG_MISC_EXAMPLE=y CONFIG_MISC_EXAMPLE_TEST=yh]h0CONFIG_MISC_EXAMPLE=y CONFIG_MISC_EXAMPLE_TEST=y}hj sbah}(h]h ]h"]h$]h&]hhjCjDnonejF}uh1j3hhhMhjhhubj)}(hhh]j)}(hRun the test: h]h)}(h Run the test:h]h Run the test:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubah}(h]h ]h"]h$]h&]j&jj(hj)j*jKuh1jhjhhhhhMubj4)}(h"./tools/testing/kunit/kunit.py runh]h"./tools/testing/kunit/kunit.py run}hj sbah}(h]h ]h"]h$]h&]hhjCjDbashjF}uh1j3hhhMhjhhubh)}(h%You should see the following failure:h]h%You should see the following failure:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj4)}(h... [16:08:57] [PASSED] misc-example:misc_example_add_test_basic [16:08:57] [FAILED] misc-example:misc_example_test_failure [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 [16:08:57] This test never passes. ...h]h... [16:08:57] [PASSED] misc-example:misc_example_add_test_basic [16:08:57] [FAILED] misc-example:misc_example_test_failure [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 [16:08:57] This test never passes. ...}hj sbah}(h]h ]h"]h$]h&]hhjCjDnonejF}uh1j3hhhM hjhhubh)}(h/Congrats! You just wrote your first KUnit test.h]h/Congrats! You just wrote your first KUnit test.}(hj( hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hjhhubeh}(h]writing-your-first-testah ]h"]writing your first testah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Next Stepsh]h Next Steps}(hjA hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj> hhhhhM,ubh)}(hIf you're interested in using some of the more advanced features of kunit.py, take a look at Documentation/dev-tools/kunit/run_wrapper.rsth]hIf you’re interested in using some of the more advanced features of kunit.py, take a look at Documentation/dev-tools/kunit/run_wrapper.rst}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM.hj> hhubh)}(hiIf you'd like to run tests without using kunit.py, check out Documentation/dev-tools/kunit/run_manual.rsth]hkIf you’d like to run tests without using kunit.py, check out Documentation/dev-tools/kunit/run_manual.rst}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM1hj> hhubh)}(hFor more information on writing KUnit tests (including some common techniques for testing different things), see Documentation/dev-tools/kunit/usage.rsth]hFor more information on writing KUnit tests (including some common techniques for testing different things), see Documentation/dev-tools/kunit/usage.rst}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hj> hhubeh}(h] next-stepsah ]h"] next stepsah$]h&]uh1hhhhhhhhM,ubeh}(h]getting-startedah ]h"]getting startedah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(customizing kconfig]jafiltering tests by name]jaurefids}nameids}(j j jjjjjjjUjj}jjjj=j:j{jxj; j8 j~ j{ u nametypes}(j jjjjUj}jj=j{j; j~ uh}(j hjhjjjjgjjjjYjjj:jjxj@j8 jj{ j> u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages](hsystem_message)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "2" (ordinal 2)h]h>Enumerated list start value not ordinal-1: “2” (ordinal 2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehnjlineKuh1j hjhhhhhKubj )}(hhh]h)}(h:Enumerated list start value not ordinal-1: "3" (ordinal 3)h]h>Enumerated list start value not ordinal-1: “3” (ordinal 3)}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj0 ubah}(h]h ]h"]h$]h&]levelKtypej- sourcehnjlineKuh1j hjhhhhhKubj )}(hhh]h)}(h:Enumerated list start value not ordinal-1: "4" (ordinal 4)h]h>Enumerated list start value not ordinal-1: “4” (ordinal 4)}(hjN hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjK ubah}(h]h ]h"]h$]h&]levelKtypej- sourcehnjlineKuh1j hjhhhhhKubj )}(hhh]h)}(h:Enumerated list start value not ordinal-1: "2" (ordinal 2)h]h>Enumerated list start value not ordinal-1: “2” (ordinal 2)}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjf ubah}(h]h ]h"]h$]h&]levelKtypej- sourcehnjlineKuh1j hjhhhhhKubj )}(hhh]h)}(h:Enumerated list start value not ordinal-1: "3" (ordinal 3)h]h>Enumerated list start value not ordinal-1: “3” (ordinal 3)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej- sourcehnjlineKuh1j hjhhhhhM ubj )}(hhh]h)}(h:Enumerated list start value not ordinal-1: "4" (ordinal 4)h]h>Enumerated list start value not ordinal-1: “4” (ordinal 4)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej- sourcehnjlineKuh1j hjhhhhhMubj )}(hhh]h)}(h:Enumerated list start value not ordinal-1: "5" (ordinal 5)h]h>Enumerated list start value not ordinal-1: “5” (ordinal 5)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej- sourcehnjlineKuh1j hjhhhhhMubetransform_messages] transformerN include_log] decorationNhhub.