projects/linux·blob master · refs

1258 lines · 43.0 KiB

1.. SPDX-License-Identifier: GPL-2.0
2
3Writing Tests
4=============
5
6Test Cases
7----------
8
9The fundamental unit in KUnit is the test case. A test case is a function with
10the signature ``void (*)(struct kunit *test)``. It calls the function under test
11and then sets *expectations* for what should happen. For example:
12
13.. code-block:: c
14
15 void example_test_success(struct kunit *test)
16 {
17 }
18
19 void example_test_failure(struct kunit *test)
20 {
21 KUNIT_FAIL(test, "This test never passes.");
22 }
23
24In the above example, ``example_test_success`` always passes because it does
25nothing; no expectations are set, and therefore all expectations pass. On the
26other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``,
27which is a special expectation that logs a message and causes the test case to
28fail.
29
30Expectations
31~~~~~~~~~~~~
32An *expectation* specifies that we expect a piece of code to do something in a
33test. An expectation is called like a function. A test is made by setting
34expectations about the behavior of a piece of code under test. When one or more
35expectations fail, the test case fails and information about the failure is
36logged. For example:
37
38.. code-block:: c
39
40 void add_test_basic(struct kunit *test)
41 {
42 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
43 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
44 }
45
46In the above example, ``add_test_basic`` makes a number of assertions about the
47behavior of a function called ``add``. The first parameter is always of type
48``struct kunit *``, which contains information about the current test context.
49The second parameter, in this case, is what the value is expected to be. The
50last value is what the value actually is. If ``add`` passes all of these
51expectations, the test case, ``add_test_basic`` will pass; if any one of these
52expectations fails, the test case will fail.
53
54A test case *fails* when any expectation is violated; however, the test will
55continue to run, and try other expectations until the test case ends or is
56otherwise terminated. This is as opposed to *assertions* which are discussed
57later.
58
59To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.
60
61.. note::
62 A single test case should be short, easy to understand, and focused on a
63 single behavior.
64
65For example, if we want to rigorously test the ``add`` function above, create
66additional tests cases which would test each property that an ``add`` function
67should have as shown below:
68
69.. code-block:: c
70
71 void add_test_basic(struct kunit *test)
72 {
73 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
74 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
75 }
76
77 void add_test_negative(struct kunit *test)
78 {
79 KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
80 }
81
82 void add_test_max(struct kunit *test)
83 {
84 KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
85 KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
86 }
87
88 void add_test_overflow(struct kunit *test)
89 {
90 KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
91 }
92
93Assertions
94~~~~~~~~~~
95
96An assertion is like an expectation, except that the assertion immediately
97terminates the test case if the condition is not satisfied. For example:
98
99.. code-block:: c
100
101 static void test_sort(struct kunit *test)
102 {
103 int *a, i, r = 1;
104 a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL);
105 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a);
106 for (i = 0; i < TEST_LEN; i++) {
107 r = (r * 725861) % 6599;
108 a[i] = r;
109 }
110 sort(a, TEST_LEN, sizeof(*a), cmpint, NULL);
111 for (i = 0; i < TEST_LEN-1; i++)
112 KUNIT_EXPECT_LE(test, a[i], a[i + 1]);
113 }
114
115In this example, we need to be able to allocate an array to test the ``sort()``
116function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if
117there's an allocation error.
118
119.. note::
120 In other test frameworks, ``ASSERT`` macros are often implemented by calling
121 ``return`` so they only work from the test function. In KUnit, we stop the
122 current kthread on failure, so you can call them from anywhere.
123
124.. note::
125 Warning: There is an exception to the above rule. You shouldn't use assertions
126 in the suite's exit() function, or in the free function for a resource. These
127 run when a test is shutting down, and an assertion here prevents further
128 cleanup code from running, potentially leading to a memory leak.
129
130Customizing error messages
131--------------------------
132
133Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG``
134variant. These take a format string and arguments to provide additional
135context to the automatically generated error messages.
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 test failed. */
143 KUNIT_EXPECT_EQ(test, strlen(some_str), 40);
144
145 /* After. Now we see the offending string. */
146 KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str);
147
148Alternatively, one can take full control over the error message by using
149``KUNIT_FAIL()``, e.g.
150
151.. code-block:: c
152
153 /* Before */
154 KUNIT_EXPECT_EQ(test, some_setup_function(), 0);
155
156 /* After: full control over the failure message. */
157 if (some_setup_function())
158 KUNIT_FAIL(test, "Failed to setup thing for testing");
159
160Suppressing warning backtraces
161------------------------------
162
163Some unit tests trigger warning backtraces either intentionally or as a side
164effect. Such backtraces are normally undesirable since they distract from
165the actual test and may result in the impression that there is a problem.
166
167Backtraces can be suppressed with **task-scoped suppression**: while
168suppression is active on the current task, the backtrace and stack dump from
169``WARN*()``, ``WARN_ON*()``, and related macros on that task are suppressed.
170Two API forms are available.
171
172- Scoped suppression is the simplest form. Wrap the code that triggers
173 warnings in a ``kunit_warning_suppress()`` block:
174
175.. code-block:: c
176
177 static void some_test(struct kunit *test)
178 {
179 kunit_warning_suppress(test) {
180 trigger_backtrace();
181 KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(test, 1);
182 }
183 }
184
185.. note::
186 The warning count must be checked inside the block; the suppression handle
187 is not accessible after the block exits.
188
189- Direct functions return an explicit handle pointer. Use them when the handle
190 needs to be retained or passed across helper functions:
191
192.. code-block:: c
193
194 static void some_test(struct kunit *test)
195 {
196 struct kunit_suppressed_warning *w;
197
198 w = kunit_start_suppress_warning(test);
199 trigger_backtrace();
200 kunit_end_suppress_warning(test, w);
201
202 KUNIT_EXPECT_EQ(test, kunit_suppressed_warning_count(w), 1);
203 }
204
205Test Suites
206~~~~~~~~~~~
207
208We need many test cases covering all the unit's behaviors. It is common to have
209many similar tests. In order to reduce duplication in these closely related
210tests, most unit testing frameworks (including KUnit) provide the concept of a
211*test suite*. A test suite is a collection of test cases for a unit of code
212with optional setup and teardown functions that run before/after the whole
213suite and/or every test case.
214
215.. note::
216 A test case will only run if it is associated with a test suite.
217
218For example:
219
220.. code-block:: c
221
222 static struct kunit_case example_test_cases[] = {
223 KUNIT_CASE(example_test_foo),
224 KUNIT_CASE(example_test_bar),
225 KUNIT_CASE(example_test_baz),
226 {}
227 };
228
229 static struct kunit_suite example_test_suite = {
230 .name = "example",
231 .init = example_test_init,
232 .exit = example_test_exit,
233 .suite_init = example_suite_init,
234 .suite_exit = example_suite_exit,
235 .test_cases = example_test_cases,
236 };
237 kunit_test_suite(example_test_suite);
238
239In the above example, the test suite ``example_test_suite`` would first run
240``example_suite_init``, then run the test cases ``example_test_foo``,
241``example_test_bar``, and ``example_test_baz``. Each would have
242``example_test_init`` called immediately before it and ``example_test_exit``
243called immediately after it. Finally, ``example_suite_exit`` would be called
244after everything else. ``kunit_test_suite(example_test_suite)`` registers the
245test suite with the KUnit test framework.
246
247.. note::
248 The ``exit`` and ``suite_exit`` functions will run even if ``init`` or
249 ``suite_init`` fail. Make sure that they can handle any inconsistent
250 state which may result from ``init`` or ``suite_init`` encountering errors
251 or exiting early.
252
253``kunit_test_suite(...)`` is a macro which tells the linker to put the
254specified test suite in a special linker section so that it can be run by KUnit
255either after ``late_init``, or when the test module is loaded (if the test was
256built as a module).
257
258For more information, see Documentation/dev-tools/kunit/api/test.rst.
259
260.. _kunit-on-non-uml:
261
262Writing Tests For Other Architectures
263-------------------------------------
264
265It is better to write tests that run on UML to tests that only run under a
266particular architecture. It is better to write tests that run under QEMU or
267another easy to obtain (and monetarily free) software environment to a specific
268piece of hardware.
269
270Nevertheless, there are still valid reasons to write a test that is architecture
271or hardware specific. For example, we might want to test code that really
272belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
273not depend on physical hardware. Some of our test cases may not need hardware,
274only few tests actually require the hardware to test it. When hardware is not
275available, instead of disabling tests, we can skip them.
276
277Now that we have narrowed down exactly what bits are hardware specific, the
278actual procedure for writing and running the tests is same as writing normal
279KUnit tests.
280
281.. important::
282 We may have to reset hardware state. If this is not possible, we may only
283 be able to run one test case per invocation.
284
285.. TODO([email protected]): Add an actual example of an architecture-
286 dependent KUnit test.
287
288Common Patterns
289===============
290
291Isolating Behavior
292------------------
293
294Unit testing limits the amount of code under test to a single unit. It controls
295what code gets run when the unit under test calls a function. Where a function
296is exposed as part of an API such that the definition of that function can be
297changed without affecting the rest of the code base. In the kernel, this comes
298from two constructs: classes, which are structs that contain function pointers
299provided by the implementer, and architecture-specific functions, which have
300definitions selected at compile time.
301
302Classes
303~~~~~~~
304
305Classes are not a construct that is built into the C programming language;
306however, it is an easily derived concept. Accordingly, in most cases, every
307project that does not use a standardized object oriented library (like GNOME's
308GObject) has their own slightly different way of doing object oriented
309programming; the Linux kernel is no exception.
310
311The central concept in kernel object oriented programming is the class. In the
312kernel, a *class* is a struct that contains function pointers. This creates a
313contract between *implementers* and *users* since it forces them to use the
314same function signature without having to call the function directly. To be a
315class, the function pointers must specify that a pointer to the class, known as
316a *class handle*, be one of the parameters. Thus the member functions (also
317known as *methods*) have access to member variables (also known as *fields*)
318allowing the same implementation to have multiple *instances*.
319
320A class can be *overridden* by *child classes* by embedding the *parent class*
321in the child class. Then when the child class *method* is called, the child
322implementation knows that the pointer passed to it is of a parent contained
323within the child. Thus, the child can compute the pointer to itself because the
324pointer to the parent is always a fixed offset from the pointer to the child.
325This offset is the offset of the parent contained in the child struct. For
326example:
327
328.. code-block:: c
329
330 struct shape {
331 int (*area)(struct shape *this);
332 };
333
334 struct rectangle {
335 struct shape parent;
336 int length;
337 int width;
338 };
339
340 int rectangle_area(struct shape *this)
341 {
342 struct rectangle *self = container_of(this, struct rectangle, parent);
343
344 return self->length * self->width;
345 };
346
347 void rectangle_new(struct rectangle *self, int length, int width)
348 {
349 self->parent.area = rectangle_area;
350 self->length = length;
351 self->width = width;
352 }
353
354In this example, computing the pointer to the child from the pointer to the
355parent is done by ``container_of``.
356
357Faking Classes
358~~~~~~~~~~~~~~
359
360In order to unit test a piece of code that calls a method in a class, the
361behavior of the method must be controllable, otherwise the test ceases to be a
362unit test and becomes an integration test.
363
364A fake class implements a piece of code that is different than what runs in a
365production instance, but behaves identical from the standpoint of the callers.
366This is done to replace a dependency that is hard to deal with, or is slow. For
367example, implementing a fake EEPROM that stores the "contents" in an
368internal buffer. Assume we have a class that represents an EEPROM:
369
370.. code-block:: c
371
372 struct eeprom {
373 ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
374 ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
375 };
376
377And we want to test code that buffers writes to the EEPROM:
378
379.. code-block:: c
380
381 struct eeprom_buffer {
382 ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
383 int flush(struct eeprom_buffer *this);
384 size_t flush_count; /* Flushes when buffer exceeds flush_count. */
385 };
386
387 struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
388 void destroy_eeprom_buffer(struct eeprom *eeprom);
389
390We can test this code by *faking out* the underlying EEPROM:
391
392.. code-block:: c
393
394 struct fake_eeprom {
395 struct eeprom parent;
396 char contents[FAKE_EEPROM_CONTENTS_SIZE];
397 };
398
399 ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
400 {
401 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
402
403 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
404 memcpy(buffer, this->contents + offset, count);
405
406 return count;
407 }
408
409 ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
410 {
411 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
412
413 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
414 memcpy(this->contents + offset, buffer, count);
415
416 return count;
417 }
418
419 void fake_eeprom_init(struct fake_eeprom *this)
420 {
421 this->parent.read = fake_eeprom_read;
422 this->parent.write = fake_eeprom_write;
423 memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
424 }
425
426We can now use it to test ``struct eeprom_buffer``:
427
428.. code-block:: c
429
430 struct eeprom_buffer_test {
431 struct fake_eeprom *fake_eeprom;
432 struct eeprom_buffer *eeprom_buffer;
433 };
434
435 static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
436 {
437 struct eeprom_buffer_test *ctx = test->priv;
438 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
439 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
440 char buffer[] = {0xff};
441
442 eeprom_buffer->flush_count = SIZE_MAX;
443
444 eeprom_buffer->write(eeprom_buffer, buffer, 1);
445 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
446
447 eeprom_buffer->write(eeprom_buffer, buffer, 1);
448 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
449
450 eeprom_buffer->flush(eeprom_buffer);
451 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
452 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
453 }
454
455 static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
456 {
457 struct eeprom_buffer_test *ctx = test->priv;
458 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
459 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
460 char buffer[] = {0xff};
461
462 eeprom_buffer->flush_count = 2;
463
464 eeprom_buffer->write(eeprom_buffer, buffer, 1);
465 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
466
467 eeprom_buffer->write(eeprom_buffer, buffer, 1);
468 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
469 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
470 }
471
472 static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
473 {
474 struct eeprom_buffer_test *ctx = test->priv;
475 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
476 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
477 char buffer[] = {0xff, 0xff};
478
479 eeprom_buffer->flush_count = 2;
480
481 eeprom_buffer->write(eeprom_buffer, buffer, 1);
482 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
483
484 eeprom_buffer->write(eeprom_buffer, buffer, 2);
485 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
486 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
487 /* Should have only flushed the first two bytes. */
488 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
489 }
490
491 static int eeprom_buffer_test_init(struct kunit *test)
492 {
493 struct eeprom_buffer_test *ctx;
494
495 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
496 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
497
498 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
499 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
500 fake_eeprom_init(ctx->fake_eeprom);
501
502 ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
503 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
504
505 test->priv = ctx;
506
507 return 0;
508 }
509
510 static void eeprom_buffer_test_exit(struct kunit *test)
511 {
512 struct eeprom_buffer_test *ctx = test->priv;
513
514 destroy_eeprom_buffer(ctx->eeprom_buffer);
515 }
516
517Testing Against Multiple Inputs
518-------------------------------
519
520Testing just a few inputs is not enough to ensure that the code works correctly,
521for example: testing a hash function.
522
523We can write a helper macro or function. The function is called for each input.
524For example, to test ``sha1sum(1)``, we can write:
525
526.. code-block:: c
527
528 #define TEST_SHA1(in, want) \
529 sha1sum(in, out); \
530 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
531
532 char out[40];
533 TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
534 TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");
535
536Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more
537detailed error and make the assertions clearer within the helper macros.
538
539The ``_MSG`` variants are useful when the same expectation is called multiple
540times (in a loop or helper function) and thus the line number is not enough to
541identify what failed, as shown below.
542
543In complicated cases, we recommend using a *table-driven test* compared to the
544helper macro variation, for example:
545
546.. code-block:: c
547
548 int i;
549 char out[40];
550
551 struct sha1_test_case {
552 const char *str;
553 const char *sha1;
554 };
555
556 struct sha1_test_case cases[] = {
557 {
558 .str = "hello world",
559 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
560 },
561 {
562 .str = "hello world!",
563 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
564 },
565 };
566 for (i = 0; i < ARRAY_SIZE(cases); ++i) {
567 sha1sum(cases[i].str, out);
568 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
569 "sha1sum(%s)", cases[i].str);
570 }
571
572
573There is more boilerplate code involved, but it can:
574
575* be more readable when there are multiple inputs/outputs (due to field names).
576
577 * For example, see ``fs/ext4/inode-test.c``.
578
579* reduce duplication if test cases are shared across multiple tests.
580
581 * For example: if we want to test ``sha256sum``, we could add a ``sha256``
582 field and reuse ``cases``.
583
584* be converted to a "parameterized test".
585
586Parameterized Testing
587~~~~~~~~~~~~~~~~~~~~~
588
589To run a test case against multiple inputs, KUnit provides a parameterized
590testing framework. This feature formalizes and extends the concept of
591table-driven tests discussed previously.
592
593A KUnit test is determined to be parameterized if a parameter generator function
594is provided when registering the test case. A test user can either write their
595own generator function or use one that is provided by KUnit. The generator
596function is stored in ``kunit_case->generate_params`` and can be set using the
597macros described in the section below.
598
599To establish the terminology, a "parameterized test" is a test which is run
600multiple times (once per "parameter" or "parameter run"). Each parameter run has
601both its own independent ``struct kunit`` (the "parameter run context") and
602access to a shared parent ``struct kunit`` (the "parameterized test context").
603
604Passing Parameters to a Test
605^^^^^^^^^^^^^^^^^^^^^^^^^^^^
606There are three ways to provide the parameters to a test:
607
608Array Parameter Macros:
609
610 KUnit provides special support for the common table-driven testing pattern.
611 By applying either ``KUNIT_ARRAY_PARAM`` or ``KUNIT_ARRAY_PARAM_DESC`` to the
612 ``cases`` array from the previous section, we can create a parameterized test
613 as shown below:
614
615.. code-block:: c
616
617 // This is copy-pasted from above.
618 struct sha1_test_case {
619 const char *str;
620 const char *sha1;
621 };
622 static const struct sha1_test_case cases[] = {
623 {
624 .str = "hello world",
625 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
626 },
627 {
628 .str = "hello world!",
629 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
630 },
631 };
632
633 // Creates `sha1_gen_params()` to iterate over `cases` while using
634 // the struct member `str` for the case description.
635 KUNIT_ARRAY_PARAM_DESC(sha1, cases, str);
636
637 // Looks no different from a normal test.
638 static void sha1_test(struct kunit *test)
639 {
640 // This function can just contain the body of the for-loop.
641 // The former `cases[i]` is accessible under test->param_value.
642 char out[40];
643 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
644
645 sha1sum(test_param->str, out);
646 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
647 "sha1sum(%s)", test_param->str);
648 }
649
650 // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
651 // function declared by KUNIT_ARRAY_PARAM or KUNIT_ARRAY_PARAM_DESC.
652 static struct kunit_case sha1_test_cases[] = {
653 KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
654 {}
655 };
656
657Custom Parameter Generator Function:
658
659 The generator function is responsible for generating parameters one-by-one
660 and has the following signature:
661 ``const void* (*)(struct kunit *test, const void *prev, char *desc)``.
662 You can pass the generator function to the ``KUNIT_CASE_PARAM``
663 or ``KUNIT_CASE_PARAM_WITH_INIT`` macros.
664
665 The function receives the previously generated parameter as the ``prev`` argument
666 (which is ``NULL`` on the first call) and can also access the parameterized
667 test context passed as the ``test`` argument. KUnit calls this function
668 repeatedly until it returns ``NULL``, which signifies that a parameterized
669 test ended.
670
671 Below is an example of how it works:
672
673.. code-block:: c
674
675 #define MAX_TEST_BUFFER_SIZE 8
676
677 // Example generator function. It produces a sequence of buffer sizes that
678 // are powers of two, starting at 1 (e.g., 1, 2, 4, 8).
679 static const void *buffer_size_gen_params(struct kunit *test, const void *prev, char *desc)
680 {
681 long prev_buffer_size = (long)prev;
682 long next_buffer_size = 1; // Start with an initial size of 1.
683
684 // Stop generating parameters if the limit is reached or exceeded.
685 if (prev_buffer_size >= MAX_TEST_BUFFER_SIZE)
686 return NULL;
687
688 // For subsequent calls, calculate the next size by doubling the previous one.
689 if (prev)
690 next_buffer_size = prev_buffer_size << 1;
691
692 return (void *)next_buffer_size;
693 }
694
695 // Simple test to validate that kunit_kzalloc provides zeroed memory.
696 static void buffer_zero_test(struct kunit *test)
697 {
698 long buffer_size = (long)test->param_value;
699 // Use kunit_kzalloc to allocate a zero-initialized buffer. This makes the
700 // memory "parameter run managed," meaning it's automatically cleaned up at
701 // the end of each parameter run.
702 int *buf = kunit_kzalloc(test, buffer_size * sizeof(int), GFP_KERNEL);
703
704 // Ensure the allocation was successful.
705 KUNIT_ASSERT_NOT_NULL(test, buf);
706
707 // Loop through the buffer and confirm every element is zero.
708 for (int i = 0; i < buffer_size; i++)
709 KUNIT_EXPECT_EQ(test, buf[i], 0);
710 }
711
712 static struct kunit_case buffer_test_cases[] = {
713 KUNIT_CASE_PARAM(buffer_zero_test, buffer_size_gen_params),
714 {}
715 };
716
717Runtime Parameter Array Registration in the Init Function:
718
719 For scenarios where you might need to initialize a parameterized test, you
720 can directly register a parameter array to the parameterized test context.
721
722 To do this, you must pass the parameterized test context, the array itself,
723 the array size, and a ``get_description()`` function to the
724 ``kunit_register_params_array()`` macro. This macro populates
725 ``struct kunit_params`` within the parameterized test context, effectively
726 storing a parameter array object. The ``get_description()`` function will
727 be used for populating parameter descriptions and has the following signature:
728 ``void (*)(struct kunit *test, const void *param, char *desc)``. Note that it
729 also has access to the parameterized test context.
730
731 .. important::
732 When using this way to register a parameter array, you will need to
733 manually pass ``kunit_array_gen_params()`` as the generator function to
734 ``KUNIT_CASE_PARAM_WITH_INIT``. ``kunit_array_gen_params()`` is a KUnit
735 helper that will use the registered array to generate the parameters.
736
737 If needed, instead of passing the KUnit helper, you can also pass your
738 own custom generator function that utilizes the parameter array. To
739 access the parameter array from within the parameter generator
740 function use ``test->params_array.params``.
741
742 The ``kunit_register_params_array()`` macro should be called within a
743 ``param_init()`` function that initializes the parameterized test and has
744 the following signature ``int (*)(struct kunit *test)``. For a detailed
745 explanation of this mechanism please refer to the "Adding Shared Resources"
746 section that is after this one. This method supports registering both
747 dynamically built and static parameter arrays.
748
749 The code snippet below shows the ``example_param_init_dynamic_arr`` test that
750 utilizes ``make_fibonacci_params()`` to create a dynamic array, which is then
751 registered using ``kunit_register_params_array()``. To see the full code
752 please refer to lib/kunit/kunit-example-test.c.
753
754.. code-block:: c
755
756 /*
757 * Example of a parameterized test param_init() function that registers a dynamic
758 * array of parameters.
759 */
760 static int example_param_init_dynamic_arr(struct kunit *test)
761 {
762 size_t seq_size;
763 int *fibonacci_params;
764
765 kunit_info(test, "initializing parameterized test\n");
766
767 seq_size = 6;
768 fibonacci_params = make_fibonacci_params(test, seq_size);
769 if (!fibonacci_params)
770 return -ENOMEM;
771 /*
772 * Passes the dynamic parameter array information to the parameterized test
773 * context struct kunit. The array and its metadata will be stored in
774 * test->parent->params_array. The array itself will be located in
775 * params_data.params.
776 */
777 kunit_register_params_array(test, fibonacci_params, seq_size,
778 example_param_dynamic_arr_get_desc);
779 return 0;
780 }
781
782 static struct kunit_case example_test_cases[] = {
783 /*
784 * Note how we pass kunit_array_gen_params() to use the array we
785 * registered in example_param_init_dynamic_arr() to generate
786 * parameters.
787 */
788 KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_dynamic_arr,
789 kunit_array_gen_params,
790 example_param_init_dynamic_arr,
791 example_param_exit_dynamic_arr),
792 {}
793 };
794
795Adding Shared Resources
796^^^^^^^^^^^^^^^^^^^^^^^
797All parameter runs in this framework hold a reference to the parameterized test
798context, which can be accessed using the parent ``struct kunit`` pointer. The
799parameterized test context is not used to execute any test logic itself; instead,
800it serves as a container for shared resources.
801
802It's possible to add resources to share between parameter runs within a
803parameterized test by using ``KUNIT_CASE_PARAM_WITH_INIT``, to which you pass
804custom ``param_init()`` and ``param_exit()`` functions. These functions run once
805before and once after the parameterized test, respectively.
806
807The ``param_init()`` function, with the signature ``int (*)(struct kunit *test)``,
808can be used for adding resources to the ``resources`` or ``priv`` fields of
809the parameterized test context, registering the parameter array, and any other
810initialization logic.
811
812The ``param_exit()`` function, with the signature ``void (*)(struct kunit *test)``,
813can be used to release any resources that were not parameterized test managed (i.e.
814not automatically cleaned up after the parameterized test ends) and for any other
815exit logic.
816
817Both ``param_init()`` and ``param_exit()`` are passed the parameterized test
818context behind the scenes. However, the test case function receives the parameter
819run context. Therefore, to manage and access shared resources from within a test
820case function, you must use ``test->parent``.
821
822For instance, finding a shared resource allocated by the Resource API requires
823passing ``test->parent`` to ``kunit_find_resource()``. This principle extends to
824all other APIs that might be used in the test case function, including
825``kunit_kzalloc()``, ``kunit_kmalloc_array()``, and others (see
826Documentation/dev-tools/kunit/api/test.rst and the
827Documentation/dev-tools/kunit/api/resource.rst).
828
829.. note::
830 The ``suite->init()`` function, which executes before each parameter run,
831 receives the parameter run context. Therefore, any resources set up in
832 ``suite->init()`` are cleaned up after each parameter run.
833
834The code below shows how you can add the shared resources. Note that this code
835utilizes the Resource API, which you can read more about here:
836Documentation/dev-tools/kunit/api/resource.rst. To see the full version of this
837code please refer to lib/kunit/kunit-example-test.c.
838
839.. code-block:: c
840
841 static int example_resource_init(struct kunit_resource *res, void *context)
842 {
843 ... /* Code that allocates memory and stores context in res->data. */
844 }
845
846 /* This function deallocates memory for the kunit_resource->data field. */
847 static void example_resource_free(struct kunit_resource *res)
848 {
849 kfree(res->data);
850 }
851
852 /* This match function locates a test resource based on defined criteria. */
853 static bool example_resource_alloc_match(struct kunit *test, struct kunit_resource *res,
854 void *match_data)
855 {
856 return res->data && res->free == example_resource_free;
857 }
858
859 /* Function to initialize the parameterized test. */
860 static int example_param_init(struct kunit *test)
861 {
862 int ctx = 3; /* Data to be stored. */
863 void *data = kunit_alloc_resource(test, example_resource_init,
864 example_resource_free,
865 GFP_KERNEL, &ctx);
866 if (!data)
867 return -ENOMEM;
868 kunit_register_params_array(test, example_params_array,
869 ARRAY_SIZE(example_params_array));
870 return 0;
871 }
872
873 /* Example test that uses shared resources in test->resources. */
874 static void example_params_test_with_init(struct kunit *test)
875 {
876 int threshold;
877 const struct example_param *param = test->param_value;
878 /* Here we pass test->parent to access the parameterized test context. */
879 struct kunit_resource *res = kunit_find_resource(test->parent,
880 example_resource_alloc_match,
881 NULL);
882
883 threshold = *((int *)res->data);
884 KUNIT_ASSERT_LE(test, param->value, threshold);
885 kunit_put_resource(res);
886 }
887
888 static struct kunit_case example_test_cases[] = {
889 KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, kunit_array_gen_params,
890 example_param_init, NULL),
891 {}
892 };
893
894As an alternative to using the KUnit Resource API for sharing resources, you can
895place them in ``test->parent->priv``. This serves as a more lightweight method
896for resource storage, best for scenarios where complex resource management is
897not required.
898
899As stated previously ``param_init()`` and ``param_exit()`` get the parameterized
900test context. So, you can directly use ``test->priv`` within ``param_init/exit``
901to manage shared resources. However, from within the test case function, you must
902navigate up to the parent ``struct kunit`` i.e. the parameterized test context.
903Therefore, you need to use ``test->parent->priv`` to access those same
904resources.
905
906The resources placed in ``test->parent->priv`` will need to be allocated in
907memory to persist across the parameter runs. If memory is allocated using the
908KUnit memory allocation APIs (described more in the "Allocating Memory" section
909below), you won't need to worry about deallocation. The APIs will make the memory
910parameterized test 'managed', ensuring that it will automatically get cleaned up
911after the parameterized test concludes.
912
913The code below demonstrates example usage of the ``priv`` field for shared
914resources:
915
916.. code-block:: c
917
918 static const struct example_param {
919 int value;
920 } example_params_array[] = {
921 { .value = 3, },
922 { .value = 2, },
923 { .value = 1, },
924 { .value = 0, },
925 };
926
927 /* Initialize the parameterized test context. */
928 static int example_param_init_priv(struct kunit *test)
929 {
930 int ctx = 3; /* Data to be stored. */
931 int arr_size = ARRAY_SIZE(example_params_array);
932
933 /*
934 * Allocate memory using kunit_kzalloc(). Since the `param_init`
935 * function receives the parameterized test context, this memory
936 * allocation will be scoped to the lifetime of the parameterized test.
937 */
938 test->priv = kunit_kzalloc(test, sizeof(int), GFP_KERNEL);
939
940 /* Assign the context value to test->priv.*/
941 *((int *)test->priv) = ctx;
942
943 /* Register the parameter array. */
944 kunit_register_params_array(test, example_params_array, arr_size, NULL);
945 return 0;
946 }
947
948 static void example_params_test_with_init_priv(struct kunit *test)
949 {
950 int threshold;
951 const struct example_param *param = test->param_value;
952
953 /* By design, test->parent will not be NULL. */
954 KUNIT_ASSERT_NOT_NULL(test, test->parent);
955
956 /* Here we use test->parent->priv to access the shared resource. */
957 threshold = *(int *)test->parent->priv;
958
959 KUNIT_ASSERT_LE(test, param->value, threshold);
960 }
961
962 static struct kunit_case example_tests[] = {
963 KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_priv,
964 kunit_array_gen_params,
965 example_param_init_priv, NULL),
966 {}
967 };
968
969Allocating Memory
970-----------------
971
972Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit
973will then ensure that the memory is freed once the test completes.
974
975This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit
976early from a test without having to worry about remembering to call ``kfree``.
977For example:
978
979.. code-block:: c
980
981 void example_test_allocation(struct kunit *test)
982 {
983 char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
984 /* Ensure allocation succeeded. */
985 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);
986
987 KUNIT_ASSERT_STREQ(test, buffer, "");
988 }
989
990Registering Cleanup Actions
991---------------------------
992
993If you need to perform some cleanup beyond simple use of ``kunit_kzalloc``,
994you can register a custom "deferred action", which is a cleanup function
995run when the test exits (whether cleanly, or via a failed assertion).
996
997Actions are simple functions with no return value, and a single ``void*``
998context argument, and fulfill the same role as "cleanup" functions in Python
999and Go tests, "defer" statements in languages which support them, and
1000(in some cases) destructors in RAII languages.
1001
1002These are very useful for unregistering things from global lists, closing
1003files or other resources, or freeing resources.
1004
1005For example:
1006
1007.. code-block:: C
1008
1009 static void cleanup_device(void *ctx)
1010 {
1011 struct device *dev = (struct device *)ctx;
1012
1013 device_unregister(dev);
1014 }
1015
1016 void example_device_test(struct kunit *test)
1017 {
1018 struct my_device dev;
1019
1020 device_register(&dev);
1021
1022 kunit_add_action(test, &cleanup_device, &dev);
1023 }
1024
1025Note that, for functions like device_unregister which only accept a single
1026pointer-sized argument, it's possible to automatically generate a wrapper
1027with the ``KUNIT_DEFINE_ACTION_WRAPPER()`` macro, for example:
1028
1029.. code-block:: C
1030
1031 KUNIT_DEFINE_ACTION_WRAPPER(device_unregister, device_unregister_wrapper, struct device *);
1032 kunit_add_action(test, &device_unregister_wrapper, &dev);
1033
1034You should do this in preference to manually casting to the ``kunit_action_t`` type,
1035as casting function pointers will break Control Flow Integrity (CFI).
1036
1037``kunit_add_action`` can fail if, for example, the system is out of memory.
1038You can use ``kunit_add_action_or_reset`` instead which runs the action
1039immediately if it cannot be deferred.
1040
1041If you need more control over when the cleanup function is called, you
1042can trigger it early using ``kunit_release_action``, or cancel it entirely
1043with ``kunit_remove_action``.
1044
1045
1046Testing Static Functions
1047------------------------
1048
1049If you want to test static functions without exposing those functions outside of
1050testing, one option is conditionally export the symbol. When KUnit is enabled,
1051the symbol is exposed but remains static otherwise. To use this method, follow
1052the template below.
1053
1054.. code-block:: c
1055
1056 /* In the file containing functions to test "my_file.c" */
1057
1058 #include <kunit/visibility.h>
1059 #include <my_file.h>
1060 ...
1061 VISIBLE_IF_KUNIT int do_interesting_thing()
1062 {
1063 ...
1064 }
1065 EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);
1066
1067 /* In the header file "my_file.h" */
1068
1069 #if IS_ENABLED(CONFIG_KUNIT)
1070 int do_interesting_thing(void);
1071 #endif
1072
1073 /* In the KUnit test file "my_file_test.c" */
1074
1075 #include <kunit/visibility.h>
1076 #include <my_file.h>
1077 ...
1078 MODULE_IMPORT_NS("EXPORTED_FOR_KUNIT_TESTING");
1079 ...
1080 // Use do_interesting_thing() in tests
1081
1082For a full example, see this `patch <https://lore.kernel.org/all/[email protected]/>`_
1083where a test is modified to conditionally expose static functions for testing
1084using the macros above.
1085
1086As an **alternative** to the method above, you could conditionally ``#include``
1087the test file at the end of your .c file. This is not recommended but works
1088if needed. For example:
1089
1090.. code-block:: c
1091
1092 /* In "my_file.c" */
1093
1094 static int do_interesting_thing();
1095
1096 #ifdef CONFIG_MY_KUNIT_TEST
1097 #include "my_kunit_test.c"
1098 #endif
1099
1100Injecting Test-Only Code
1101------------------------
1102
1103Similar to as shown above, we can add test-specific logic. For example:
1104
1105.. code-block:: c
1106
1107 /* In my_file.h */
1108
1109 #ifdef CONFIG_MY_KUNIT_TEST
1110 /* Defined in my_kunit_test.c */
1111 void test_only_hook(void);
1112 #else
1113 void test_only_hook(void) { }
1114 #endif
1115
1116This test-only code can be made more useful by accessing the current ``kunit_test``
1117as shown in next section: *Accessing The Current Test*.
1118
1119Accessing The Current Test
1120--------------------------
1121
1122In some cases, we need to call test-only code from outside the test file. This
1123is helpful, for example, when providing a fake implementation of a function, or
1124to fail any current test from within an error handler.
1125We can do this via the ``kunit_test`` field in ``task_struct``, which we can
1126access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``.
1127
1128``kunit_get_current_test()`` is safe to call even if KUnit is not enabled. If
1129KUnit is not enabled, or if no test is running in the current task, it will
1130return ``NULL``. This compiles down to either a no-op or a static key check,
1131so will have a negligible performance impact when no test is running.
1132
1133The example below uses this to implement a "mock" implementation of a function, ``foo``:
1134
1135.. code-block:: c
1136
1137 #include <kunit/test-bug.h> /* for kunit_get_current_test */
1138
1139 struct test_data {
1140 int foo_result;
1141 int want_foo_called_with;
1142 };
1143
1144 static int fake_foo(int arg)
1145 {
1146 struct kunit *test = kunit_get_current_test();
1147 struct test_data *test_data = test->priv;
1148
1149 KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
1150 return test_data->foo_result;
1151 }
1152
1153 static void example_simple_test(struct kunit *test)
1154 {
1155 /* Assume priv (private, a member used to pass test data from
1156 * the init function) is allocated in the suite's .init */
1157 struct test_data *test_data = test->priv;
1158
1159 test_data->foo_result = 42;
1160 test_data->want_foo_called_with = 1;
1161
1162 /* In a real test, we'd probably pass a pointer to fake_foo somewhere
1163 * like an ops struct, etc. instead of calling it directly. */
1164 KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
1165 }
1166
1167In this example, we are using the ``priv`` member of ``struct kunit`` as a way
1168of passing data to the test from the init function. In general ``priv`` is
1169pointer that can be used for any user data. This is preferred over static
1170variables, as it avoids concurrency issues.
1171
1172Had we wanted something more flexible, we could have used a named ``kunit_resource``.
1173Each test can have multiple resources which have string names providing the same
1174flexibility as a ``priv`` member, but also, for example, allowing helper
1175functions to create resources without conflicting with each other. It is also
1176possible to define a clean up function for each resource, making it easy to
1177avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst.
1178
1179Failing The Current Test
1180------------------------
1181
1182If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
1183which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
1184For example, we have an option to enable some extra debug checks on some data
1185structures as shown below:
1186
1187.. code-block:: c
1188
1189 #include <kunit/test-bug.h>
1190
1191 #ifdef CONFIG_EXTRA_DEBUG_CHECKS
1192 static void validate_my_data(struct data *data)
1193 {
1194 if (is_valid(data))
1195 return;
1196
1197 kunit_fail_current_test("data %p is invalid", data);
1198
1199 /* Normal, non-KUnit, error reporting code here. */
1200 }
1201 #else
1202 static void my_debug_function(void) { }
1203 #endif
1204
1205``kunit_fail_current_test()`` is safe to call even if KUnit is not enabled. If
1206KUnit is not enabled, or if no test is running in the current task, it will do
1207nothing. This compiles down to either a no-op or a static key check, so will
1208have a negligible performance impact when no test is running.
1209
1210Managing Fake Devices and Drivers
1211---------------------------------
1212
1213When testing drivers or code which interacts with drivers, many functions will
1214require a ``struct device`` or ``struct device_driver``. In many cases, setting
1215up a real device is not required to test any given function, so a fake device
1216can be used instead.
1217
1218KUnit provides helper functions to create and manage these fake devices, which
1219are internally of type ``struct kunit_device``, and are attached to a special
1220``kunit_bus``. These devices support managed device resources (devres), as
1221described in Documentation/driver-api/driver-model/devres.rst
1222
1223To create a KUnit-managed ``struct device_driver``, use ``kunit_driver_create()``,
1224which will create a driver with the given name, on the ``kunit_bus``. This driver
1225will automatically be destroyed when the corresponding test finishes, but can also
1226be manually destroyed with ``driver_unregister()``.
1227
1228To create a fake device, use the ``kunit_device_register()``, which will create
1229and register a device, using a new KUnit-managed driver created with ``kunit_driver_create()``.
1230To provide a specific, non-KUnit-managed driver, use ``kunit_device_register_with_driver()``
1231instead. Like with managed drivers, KUnit-managed fake devices are automatically
1232cleaned up when the test finishes, but can be manually cleaned up early with
1233``kunit_device_unregister()``.
1234
1235The KUnit devices should be used in preference to ``root_device_register()``, and
1236instead of ``platform_device_register()`` in cases where the device is not otherwise
1237a platform device.
1238
1239For example:
1240
1241.. code-block:: c
1242
1243 #include <kunit/device.h>
1244
1245 static void test_my_device(struct kunit *test)
1246 {
1247 struct device *fake_device;
1248 const char *dev_managed_string;
1249
1250 // Create a fake device.
1251 fake_device = kunit_device_register(test, "my_device");
1252 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device)
1253
1254 // Pass it to functions which need a device.
1255 dev_managed_string = devm_kstrdup(fake_device, "Hello, World!");
1256
1257 // Everything is cleaned up automatically when the test ends.
1258 }