OSCL-LXR linux-6.0.1/​Documentation/​dev-tools/​kunit/​start.rst	Source navigation Diff markup Identifier search General search
	Version: linux-6.0.1 spark-3.0.0 hadoop-3.2.0-src hadoop-3.3.0-src spark-2.4.7 linux-4.15.13 hadoop-2.7.4-src Revert   Change

 .. SPDX-License-Identifier: GPL-2.0
 
 ===============
 Getting Started
 ===============
 
 Installing Dependencies
 =======================
 KUnit has the same dependencies as the Linux kernel. As long as you can
 build the kernel, you can run KUnit.
 
 Running tests with kunit_tool
 =============================
 kunit_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:
 
 .. code-block:: bash
 
         ./tools/testing/kunit/kunit.py run
 
 For more information on this wrapper, see:
 Documentation/dev-tools/kunit/run_wrapper.rst.
 
 Creating a ``.kunitconfig``
 ---------------------------
 
 By default, kunit_tool runs a selection of tests. However, you can specify which
 unit tests to run by creating a ``.kunitconfig`` file with kernel config options
 that enable only a specific set of tests and their dependencies.
 The ``.kunitconfig`` file contains a list of kconfig options which are required
 to run the desired targets. The ``.kunitconfig`` also contains any other test
 specific config options, such as test dependencies. For example: the
 ``FAT_FS`` tests - ``FAT_KUNIT_TEST``, depends on
 ``FAT_FS``. ``FAT_FS`` can be enabled by selecting either ``MSDOS_FS``
 or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has:
 
 .. code-block:: none
 
         CONFIG_KUNIT=y
         CONFIG_MSDOS_FS=y
         CONFIG_FAT_KUNIT_TEST=y
 
 1. A good starting point for the ``.kunitconfig`` is the KUnit default config.
    You can generate it by running:
 
 .. code-block:: bash
 
         cd $PATH_TO_LINUX_REPO
         tools/testing/kunit/kunit.py config
         cat .kunit/.kunitconfig
 
 .. note ::
    ``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is
    ``.kunit`` by default.
 
 .. note ::
    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.
 
 2. You can then add any other Kconfig options, for example:
 
 .. code-block:: none
 
         CONFIG_LIST_KUNIT_TEST=y
 
 Before 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.
 
 .. note ::
    If 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.
 
 Running Tests (KUnit Wrapper)
 -----------------------------
 1. To make sure that everything is set up correctly, invoke the Python
    wrapper from your kernel repository:
 
 .. code-block:: bash
 
         ./tools/testing/kunit/kunit.py run
 
 If everything worked correctly, you should see the following:
 
 .. code-block::
 
         Generating .config ...
         Building KUnit Kernel ...
         Starting KUnit Kernel ...
 
 The tests will pass or fail.
 
 .. note ::
    Because it is building a lot of sources for the first time, the
    ``Building KUnit kernel`` may take a while.
 
 Running Tests without the KUnit Wrapper
 =======================================
 If you do not want to use the KUnit Wrapper (for example: you want code
 under test to integrate with other systems, or use a different/
 unsupported architecture or configuration), KUnit can be included in
 any kernel, and the results are read out and parsed manually.
 
 .. note ::
    ``CONFIG_KUNIT`` should not be enabled in a production environment.
    Enabling KUnit disables Kernel Address-Space Layout Randomization
    (KASLR), and tests may affect the state of the kernel in ways not
    suitable for production.
 
 Configuring the Kernel
 ----------------------
 To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig
 option (under Kernel Hacking/Kernel Testing and Coverage in
 ``menuconfig``). From there, you can enable any KUnit tests. They
 usually have config options ending in ``_KUNIT_TEST``.
 
 KUnit and KUnit tests can be compiled as modules. The tests in a module
 will run when the module is loaded.
 
 Running Tests (without KUnit Wrapper)
 -------------------------------------
 Build and run your kernel. In the kernel log, the test output is printed
 out in the TAP format. This will only happen by default if KUnit/tests
 are built-in. Otherwise the module will need to be loaded.
 
 .. note ::
    Some lines and/or data may get interspersed in the TAP output.
 
 Writing Your First Test
 =======================
 In your kernel repository, let's add some code that we can test.
 
 1. Create a file ``drivers/misc/example.h``, which includes:
 
 .. code-block:: c
 
         int misc_example_add(int left, int right);
 
 2. Create a file ``drivers/misc/example.c``, which includes:
 
 .. code-block:: c
 
         #include <linux/errno.h>
 
         #include "example.h"
 
         int misc_example_add(int left, int right)
         {
                 return left + right;
         }
 
 3. Add the following lines to ``drivers/misc/Kconfig``:
 
 .. code-block:: kconfig
 
         config MISC_EXAMPLE
                 bool "My example"
 
 4. Add the following lines to ``drivers/misc/Makefile``:
 
 .. code-block:: make
 
         obj-$(CONFIG_MISC_EXAMPLE) += example.o
 
 Now we are ready to write the test cases.
 
 1. Add the below test case in ``drivers/misc/example_test.c``:
 
 .. code-block:: c
 
         #include <kunit/test.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);
 
 2. Add the following lines to ``drivers/misc/Kconfig``:
 
 .. code-block:: kconfig
 
         config MISC_EXAMPLE_TEST
                 tristate "Test for my example" if !KUNIT_ALL_TESTS
                 depends on MISC_EXAMPLE && KUNIT=y
                 default KUNIT_ALL_TESTS
 
 3. Add the following lines to ``drivers/misc/Makefile``:
 
 .. code-block:: make
 
         obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o
 
 4. Add the following lines to ``.kunitconfig``:
 
 .. code-block:: none
 
         CONFIG_MISC_EXAMPLE=y
         CONFIG_MISC_EXAMPLE_TEST=y
 
 5. Run the test:
 
 .. code-block:: bash
 
         ./tools/testing/kunit/kunit.py run
 
 You should see the following failure:
 
 .. code-block:: none
 
         ...
         [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.
         ...
 
 Congrats! You just wrote your first KUnit test.
 
 Next Steps
 ==========
 
 *   Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
 *   Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
 *   Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
 *   Documentation/dev-tools/kunit/usage.rst - write tests.
 *   Documentation/dev-tools/kunit/tips.rst - best practices with
     examples.
 *   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
     used for testing.
 *   Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
     script.
 *   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
     answers.

This page was automatically generated by the 2.1.0 LXR engine. The LXR team