| .. 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. | |
| KUnit Wrapper | |
| ============= | |
| Included with KUnit is a simple Python wrapper that helps format the output to | |
| easily use and read KUnit output. It handles building and running the kernel, as | |
| well as formatting the output. | |
| The wrapper can be run with: | |
| .. code-block:: bash | |
| ./tools/testing/kunit/kunit.py run | |
| Creating a kunitconfig | |
| ====================== | |
| The Python script is a thin wrapper around Kbuild as such, it needs to be | |
| configured with a ``kunitconfig`` file. This file essentially contains the | |
| regular Kernel config, with the specific test targets as well. | |
| .. code-block:: bash | |
| git clone -b kunit/alpha/master https://kunit.googlesource.com/kunitconfig $PATH_TO_KUNITCONFIG_REPO | |
| cd $PATH_TO_LINUX_REPO | |
| ln -s $PATH_TO_KUNITCONFIG_REPO/kunitconfig kunitconfig | |
| You may want to add kunitconfig to your local gitignore. | |
| Verifying KUnit Works | |
| ------------------------- | |
| To make sure that everything is set up correctly, simply invoke the Python | |
| wrapper from your kernel repo: | |
| .. code-block:: bash | |
| ./tools/testing/kunit/kunit.py run | |
| .. note:: | |
| You may want to run ``make mrproper`` first. | |
| If everything worked correctly, you should see the following: | |
| .. code-block:: bash | |
| Generating .config ... | |
| Building KUnit Kernel ... | |
| Starting KUnit Kernel ... | |
| followed by a list of tests that are run. All of them should be passing. | |
| .. note:: | |
| Because it is building a lot of sources for the first time, the ``Building | |
| kunit kernel`` step may take a while. | |
| Writing your first test | |
| ========================== | |
| In your kernel repo let's add some code that we can test. Create a file | |
| ``drivers/misc/example.h`` with the contents: | |
| .. code-block:: c | |
| struct misc_example { | |
| int (*misc_example_foo)(struct misc_example *, int); | |
| }; | |
| int misc_example_bar(struct misc_example *example); | |
| create a file ``drivers/misc/example.c``: | |
| .. code-block:: c | |
| #include <linux/errno.h> | |
| #include "example.h" | |
| int misc_example_bar(struct misc_example *example) | |
| { | |
| if (example->misc_example_foo(example, 5)) | |
| return -EIO; | |
| else | |
| return 0; | |
| } | |
| Now add the following lines to ``drivers/misc/Kconfig``: | |
| .. code-block:: kconfig | |
| config MISC_EXAMPLE | |
| bool "My example" | |
| and the following lines to ``drivers/misc/Makefile``: | |
| .. code-block:: make | |
| obj-$(CONFIG_MISC_EXAMPLE) += example.o | |
| Now we are ready to write the test. The test will be in | |
| ``drivers/misc/example-test.c``: | |
| .. code-block:: c | |
| #include <test/test.h> | |
| #include <test/mock.h> | |
| #include "example.h" | |
| /* Define the mock. */ | |
| DECLARE_STRUCT_CLASS_MOCK_PREREQS(misc_example); | |
| DEFINE_STRUCT_CLASS_MOCK(METHOD(misc_example_foo), CLASS(misc_example), | |
| RETURNS(int), | |
| PARAMS(struct misc_example *, int)); | |
| static int misc_example_init(struct MOCK(misc_example) *mock_example) | |
| { | |
| struct misc_example *example = mock_get_trgt(mock_example); | |
| example->misc_example_foo = misc_example_foo; | |
| return 0; | |
| } | |
| DEFINE_STRUCT_CLASS_MOCK_INIT(misc_example, misc_example_init); | |
| /* Define the test cases. */ | |
| static void misc_example_bar_test_success(struct test *test) | |
| { | |
| struct MOCK(misc_example) *mock_example = test->priv; | |
| struct misc_example *example = mock_get_trgt(mock_example); | |
| struct mock_expectation *handle; | |
| handle = EXPECT_CALL(misc_example_foo(mock_get_ctrl(mock_example), | |
| int_eq(test, 5))); | |
| handle->action = int_return(test, 0); | |
| EXPECT_EQ(test, 0, misc_example_bar(example)); | |
| } | |
| static void misc_example_bar_test_failure(struct test *test) | |
| { | |
| struct MOCK(misc_example) *mock_example = test->priv; | |
| struct misc_example *example = mock_get_trgt(mock_example); | |
| struct mock_expectation *handle; | |
| handle = EXPECT_CALL(misc_example_foo(mock_get_ctrl(mock_example), | |
| int_eq(test, 5))); | |
| handle->action = int_return(test, -EINVAL); | |
| EXPECT_EQ(test, -EINVAL, misc_example_bar(example)); | |
| } | |
| static int misc_example_test_init(struct test *test) | |
| { | |
| test->priv = CONSTRUCT_MOCK(misc_example, test); | |
| if (!test->priv) | |
| return -EINVAL; | |
| return 0; | |
| } | |
| static void misc_example_test_exit(struct test *test) | |
| { | |
| } | |
| static struct test_case misc_example_test_cases[] = { | |
| TEST_CASE(misc_example_bar_test_success), | |
| TEST_CASE(misc_example_bar_test_failure), | |
| {}, | |
| }; | |
| static struct test_module misc_example_test_module = { | |
| .name = "misc-example", | |
| .init = misc_example_test_init, | |
| .exit = misc_example_test_exit, | |
| .test_cases = misc_example_test_cases, | |
| }; | |
| module_test(misc_example_test_module); | |
| Now add the following to ``drivers/misc/Kconfig``: | |
| .. code-block:: kconfig | |
| config MISC_EXAMPLE_TEST | |
| bool "Test for my example" | |
| depends on MISC_EXAMPLE && TEST | |
| and the following to ``drivers/misc/Makefile``: | |
| .. code-block:: make | |
| obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o | |
| Now add it to your ``kunitconfig``: | |
| .. code-block:: none | |
| CONFIG_MISC_EXAMPLE=y | |
| CONFIG_MISC_EXAMPLE_TEST=y | |
| Now you can run the test: | |
| .. code-block:: bash | |
| ./tools/testing/kunit/kunit.py run | |
| You should see the following failure: | |
| .. code-block:: none | |
| ... | |
| kunit misc-example: misc_example_bar_test_success passed | |
| kunit misc-example: EXPECTATION FAILED at drivers/misc/example-test.c:48 | |
| Expected -22 == misc_example_bar(example), but | |
| -22 == -22 | |
| misc_example_bar(example) == -5 | |
| kunit misc-example: misc_example_bar_test_failure failed | |
| kunit misc-example: one or more tests failed | |
| Congrats! You just wrote your first KUnit test! | |
| Next Steps | |
| ============= | |
| * Check out the :doc:`usage` page for a more | |
| in-depth explanation of KUnit. |