1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
>> 3 ===========
>> 4 Using KUnit
>> 5 ===========
>> 6
>> 7 The purpose of this document is to describe what KUnit is, how it works, how it
>> 8 is intended to be used, and all the concepts and terminology that are needed to
>> 9 understand it. This guide assumes a working knowledge of the Linux kernel and
>> 10 some basic knowledge of testing.
>> 11
>> 12 For a high level introduction to KUnit, including setting up KUnit for your
>> 13 project, see Documentation/dev-tools/kunit/start.rst.
>> 14
>> 15 Organization of this document
>> 16 =============================
>> 17
>> 18 This document is organized into two main sections: Testing and Common Patterns.
>> 19 The first covers what unit tests are and how to use KUnit to write them. The
>> 20 second covers common testing patterns, e.g. how to isolate code and make it
>> 21 possible to unit test code that was otherwise un-unit-testable.
>> 22
>> 23 Testing
>> 24 =======
>> 25
>> 26 What is KUnit?
>> 27 --------------
>> 28
>> 29 "K" is short for "kernel" so "KUnit" is the "(Linux) Kernel Unit Testing
>> 30 Framework." KUnit is intended first and foremost for writing unit tests; it is
>> 31 general enough that it can be used to write integration tests; however, this is
>> 32 a secondary goal. KUnit has no ambition of being the only testing framework for
>> 33 the kernel; for example, it does not intend to be an end-to-end testing
>> 34 framework.
>> 35
>> 36 What is Unit Testing?
>> 37 ---------------------
>> 38
>> 39 A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is a test that
>> 40 tests code at the smallest possible scope, a *unit* of code. In the C
>> 41 programming language that's a function.
>> 42
>> 43 Unit tests should be written for all the publicly exposed functions in a
>> 44 compilation unit; so that is all the functions that are exported in either a
>> 45 *class* (defined below) or all functions which are **not** static.
>> 46
3 Writing Tests 47 Writing Tests
4 ============= !! 48 -------------
5 49
6 Test Cases 50 Test Cases
7 ---------- !! 51 ~~~~~~~~~~
8 52
9 The fundamental unit in KUnit is the test case 53 The fundamental unit in KUnit is the test case. A test case is a function with
10 the signature ``void (*)(struct kunit *test)`` !! 54 the signature ``void (*)(struct kunit *test)``. It calls a function to be tested
11 and then sets *expectations* for what should h 55 and then sets *expectations* for what should happen. For example:
12 56
13 .. code-block:: c 57 .. code-block:: c
14 58
15 void example_test_success(struct kunit 59 void example_test_success(struct kunit *test)
16 { 60 {
17 } 61 }
18 62
19 void example_test_failure(struct kunit 63 void example_test_failure(struct kunit *test)
20 { 64 {
21 KUNIT_FAIL(test, "This test ne 65 KUNIT_FAIL(test, "This test never passes.");
22 } 66 }
23 67
24 In the above example, ``example_test_success`` !! 68 In the above example ``example_test_success`` always passes because it does
25 nothing; no expectations are set, and therefor !! 69 nothing; no expectations are set, so all expectations pass. On the other hand
26 other hand ``example_test_failure`` always fai !! 70 ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, which is
27 which is a special expectation that logs a mes !! 71 a special expectation that logs a message and causes the test case to fail.
28 fail. <<
29 72
30 Expectations 73 Expectations
31 ~~~~~~~~~~~~ 74 ~~~~~~~~~~~~
32 An *expectation* specifies that we expect a pi !! 75 An *expectation* is a way to specify that you expect a piece of code to do
33 test. An expectation is called like a function !! 76 something in a test. An expectation is called like a function. A test is made
34 expectations about the behavior of a piece of !! 77 by setting expectations about the behavior of a piece of code under test; when
35 expectations fail, the test case fails and inf !! 78 one or more of the expectations fail, the test case fails and information about
36 logged. For example: !! 79 the failure is logged. For example:
37 80
38 .. code-block:: c 81 .. code-block:: c
39 82
40 void add_test_basic(struct kunit *test 83 void add_test_basic(struct kunit *test)
41 { 84 {
42 KUNIT_EXPECT_EQ(test, 1, add(1 85 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
43 KUNIT_EXPECT_EQ(test, 2, add(1 86 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
44 } 87 }
45 88
46 In the above example, ``add_test_basic`` makes !! 89 In the above example ``add_test_basic`` makes a number of assertions about the
47 behavior of a function called ``add``. The fir !! 90 behavior of a function called ``add``; the first parameter is always of type
48 ``struct kunit *``, which contains information !! 91 ``struct kunit *``, which contains information about the current test context;
49 The second parameter, in this case, is what th !! 92 the second parameter, in this case, is what the value is expected to be; the
50 last value is what the value actually is. If ` 93 last value is what the value actually is. If ``add`` passes all of these
51 expectations, the test case, ``add_test_basic` 94 expectations, the test case, ``add_test_basic`` will pass; if any one of these
52 expectations fails, the test case will fail. 95 expectations fails, the test case will fail.
53 96
54 A test case *fails* when any expectation is vi !! 97 It is important to understand that a test case *fails* when any expectation is
55 continue to run, and try other expectations un !! 98 violated; however, the test will continue running, potentially trying other
56 otherwise terminated. This is as opposed to *a !! 99 expectations until the test case ends or is otherwise terminated. This is as
57 later. !! 100 opposed to *assertions* which are discussed later.
58 101
59 To learn about more KUnit expectations, see Do !! 102 To learn about more expectations supported by KUnit, see
>> 103 Documentation/dev-tools/kunit/api/test.rst.
60 104
61 .. note:: 105 .. note::
62 A single test case should be short, easy to !! 106 A single test case should be pretty short, pretty easy to understand,
63 single behavior. !! 107 focused on a single behavior.
64 108
65 For example, if we want to rigorously test the !! 109 For example, if we wanted to properly test the add function above, we would
66 additional tests cases which would test each p !! 110 create additional tests cases which would each test a different property that an
67 should have as shown below: !! 111 add function should have like this:
68 112
69 .. code-block:: c 113 .. code-block:: c
70 114
71 void add_test_basic(struct kunit *test 115 void add_test_basic(struct kunit *test)
72 { 116 {
73 KUNIT_EXPECT_EQ(test, 1, add(1 117 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
74 KUNIT_EXPECT_EQ(test, 2, add(1 118 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
75 } 119 }
76 120
77 void add_test_negative(struct kunit *t 121 void add_test_negative(struct kunit *test)
78 { 122 {
79 KUNIT_EXPECT_EQ(test, 0, add(- 123 KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
80 } 124 }
81 125
82 void add_test_max(struct kunit *test) 126 void add_test_max(struct kunit *test)
83 { 127 {
84 KUNIT_EXPECT_EQ(test, INT_MAX, 128 KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
85 KUNIT_EXPECT_EQ(test, -1, add( 129 KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
86 } 130 }
87 131
88 void add_test_overflow(struct kunit *t 132 void add_test_overflow(struct kunit *test)
89 { 133 {
90 KUNIT_EXPECT_EQ(test, INT_MIN, 134 KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
91 } 135 }
92 136
>> 137 Notice how it is immediately obvious what all the properties that we are testing
>> 138 for are.
>> 139
93 Assertions 140 Assertions
94 ~~~~~~~~~~ 141 ~~~~~~~~~~
95 142
96 An assertion is like an expectation, except th !! 143 KUnit also has the concept of an *assertion*. An assertion is just like an
97 terminates the test case if the condition is n !! 144 expectation except the assertion immediately terminates the test case if it is
98 !! 145 not satisfied.
99 .. code-block:: c <<
100 <<
101 static void test_sort(struct kunit *te <<
102 { <<
103 int *a, i, r = 1; <<
104 a = kunit_kmalloc_array(test, <<
105 KUNIT_ASSERT_NOT_ERR_OR_NULL(t <<
106 for (i = 0; i < TEST_LEN; i++) <<
107 r = (r * 725861) % 659 <<
108 a[i] = r; <<
109 } <<
110 sort(a, TEST_LEN, sizeof(*a), <<
111 for (i = 0; i < TEST_LEN-1; i+ <<
112 KUNIT_EXPECT_LE(test, <<
113 } <<
114 <<
115 In this example, we need to be able to allocat <<
116 function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_ <<
117 there's an allocation error. <<
118 <<
119 .. note:: <<
120 In other test frameworks, ``ASSERT`` macros <<
121 ``return`` so they only work from the test <<
122 current kthread on failure, so you can call <<
123 <<
124 .. note:: <<
125 Warning: There is an exception to the above <<
126 in the suite's exit() function, or in the f <<
127 run when a test is shutting down, and an as <<
128 cleanup code from running, potentially lead <<
129 <<
130 Customizing error messages <<
131 -------------------------- <<
132 <<
133 Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSER <<
134 variant. These take a format string and argum <<
135 context to the automatically generated error m <<
136 <<
137 .. code-block:: c <<
138 <<
139 char some_str[41]; <<
140 generate_sha1_hex_string(some_str); <<
141 <<
142 /* Before. Not easy to tell why the te <<
143 KUNIT_EXPECT_EQ(test, strlen(some_str) <<
144 <<
145 /* After. Now we see the offending str <<
146 KUNIT_EXPECT_EQ_MSG(test, strlen(some_ <<
147 146
148 Alternatively, one can take full control over !! 147 For example:
149 ``KUNIT_FAIL()``, e.g. <<
150 148
151 .. code-block:: c 149 .. code-block:: c
152 150
153 /* Before */ !! 151 static void mock_test_do_expect_default_return(struct kunit *test)
154 KUNIT_EXPECT_EQ(test, some_setup_funct !! 152 {
155 !! 153 struct mock_test_context *ctx = test->priv;
156 /* After: full control over the failur !! 154 struct mock *mock = ctx->mock;
157 if (some_setup_function()) !! 155 int param0 = 5, param1 = -5;
158 KUNIT_FAIL(test, "Failed to se !! 156 const char *two_param_types[] = {"int", "int"};
159 !! 157 const void *two_params[] = {¶m0, ¶m1};
>> 158 const void *ret;
>> 159
>> 160 ret = mock->do_expect(mock,
>> 161 "test_printk", test_printk,
>> 162 two_param_types, two_params,
>> 163 ARRAY_SIZE(two_params));
>> 164 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ret);
>> 165 KUNIT_EXPECT_EQ(test, -4, *((int *) ret));
>> 166 }
>> 167
>> 168 In this example, the method under test should return a pointer to a value, so
>> 169 if the pointer returned by the method is null or an errno, we don't want to
>> 170 bother continuing the test since the following expectation could crash the test
>> 171 case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us to bail out of the test case if
>> 172 the appropriate conditions have not been satisfied to complete the test.
160 173
161 Test Suites 174 Test Suites
162 ~~~~~~~~~~~ 175 ~~~~~~~~~~~
163 176
164 We need many test cases covering all the unit' !! 177 Now obviously one unit test isn't very helpful; the power comes from having
165 many similar tests. In order to reduce duplica !! 178 many test cases covering all of a unit's behaviors. Consequently it is common
166 tests, most unit testing frameworks (including !! 179 to have many *similar* tests; in order to reduce duplication in these closely
167 *test suite*. A test suite is a collection of !! 180 related tests most unit testing frameworks - including KUnit - provide the
168 with optional setup and teardown functions tha !! 181 concept of a *test suite*. A *test suite* is just a collection of test cases
169 suite and/or every test case. !! 182 for a unit of code with a set up function that gets invoked before every test
>> 183 case and then a tear down function that gets invoked after every test case
>> 184 completes.
170 185
171 .. note:: !! 186 Example:
172 A test case will only run if it is associat <<
173 <<
174 For example: <<
175 187
176 .. code-block:: c 188 .. code-block:: c
177 189
178 static struct kunit_case example_test_ 190 static struct kunit_case example_test_cases[] = {
179 KUNIT_CASE(example_test_foo), 191 KUNIT_CASE(example_test_foo),
180 KUNIT_CASE(example_test_bar), 192 KUNIT_CASE(example_test_bar),
181 KUNIT_CASE(example_test_baz), 193 KUNIT_CASE(example_test_baz),
182 {} 194 {}
183 }; 195 };
184 196
185 static struct kunit_suite example_test 197 static struct kunit_suite example_test_suite = {
186 .name = "example", 198 .name = "example",
187 .init = example_test_init, 199 .init = example_test_init,
188 .exit = example_test_exit, 200 .exit = example_test_exit,
189 .suite_init = example_suite_in <<
190 .suite_exit = example_suite_ex <<
191 .test_cases = example_test_cas 201 .test_cases = example_test_cases,
192 }; 202 };
193 kunit_test_suite(example_test_suite); 203 kunit_test_suite(example_test_suite);
194 204
195 In the above example, the test suite ``example !! 205 In the above example the test suite, ``example_test_suite``, would run the test
196 ``example_suite_init``, then run the test case !! 206 cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``;
197 ``example_test_bar``, and ``example_test_baz`` !! 207 each would have ``example_test_init`` called immediately before it and would
198 ``example_test_init`` called immediately befor !! 208 have ``example_test_exit`` called immediately after it.
199 called immediately after it. Finally, ``exampl !! 209 ``kunit_test_suite(example_test_suite)`` registers the test suite with the
200 after everything else. ``kunit_test_suite(exam !! 210 KUnit test framework.
201 test suite with the KUnit test framework. <<
202 211
203 .. note:: 212 .. note::
204 The ``exit`` and ``suite_exit`` functions w !! 213 A test case will only be run if it is associated with a test suite.
205 ``suite_init`` fail. Make sure that they ca <<
206 state which may result from ``init`` or ``s <<
207 or exiting early. <<
208 <<
209 ``kunit_test_suite(...)`` is a macro which tel <<
210 specified test suite in a special linker secti <<
211 either after ``late_init``, or when the test m <<
212 built as a module). <<
213 <<
214 For more information, see Documentation/dev-to <<
215 <<
216 .. _kunit-on-non-uml: <<
217 214
218 Writing Tests For Other Architectures !! 215 ``kunit_test_suite(...)`` is a macro which tells the linker to put the specified
219 ------------------------------------- !! 216 test suite in a special linker section so that it can be run by KUnit either
>> 217 after late_init, or when the test module is loaded (depending on whether the
>> 218 test was built in or not).
220 219
221 It is better to write tests that run on UML to !! 220 For more information on these types of things see the
222 particular architecture. It is better to write !! 221 Documentation/dev-tools/kunit/api/test.rst.
223 another easy to obtain (and monetarily free) s <<
224 piece of hardware. <<
225 <<
226 Nevertheless, there are still valid reasons to <<
227 or hardware specific. For example, we might wa <<
228 belongs in ``arch/some-arch/*``. Even so, try <<
229 not depend on physical hardware. Some of our t <<
230 only few tests actually require the hardware t <<
231 available, instead of disabling tests, we can <<
232 <<
233 Now that we have narrowed down exactly what bi <<
234 actual procedure for writing and running the t <<
235 KUnit tests. <<
236 <<
237 .. important:: <<
238 We may have to reset hardware state. If thi <<
239 be able to run one test case per invocation <<
240 <<
241 .. TODO(brendanhiggins@google.com): Add an act <<
242 dependent KUnit test. <<
243 222
244 Common Patterns 223 Common Patterns
245 =============== 224 ===============
246 225
247 Isolating Behavior 226 Isolating Behavior
248 ------------------ 227 ------------------
249 228
250 Unit testing limits the amount of code under t !! 229 The most important aspect of unit testing that other forms of testing do not
251 what code gets run when the unit under test ca !! 230 provide is the ability to limit the amount of code under test to a single unit.
252 is exposed as part of an API such that the def !! 231 In practice, this is only possible by being able to control what code gets run
253 changed without affecting the rest of the code !! 232 when the unit under test calls a function and this is usually accomplished
254 from two constructs: classes, which are struct !! 233 through some sort of indirection where a function is exposed as part of an API
255 provided by the implementer, and architecture- !! 234 such that the definition of that function can be changed without affecting the
256 definitions selected at compile time. !! 235 rest of the code base. In the kernel this primarily comes from two constructs,
>> 236 classes, structs that contain function pointers that are provided by the
>> 237 implementer, and architecture-specific functions which have definitions selected
>> 238 at compile time.
257 239
258 Classes 240 Classes
259 ~~~~~~~ 241 ~~~~~~~
260 242
261 Classes are not a construct that is built into 243 Classes are not a construct that is built into the C programming language;
262 however, it is an easily derived concept. Acco !! 244 however, it is an easily derived concept. Accordingly, pretty much every project
263 project that does not use a standardized objec !! 245 that does not use a standardized object oriented library (like GNOME's GObject)
264 GObject) has their own slightly different way !! 246 has their own slightly different way of doing object oriented programming; the
265 programming; the Linux kernel is no exception. !! 247 Linux kernel is no exception.
266 248
267 The central concept in kernel object oriented 249 The central concept in kernel object oriented programming is the class. In the
268 kernel, a *class* is a struct that contains fu 250 kernel, a *class* is a struct that contains function pointers. This creates a
269 contract between *implementers* and *users* si 251 contract between *implementers* and *users* since it forces them to use the
270 same function signature without having to call !! 252 same function signature without having to call the function directly. In order
271 class, the function pointers must specify that !! 253 for it to truly be a class, the function pointers must specify that a pointer
272 a *class handle*, be one of the parameters. Th !! 254 to the class, known as a *class handle*, be one of the parameters; this makes
273 known as *methods*) have access to member vari !! 255 it possible for the member functions (also known as *methods*) to have access
274 allowing the same implementation to have multi !! 256 to member variables (more commonly known as *fields*) allowing the same
275 !! 257 implementation to have multiple *instances*.
276 A class can be *overridden* by *child classes* !! 258
277 in the child class. Then when the child class !! 259 Typically a class can be *overridden* by *child classes* by embedding the
278 implementation knows that the pointer passed t !! 260 *parent class* in the child class. Then when a method provided by the child
279 within the child. Thus, the child can compute !! 261 class is called, the child implementation knows that the pointer passed to it is
280 pointer to the parent is always a fixed offset !! 262 of a parent contained within the child; because of this, the child can compute
281 This offset is the offset of the parent contai !! 263 the pointer to itself because the pointer to the parent is always a fixed offset
282 example: !! 264 from the pointer to the child; this offset is the offset of the parent contained
>> 265 in the child struct. For example:
283 266
284 .. code-block:: c 267 .. code-block:: c
285 268
286 struct shape { 269 struct shape {
287 int (*area)(struct shape *this 270 int (*area)(struct shape *this);
288 }; 271 };
289 272
290 struct rectangle { 273 struct rectangle {
291 struct shape parent; 274 struct shape parent;
292 int length; 275 int length;
293 int width; 276 int width;
294 }; 277 };
295 278
296 int rectangle_area(struct shape *this) 279 int rectangle_area(struct shape *this)
297 { 280 {
298 struct rectangle *self = conta !! 281 struct rectangle *self = container_of(this, struct shape, parent);
299 282
300 return self->length * self->wi 283 return self->length * self->width;
301 }; 284 };
302 285
303 void rectangle_new(struct rectangle *s 286 void rectangle_new(struct rectangle *self, int length, int width)
304 { 287 {
305 self->parent.area = rectangle_ 288 self->parent.area = rectangle_area;
306 self->length = length; 289 self->length = length;
307 self->width = width; 290 self->width = width;
308 } 291 }
309 292
310 In this example, computing the pointer to the !! 293 In this example (as in most kernel code) the operation of computing the pointer
311 parent is done by ``container_of``. !! 294 to the child from the pointer to the parent is done by ``container_of``.
312 295
313 Faking Classes 296 Faking Classes
314 ~~~~~~~~~~~~~~ 297 ~~~~~~~~~~~~~~
315 298
316 In order to unit test a piece of code that cal 299 In order to unit test a piece of code that calls a method in a class, the
317 behavior of the method must be controllable, o 300 behavior of the method must be controllable, otherwise the test ceases to be a
318 unit test and becomes an integration test. 301 unit test and becomes an integration test.
319 302
320 A fake class implements a piece of code that i !! 303 A fake just provides an implementation of a piece of code that is different than
321 production instance, but behaves identical fro !! 304 what runs in a production instance, but behaves identically from the standpoint
322 This is done to replace a dependency that is h !! 305 of the callers; this is usually done to replace a dependency that is hard to
323 example, implementing a fake EEPROM that store !! 306 deal with, or is slow.
324 internal buffer. Assume we have a class that r !! 307
>> 308 A good example for this might be implementing a fake EEPROM that just stores the
>> 309 "contents" in an internal buffer. For example, let's assume we have a class that
>> 310 represents an EEPROM:
325 311
326 .. code-block:: c 312 .. code-block:: c
327 313
328 struct eeprom { 314 struct eeprom {
329 ssize_t (*read)(struct eeprom 315 ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
330 ssize_t (*write)(struct eeprom 316 ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
331 }; 317 };
332 318
333 And we want to test code that buffers writes t !! 319 And we want to test some code that buffers writes to the EEPROM:
334 320
335 .. code-block:: c 321 .. code-block:: c
336 322
337 struct eeprom_buffer { 323 struct eeprom_buffer {
338 ssize_t (*write)(struct eeprom 324 ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
339 int flush(struct eeprom_buffer 325 int flush(struct eeprom_buffer *this);
340 size_t flush_count; /* Flushes 326 size_t flush_count; /* Flushes when buffer exceeds flush_count. */
341 }; 327 };
342 328
343 struct eeprom_buffer *new_eeprom_buffe 329 struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
344 void destroy_eeprom_buffer(struct eepr 330 void destroy_eeprom_buffer(struct eeprom *eeprom);
345 331
346 We can test this code by *faking out* the unde !! 332 We can easily test this code by *faking out* the underlying EEPROM:
347 333
348 .. code-block:: c 334 .. code-block:: c
349 335
350 struct fake_eeprom { 336 struct fake_eeprom {
351 struct eeprom parent; 337 struct eeprom parent;
352 char contents[FAKE_EEPROM_CONT 338 char contents[FAKE_EEPROM_CONTENTS_SIZE];
353 }; 339 };
354 340
355 ssize_t fake_eeprom_read(struct eeprom 341 ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
356 { 342 {
357 struct fake_eeprom *this = con 343 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
358 344
359 count = min(count, FAKE_EEPROM 345 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
360 memcpy(buffer, this->contents 346 memcpy(buffer, this->contents + offset, count);
361 347
362 return count; 348 return count;
363 } 349 }
364 350
365 ssize_t fake_eeprom_write(struct eepro 351 ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
366 { 352 {
367 struct fake_eeprom *this = con 353 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
368 354
369 count = min(count, FAKE_EEPROM 355 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
370 memcpy(this->contents + offset 356 memcpy(this->contents + offset, buffer, count);
371 357
372 return count; 358 return count;
373 } 359 }
374 360
375 void fake_eeprom_init(struct fake_eepr 361 void fake_eeprom_init(struct fake_eeprom *this)
376 { 362 {
377 this->parent.read = fake_eepro 363 this->parent.read = fake_eeprom_read;
378 this->parent.write = fake_eepr 364 this->parent.write = fake_eeprom_write;
379 memset(this->contents, 0, FAKE 365 memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
380 } 366 }
381 367
382 We can now use it to test ``struct eeprom_buff 368 We can now use it to test ``struct eeprom_buffer``:
383 369
384 .. code-block:: c 370 .. code-block:: c
385 371
386 struct eeprom_buffer_test { 372 struct eeprom_buffer_test {
387 struct fake_eeprom *fake_eepro 373 struct fake_eeprom *fake_eeprom;
388 struct eeprom_buffer *eeprom_b 374 struct eeprom_buffer *eeprom_buffer;
389 }; 375 };
390 376
391 static void eeprom_buffer_test_does_no 377 static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
392 { 378 {
393 struct eeprom_buffer_test *ctx 379 struct eeprom_buffer_test *ctx = test->priv;
394 struct eeprom_buffer *eeprom_b 380 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
395 struct fake_eeprom *fake_eepro 381 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
396 char buffer[] = {0xff}; 382 char buffer[] = {0xff};
397 383
398 eeprom_buffer->flush_count = S 384 eeprom_buffer->flush_count = SIZE_MAX;
399 385
400 eeprom_buffer->write(eeprom_bu 386 eeprom_buffer->write(eeprom_buffer, buffer, 1);
401 KUNIT_EXPECT_EQ(test, fake_eep 387 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
402 388
403 eeprom_buffer->write(eeprom_bu 389 eeprom_buffer->write(eeprom_buffer, buffer, 1);
404 KUNIT_EXPECT_EQ(test, fake_eep 390 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
405 391
406 eeprom_buffer->flush(eeprom_bu 392 eeprom_buffer->flush(eeprom_buffer);
407 KUNIT_EXPECT_EQ(test, fake_eep 393 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
408 KUNIT_EXPECT_EQ(test, fake_eep 394 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
409 } 395 }
410 396
411 static void eeprom_buffer_test_flushes 397 static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
412 { 398 {
413 struct eeprom_buffer_test *ctx 399 struct eeprom_buffer_test *ctx = test->priv;
414 struct eeprom_buffer *eeprom_b 400 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
415 struct fake_eeprom *fake_eepro 401 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
416 char buffer[] = {0xff}; 402 char buffer[] = {0xff};
417 403
418 eeprom_buffer->flush_count = 2 404 eeprom_buffer->flush_count = 2;
419 405
420 eeprom_buffer->write(eeprom_bu 406 eeprom_buffer->write(eeprom_buffer, buffer, 1);
421 KUNIT_EXPECT_EQ(test, fake_eep 407 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
422 408
423 eeprom_buffer->write(eeprom_bu 409 eeprom_buffer->write(eeprom_buffer, buffer, 1);
424 KUNIT_EXPECT_EQ(test, fake_eep 410 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
425 KUNIT_EXPECT_EQ(test, fake_eep 411 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
426 } 412 }
427 413
428 static void eeprom_buffer_test_flushes 414 static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
429 { 415 {
430 struct eeprom_buffer_test *ctx 416 struct eeprom_buffer_test *ctx = test->priv;
431 struct eeprom_buffer *eeprom_b 417 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
432 struct fake_eeprom *fake_eepro 418 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
433 char buffer[] = {0xff, 0xff}; 419 char buffer[] = {0xff, 0xff};
434 420
435 eeprom_buffer->flush_count = 2 421 eeprom_buffer->flush_count = 2;
436 422
437 eeprom_buffer->write(eeprom_bu 423 eeprom_buffer->write(eeprom_buffer, buffer, 1);
438 KUNIT_EXPECT_EQ(test, fake_eep 424 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
439 425
440 eeprom_buffer->write(eeprom_bu 426 eeprom_buffer->write(eeprom_buffer, buffer, 2);
441 KUNIT_EXPECT_EQ(test, fake_eep 427 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
442 KUNIT_EXPECT_EQ(test, fake_eep 428 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
443 /* Should have only flushed th 429 /* Should have only flushed the first two bytes. */
444 KUNIT_EXPECT_EQ(test, fake_eep 430 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
445 } 431 }
446 432
447 static int eeprom_buffer_test_init(str 433 static int eeprom_buffer_test_init(struct kunit *test)
448 { 434 {
449 struct eeprom_buffer_test *ctx 435 struct eeprom_buffer_test *ctx;
450 436
451 ctx = kunit_kzalloc(test, size 437 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
452 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 438 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
453 439
454 ctx->fake_eeprom = kunit_kzall 440 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
455 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 441 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
456 fake_eeprom_init(ctx->fake_eep 442 fake_eeprom_init(ctx->fake_eeprom);
457 443
458 ctx->eeprom_buffer = new_eepro 444 ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
459 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 445 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
460 446
461 test->priv = ctx; 447 test->priv = ctx;
462 448
463 return 0; 449 return 0;
464 } 450 }
465 451
466 static void eeprom_buffer_test_exit(st 452 static void eeprom_buffer_test_exit(struct kunit *test)
467 { 453 {
468 struct eeprom_buffer_test *ctx 454 struct eeprom_buffer_test *ctx = test->priv;
469 455
470 destroy_eeprom_buffer(ctx->eep 456 destroy_eeprom_buffer(ctx->eeprom_buffer);
471 } 457 }
472 458
473 Testing Against Multiple Inputs !! 459 Testing against multiple inputs
474 ------------------------------- 460 -------------------------------
475 461
476 Testing just a few inputs is not enough to ens !! 462 Testing just a few inputs might not be enough to have confidence that the code
477 for example: testing a hash function. !! 463 works correctly, e.g. for a hash function.
478 464
479 We can write a helper macro or function. The f !! 465 In such cases, it can be helpful to have a helper macro or function, e.g. this
480 For example, to test ``sha1sum(1)``, we can wr !! 466 fictitious example for ``sha1sum(1)``
481 467
482 .. code-block:: c 468 .. code-block:: c
483 469
484 #define TEST_SHA1(in, want) \ 470 #define TEST_SHA1(in, want) \
485 sha1sum(in, out); \ 471 sha1sum(in, out); \
486 KUNIT_EXPECT_STREQ_MSG(test, o 472 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
487 473
488 char out[40]; 474 char out[40];
489 TEST_SHA1("hello world", "2aae6c35c94 475 TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
490 TEST_SHA1("hello world!", "430ce34d020 476 TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");
491 477
492 Note the use of the ``_MSG`` version of ``KUNI <<
493 detailed error and make the assertions clearer <<
494 478
495 The ``_MSG`` variants are useful when the same !! 479 Note the use of ``KUNIT_EXPECT_STREQ_MSG`` to give more context when it fails
496 times (in a loop or helper function) and thus !! 480 and make it easier to track down. (Yes, in this example, ``want`` is likely
497 identify what failed, as shown below. !! 481 going to be unique enough on its own).
>> 482
>> 483 The ``_MSG`` variants are even more useful when the same expectation is called
>> 484 multiple times (in a loop or helper function) and thus the line number isn't
>> 485 enough to identify what failed, like below.
498 486
499 In complicated cases, we recommend using a *ta !! 487 In some cases, it can be helpful to write a *table-driven test* instead, e.g.
500 helper macro variation, for example: <<
501 488
502 .. code-block:: c 489 .. code-block:: c
503 490
504 int i; 491 int i;
505 char out[40]; 492 char out[40];
506 493
507 struct sha1_test_case { 494 struct sha1_test_case {
508 const char *str; 495 const char *str;
509 const char *sha1; 496 const char *sha1;
510 }; 497 };
511 498
512 struct sha1_test_case cases[] = { 499 struct sha1_test_case cases[] = {
513 { 500 {
514 .str = "hello world", 501 .str = "hello world",
515 .sha1 = "2aae6c35c94fc 502 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
516 }, 503 },
517 { 504 {
518 .str = "hello world!", 505 .str = "hello world!",
519 .sha1 = "430ce34d02072 506 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
520 }, 507 },
521 }; 508 };
522 for (i = 0; i < ARRAY_SIZE(cases); ++i 509 for (i = 0; i < ARRAY_SIZE(cases); ++i) {
523 sha1sum(cases[i].str, out); 510 sha1sum(cases[i].str, out);
524 KUNIT_EXPECT_STREQ_MSG(test, o 511 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
525 "sha1sum 512 "sha1sum(%s)", cases[i].str);
526 } 513 }
527 514
528 515
529 There is more boilerplate code involved, but i !! 516 There's more boilerplate involved, but it can:
530 <<
531 * be more readable when there are multiple inp <<
532 517
533 * For example, see ``fs/ext4/inode-test.c``. !! 518 * be more readable when there are multiple inputs/outputs thanks to field names,
534 519
535 * reduce duplication if test cases are shared !! 520 * E.g. see ``fs/ext4/inode-test.c`` for an example of both.
>> 521 * reduce duplication if test cases can be shared across multiple tests.
536 522
537 * For example: if we want to test ``sha256su !! 523 * E.g. if we wanted to also test ``sha256sum``, we could add a ``sha256``
538 field and reuse ``cases``. 524 field and reuse ``cases``.
539 525
540 * be converted to a "parameterized test". !! 526 * be converted to a "parameterized test", see below.
541 527
542 Parameterized Testing 528 Parameterized Testing
543 ~~~~~~~~~~~~~~~~~~~~~ 529 ~~~~~~~~~~~~~~~~~~~~~
544 530
545 The table-driven testing pattern is common eno 531 The table-driven testing pattern is common enough that KUnit has special
546 support for it. 532 support for it.
547 533
548 By reusing the same ``cases`` array from above !! 534 Reusing the same ``cases`` array from above, we can write the test as a
549 "parameterized test" with the following. 535 "parameterized test" with the following.
550 536
551 .. code-block:: c 537 .. code-block:: c
552 538
553 // This is copy-pasted from above. 539 // This is copy-pasted from above.
554 struct sha1_test_case { 540 struct sha1_test_case {
555 const char *str; 541 const char *str;
556 const char *sha1; 542 const char *sha1;
557 }; 543 };
558 const struct sha1_test_case cases[] = !! 544 struct sha1_test_case cases[] = {
559 { 545 {
560 .str = "hello world", 546 .str = "hello world",
561 .sha1 = "2aae6c35c94fc 547 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
562 }, 548 },
563 { 549 {
564 .str = "hello world!", 550 .str = "hello world!",
565 .sha1 = "430ce34d02072 551 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
566 }, 552 },
567 }; 553 };
568 554
569 // Creates `sha1_gen_params()` to iter !! 555 // Need a helper function to generate a name for each test case.
570 // the struct member `str` for the cas !! 556 static void case_to_desc(const struct sha1_test_case *t, char *desc)
571 KUNIT_ARRAY_PARAM_DESC(sha1, cases, st !! 557 {
>> 558 strcpy(desc, t->str);
>> 559 }
>> 560 // Creates `sha1_gen_params()` to iterate over `cases`.
>> 561 KUNIT_ARRAY_PARAM(sha1, cases, case_to_desc);
572 562
573 // Looks no different from a normal te 563 // Looks no different from a normal test.
574 static void sha1_test(struct kunit *te 564 static void sha1_test(struct kunit *test)
575 { 565 {
576 // This function can just cont 566 // This function can just contain the body of the for-loop.
577 // The former `cases[i]` is ac 567 // The former `cases[i]` is accessible under test->param_value.
578 char out[40]; 568 char out[40];
579 struct sha1_test_case *test_pa 569 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
580 570
581 sha1sum(test_param->str, out); 571 sha1sum(test_param->str, out);
582 KUNIT_EXPECT_STREQ_MSG(test, o 572 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
583 "sha1sum 573 "sha1sum(%s)", test_param->str);
584 } 574 }
585 575
586 // Instead of KUNIT_CASE, we use KUNIT 576 // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
587 // function declared by KUNIT_ARRAY_PA !! 577 // function declared by KUNIT_ARRAY_PARAM.
588 static struct kunit_case sha1_test_cas 578 static struct kunit_case sha1_test_cases[] = {
589 KUNIT_CASE_PARAM(sha1_test, sh 579 KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
590 {} 580 {}
591 }; 581 };
592 582
593 Allocating Memory !! 583 .. _kunit-on-non-uml:
594 ----------------- <<
595 <<
596 Where you might use ``kzalloc``, you can inste <<
597 will then ensure that the memory is freed once <<
598 <<
599 This is useful because it lets us use the ``KU <<
600 early from a test without having to worry abou <<
601 For example: <<
602 <<
603 .. code-block:: c <<
604 <<
605 void example_test_allocation(struct ku <<
606 { <<
607 char *buffer = kunit_kzalloc(t <<
608 /* Ensure allocation succeeded <<
609 KUNIT_ASSERT_NOT_ERR_OR_NULL(t <<
610 <<
611 KUNIT_ASSERT_STREQ(test, buffe <<
612 } <<
613 <<
614 Registering Cleanup Actions <<
615 --------------------------- <<
616 <<
617 If you need to perform some cleanup beyond sim <<
618 you can register a custom "deferred action", w <<
619 run when the test exits (whether cleanly, or v <<
620 <<
621 Actions are simple functions with no return va <<
622 context argument, and fulfill the same role as <<
623 and Go tests, "defer" statements in languages <<
624 (in some cases) destructors in RAII languages. <<
625 <<
626 These are very useful for unregistering things <<
627 files or other resources, or freeing resources <<
628 <<
629 For example: <<
630 <<
631 .. code-block:: C <<
632 <<
633 static void cleanup_device(void *ctx) <<
634 { <<
635 struct device *dev = (struct d <<
636 <<
637 device_unregister(dev); <<
638 } <<
639 <<
640 void example_device_test(struct kunit <<
641 { <<
642 struct my_device dev; <<
643 <<
644 device_register(&dev); <<
645 <<
646 kunit_add_action(test, &cleanu <<
647 } <<
648 <<
649 Note that, for functions like device_unregiste <<
650 pointer-sized argument, it's possible to autom <<
651 with the ``KUNIT_DEFINE_ACTION_WRAPPER()`` mac <<
652 <<
653 .. code-block:: C <<
654 <<
655 KUNIT_DEFINE_ACTION_WRAPPER(device_unr <<
656 kunit_add_action(test, &device_unregis <<
657 <<
658 You should do this in preference to manually c <<
659 as casting function pointers will break Contro <<
660 <<
661 ``kunit_add_action`` can fail if, for example, <<
662 You can use ``kunit_add_action_or_reset`` inst <<
663 immediately if it cannot be deferred. <<
664 <<
665 If you need more control over when the cleanup <<
666 can trigger it early using ``kunit_release_act <<
667 with ``kunit_remove_action``. <<
668 <<
669 <<
670 Testing Static Functions <<
671 ------------------------ <<
672 <<
673 If we do not want to expose functions or varia <<
674 conditionally export the used symbol. For exam <<
675 <<
676 .. code-block:: c <<
677 <<
678 /* In my_file.c */ <<
679 <<
680 VISIBLE_IF_KUNIT int do_interesting_th <<
681 EXPORT_SYMBOL_IF_KUNIT(do_interesting_ <<
682 584
683 /* In my_file.h */ !! 585 KUnit on non-UML architectures
>> 586 ==============================
684 587
685 #if IS_ENABLED(CONFIG_KUNIT) !! 588 By default KUnit uses UML as a way to provide dependencies for code under test.
686 int do_interesting_thing(void) !! 589 Under most circumstances KUnit's usage of UML should be treated as an
687 #endif !! 590 implementation detail of how KUnit works under the hood. Nevertheless, there
>> 591 are instances where being able to run architecture-specific code or test
>> 592 against real hardware is desirable. For these reasons KUnit supports running on
>> 593 other architectures.
688 594
689 Alternatively, you could conditionally ``#incl !! 595 Running existing KUnit tests on non-UML architectures
690 your .c file. For example: !! 596 -----------------------------------------------------
691 597
692 .. code-block:: c !! 598 There are some special considerations when running existing KUnit tests on
>> 599 non-UML architectures:
693 600
694 /* In my_file.c */ !! 601 * Hardware may not be deterministic, so a test that always passes or fails
>> 602 when run under UML may not always do so on real hardware.
>> 603 * Hardware and VM environments may not be hermetic. KUnit tries its best to
>> 604 provide a hermetic environment to run tests; however, it cannot manage state
>> 605 that it doesn't know about outside of the kernel. Consequently, tests that
>> 606 may be hermetic on UML may not be hermetic on other architectures.
>> 607 * Some features and tooling may not be supported outside of UML.
>> 608 * Hardware and VMs are slower than UML.
695 609
696 static int do_interesting_thing(); !! 610 None of these are reasons not to run your KUnit tests on real hardware; they are
>> 611 only things to be aware of when doing so.
697 612
698 #ifdef CONFIG_MY_KUNIT_TEST !! 613 Currently, the KUnit Wrapper (``tools/testing/kunit/kunit.py``) (aka
699 #include "my_kunit_test.c" !! 614 kunit_tool) only fully supports running tests inside of UML and QEMU; however,
700 #endif !! 615 this is only due to our own time limitations as humans working on KUnit. It is
>> 616 entirely possible to support other emulators and even actual hardware, but for
>> 617 now QEMU and UML is what is fully supported within the KUnit Wrapper. Again, to
>> 618 be clear, this is just the Wrapper. The actualy KUnit tests and the KUnit
>> 619 library they are written in is fully architecture agnostic and can be used in
>> 620 virtually any setup, you just won't have the benefit of typing a single command
>> 621 out of the box and having everything magically work perfectly.
701 622
702 Injecting Test-Only Code !! 623 Again, all core KUnit framework features are fully supported on all
703 ------------------------ !! 624 architectures, and using them is straightforward: Most popular architectures
>> 625 are supported directly in the KUnit Wrapper via QEMU. Currently, supported
>> 626 architectures on QEMU include:
704 627
705 Similar to as shown above, we can add test-spe !! 628 * i386
>> 629 * x86_64
>> 630 * arm
>> 631 * arm64
>> 632 * alpha
>> 633 * powerpc
>> 634 * riscv
>> 635 * s390
>> 636 * sparc
706 637
707 .. code-block:: c !! 638 In order to run KUnit tests on one of these architectures via QEMU with the
>> 639 KUnit wrapper, all you need to do is specify the flags ``--arch`` and
>> 640 ``--cross_compile`` when invoking the KUnit Wrapper. For example, we could run
>> 641 the default KUnit tests on ARM in the following manner (assuming we have an ARM
>> 642 toolchain installed):
708 643
709 /* In my_file.h */ !! 644 .. code-block:: bash
710 645
711 #ifdef CONFIG_MY_KUNIT_TEST !! 646 tools/testing/kunit/kunit.py run --timeout=60 --jobs=12 --arch=arm --cross_compile=arm-linux-gnueabihf-
712 /* Defined in my_kunit_test.c */ <<
713 void test_only_hook(void); <<
714 #else <<
715 void test_only_hook(void) { } <<
716 #endif <<
717 647
718 This test-only code can be made more useful by !! 648 Alternatively, if you want to run your tests on real hardware or in some other
719 as shown in next section: *Accessing The Curre !! 649 emulation environment, all you need to do is to take your kunitconfig, your
>> 650 Kconfig options for the tests you would like to run, and merge them into
>> 651 whatever config your are using for your platform. That's it!
720 652
721 Accessing The Current Test !! 653 For example, let's say you have the following kunitconfig:
722 -------------------------- <<
723 654
724 In some cases, we need to call test-only code !! 655 .. code-block:: none
725 is helpful, for example, when providing a fake <<
726 to fail any current test from within an error <<
727 We can do this via the ``kunit_test`` field in <<
728 access using the ``kunit_get_current_test()`` <<
729 656
730 ``kunit_get_current_test()`` is safe to call e !! 657 CONFIG_KUNIT=y
731 KUnit is not enabled, or if no test is running !! 658 CONFIG_KUNIT_EXAMPLE_TEST=y
732 return ``NULL``. This compiles down to either <<
733 so will have a negligible performance impact w <<
734 659
735 The example below uses this to implement a "mo !! 660 If you wanted to run this test on an x86 VM, you might add the following config
>> 661 options to your ``.config``:
736 662
737 .. code-block:: c !! 663 .. code-block:: none
738 664
739 #include <kunit/test-bug.h> /* for kun !! 665 CONFIG_KUNIT=y
>> 666 CONFIG_KUNIT_EXAMPLE_TEST=y
>> 667 CONFIG_SERIAL_8250=y
>> 668 CONFIG_SERIAL_8250_CONSOLE=y
740 669
741 struct test_data { !! 670 All these new options do is enable support for a common serial console needed
742 int foo_result; !! 671 for logging.
743 int want_foo_called_with; <<
744 }; <<
745 672
746 static int fake_foo(int arg) !! 673 Next, you could build a kernel with these tests as follows:
747 { <<
748 struct kunit *test = kunit_get <<
749 struct test_data *test_data = <<
750 674
751 KUNIT_EXPECT_EQ(test, test_dat <<
752 return test_data->foo_result; <<
753 } <<
754 675
755 static void example_simple_test(struct !! 676 .. code-block:: bash
756 { <<
757 /* Assume priv (private, a mem <<
758 * the init function) is alloc <<
759 struct test_data *test_data = <<
760 <<
761 test_data->foo_result = 42; <<
762 test_data->want_foo_called_wit <<
763 677
764 /* In a real test, we'd probab !! 678 make ARCH=x86 olddefconfig
765 * like an ops struct, etc. in !! 679 make ARCH=x86
766 KUNIT_EXPECT_EQ(test, fake_foo <<
767 } <<
768 680
769 In this example, we are using the ``priv`` mem !! 681 Once you have built a kernel, you could run it on QEMU as follows:
770 of passing data to the test from the init func <<
771 pointer that can be used for any user data. Th <<
772 variables, as it avoids concurrency issues. <<
773 682
774 Had we wanted something more flexible, we coul !! 683 .. code-block:: bash
775 Each test can have multiple resources which ha <<
776 flexibility as a ``priv`` member, but also, fo <<
777 functions to create resources without conflict <<
778 possible to define a clean up function for eac <<
779 avoid resource leaks. For more information, se <<
780 684
781 Failing The Current Test !! 685 qemu-system-x86_64 -enable-kvm \
782 ------------------------ !! 686 -m 1024 \
>> 687 -kernel arch/x86_64/boot/bzImage \
>> 688 -append 'console=ttyS0' \
>> 689 --nographic
783 690
784 If we want to fail the current test, we can us !! 691 Interspersed in the kernel logs you might see the following:
785 which is defined in ``<kunit/test-bug.h>`` and <<
786 For example, we have an option to enable some <<
787 structures as shown below: <<
788 692
789 .. code-block:: c !! 693 .. code-block:: none
790 694
791 #include <kunit/test-bug.h> !! 695 TAP version 14
>> 696 # Subtest: example
>> 697 1..1
>> 698 # example_simple_test: initializing
>> 699 ok 1 - example_simple_test
>> 700 ok 1 - example
792 701
793 #ifdef CONFIG_EXTRA_DEBUG_CHECKS !! 702 Congratulations, you just ran a KUnit test on the x86 architecture!
794 static void validate_my_data(struct da <<
795 { <<
796 if (is_valid(data)) <<
797 return; <<
798 703
799 kunit_fail_current_test("data !! 704 In a similar manner, kunit and kunit tests can also be built as modules,
>> 705 so if you wanted to run tests in this way you might add the following config
>> 706 options to your ``.config``:
800 707
801 /* Normal, non-KUnit, error re !! 708 .. code-block:: none
802 } <<
803 #else <<
804 static void my_debug_function(void) { <<
805 #endif <<
806 709
807 ``kunit_fail_current_test()`` is safe to call !! 710 CONFIG_KUNIT=m
808 KUnit is not enabled, or if no test is running !! 711 CONFIG_KUNIT_EXAMPLE_TEST=m
809 nothing. This compiles down to either a no-op <<
810 have a negligible performance impact when no t <<
811 712
812 Managing Fake Devices and Drivers !! 713 Once the kernel is built and installed, a simple
813 --------------------------------- <<
814 714
815 When testing drivers or code which interacts w !! 715 .. code-block:: bash
816 require a ``struct device`` or ``struct device <<
817 up a real device is not required to test any g <<
818 can be used instead. <<
819 716
820 KUnit provides helper functions to create and !! 717 modprobe example-test
821 are internally of type ``struct kunit_device`` <<
822 ``kunit_bus``. These devices support managed d <<
823 described in Documentation/driver-api/driver-m <<
824 718
825 To create a KUnit-managed ``struct device_driv !! 719 ...will run the tests.
826 which will create a driver with the given name <<
827 will automatically be destroyed when the corre <<
828 be manually destroyed with ``driver_unregister <<
829 720
830 To create a fake device, use the ``kunit_devic !! 721 .. note::
831 and register a device, using a new KUnit-manag !! 722 Note that you should make sure your test depends on ``KUNIT=y`` in Kconfig
832 To provide a specific, non-KUnit-managed drive !! 723 if the test does not support module build. Otherwise, it will trigger
833 instead. Like with managed drivers, KUnit-mana !! 724 compile errors if ``CONFIG_KUNIT`` is ``m``.
834 cleaned up when the test finishes, but can be !! 725
835 ``kunit_device_unregister()``. !! 726 Writing new tests for other architectures
836 !! 727 -----------------------------------------
837 The KUnit devices should be used in preference !! 728
838 instead of ``platform_device_register()`` in c !! 729 The first thing you must do is ask yourself whether it is necessary to write a
839 a platform device. !! 730 KUnit test for a specific architecture, and then whether it is necessary to
840 !! 731 write that test for a particular piece of hardware. In general, writing a test
841 For example: !! 732 that depends on having access to a particular piece of hardware or software (not
842 !! 733 included in the Linux source repo) should be avoided at all costs.
843 .. code-block:: c !! 734
844 !! 735 Even if you only ever plan on running your KUnit test on your hardware
845 #include <kunit/device.h> !! 736 configuration, other people may want to run your tests and may not have access
846 !! 737 to your hardware. If you write your test to run on UML, then anyone can run your
847 static void test_my_device(struct kuni !! 738 tests without knowing anything about your particular setup, and you can still
848 { !! 739 run your tests on your hardware setup just by compiling for your architecture.
849 struct device *fake_device; <<
850 const char *dev_managed_string <<
851 740
852 // Create a fake device. !! 741 .. important::
853 fake_device = kunit_device_reg !! 742 Always prefer tests that run on UML to tests that only run under a particular
854 KUNIT_ASSERT_NOT_ERR_OR_NULL(t !! 743 architecture, and always prefer tests that run under QEMU or another easy
>> 744 (and monetarily free) to obtain software environment to a specific piece of
>> 745 hardware.
>> 746
>> 747 Nevertheless, there are still valid reasons to write an architecture or hardware
>> 748 specific test: for example, you might want to test some code that really belongs
>> 749 in ``arch/some-arch/*``. Even so, try your best to write the test so that it
>> 750 does not depend on physical hardware: if some of your test cases don't need the
>> 751 hardware, only require the hardware for tests that actually need it.
>> 752
>> 753 Now that you have narrowed down exactly what bits are hardware specific, the
>> 754 actual procedure for writing and running the tests is pretty much the same as
>> 755 writing normal KUnit tests. One special caveat is that you have to reset
>> 756 hardware state in between test cases; if this is not possible, you may only be
>> 757 able to run one test case per invocation.
855 758
856 // Pass it to functions which !! 759 .. TODO(brendanhiggins@google.com): Add an actual example of an architecture-
857 dev_managed_string = devm_kstr !! 760 dependent KUnit test.
858 761
859 // Everything is cleaned up au !! 762 KUnit debugfs representation
860 } !! 763 ============================
>> 764 When kunit test suites are initialized, they create an associated directory
>> 765 in ``/sys/kernel/debug/kunit/<test-suite>``. The directory contains one file
>> 766
>> 767 - results: "cat results" displays results of each test case and the results
>> 768 of the entire suite for the last test run.
>> 769
>> 770 The debugfs representation is primarily of use when kunit test suites are
>> 771 run in a native environment, either as modules or builtin. Having a way
>> 772 to display results like this is valuable as otherwise results can be
>> 773 intermixed with other events in dmesg output. The maximum size of each
>> 774 results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.