1.. SPDX-License-Identifier: GPL-2.0
2
3===============
4Getting Started
5===============
6
7Installing dependencies
8=======================
9KUnit has the same dependencies as the Linux kernel. As long as you can build
10the kernel, you can run KUnit.
11
12KUnit Wrapper
13=============
14Included with KUnit is a simple Python wrapper that helps format the output to
15easily use and read KUnit output. It handles building and running the kernel, as
16well as formatting the output.
17
18The wrapper can be run with:
19
20.. code-block:: bash
21
22	./tools/testing/kunit/kunit.py run --defconfig
23
24For more information on this wrapper (also called kunit_tool) checkout the
25:doc:`kunit-tool` page.
26
27Creating a .kunitconfig
28=======================
29The Python script is a thin wrapper around Kbuild. As such, it needs to be
30configured with a ``.kunitconfig`` file. This file essentially contains the
31regular Kernel config, with the specific test targets as well.
32
33.. code-block:: bash
34
35	cd $PATH_TO_LINUX_REPO
36	cp arch/um/configs/kunit_defconfig .kunitconfig
37
38Verifying KUnit Works
39---------------------
40
41To make sure that everything is set up correctly, simply invoke the Python
42wrapper from your kernel repo:
43
44.. code-block:: bash
45
46	./tools/testing/kunit/kunit.py run
47
48.. note::
49   You may want to run ``make mrproper`` first.
50
51If everything worked correctly, you should see the following:
52
53.. code-block:: bash
54
55	Generating .config ...
56	Building KUnit Kernel ...
57	Starting KUnit Kernel ...
58
59followed by a list of tests that are run. All of them should be passing.
60
61.. note::
62	Because it is building a lot of sources for the first time, the
63	``Building KUnit kernel`` step may take a while.
64
65Writing your first test
66=======================
67
68In your kernel repo let's add some code that we can test. Create a file
69``drivers/misc/example.h`` with the contents:
70
71.. code-block:: c
72
73	int misc_example_add(int left, int right);
74
75create a file ``drivers/misc/example.c``:
76
77.. code-block:: c
78
79	#include <linux/errno.h>
80
81	#include "example.h"
82
83	int misc_example_add(int left, int right)
84	{
85		return left + right;
86	}
87
88Now add the following lines to ``drivers/misc/Kconfig``:
89
90.. code-block:: kconfig
91
92	config MISC_EXAMPLE
93		bool "My example"
94
95and the following lines to ``drivers/misc/Makefile``:
96
97.. code-block:: make
98
99	obj-$(CONFIG_MISC_EXAMPLE) += example.o
100
101Now we are ready to write the test. The test will be in
102``drivers/misc/example-test.c``:
103
104.. code-block:: c
105
106	#include <kunit/test.h>
107	#include "example.h"
108
109	/* Define the test cases. */
110
111	static void misc_example_add_test_basic(struct kunit *test)
112	{
113		KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0));
114		KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1));
115		KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1));
116		KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX));
117		KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN));
118	}
119
120	static void misc_example_test_failure(struct kunit *test)
121	{
122		KUNIT_FAIL(test, "This test never passes.");
123	}
124
125	static struct kunit_case misc_example_test_cases[] = {
126		KUNIT_CASE(misc_example_add_test_basic),
127		KUNIT_CASE(misc_example_test_failure),
128		{}
129	};
130
131	static struct kunit_suite misc_example_test_suite = {
132		.name = "misc-example",
133		.test_cases = misc_example_test_cases,
134	};
135	kunit_test_suite(misc_example_test_suite);
136
137Now add the following to ``drivers/misc/Kconfig``:
138
139.. code-block:: kconfig
140
141	config MISC_EXAMPLE_TEST
142		bool "Test for my example"
143		depends on MISC_EXAMPLE && KUNIT
144
145and the following to ``drivers/misc/Makefile``:
146
147.. code-block:: make
148
149	obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o
150
151Now add it to your ``.kunitconfig``:
152
153.. code-block:: none
154
155	CONFIG_MISC_EXAMPLE=y
156	CONFIG_MISC_EXAMPLE_TEST=y
157
158Now you can run the test:
159
160.. code-block:: bash
161
162	./tools/testing/kunit/kunit.py run
163
164You should see the following failure:
165
166.. code-block:: none
167
168	...
169	[16:08:57] [PASSED] misc-example:misc_example_add_test_basic
170	[16:08:57] [FAILED] misc-example:misc_example_test_failure
171	[16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17
172	[16:08:57] 	This test never passes.
173	...
174
175Congrats! You just wrote your first KUnit test!
176
177Next Steps
178==========
179*   Check out the :doc:`usage` page for a more
180    in-depth explanation of KUnit.
181