1 .. SPDX-License-Identifier: GPL-2.0
9 The fundamental unit in KUnit is the test case. A test case is a function with
10 the signature ``void (*)(struct kunit *test)``. It calls the function under test
11 and then sets *expectations* for what should happen. For example:
15 void example_test_success(struct kunit *test)
19 void example_test_failure(struct kunit *test)
21 KUNIT_FAIL(test, "This test never passes.");
24 In the above example, ``example_test_success`` always passes because it does
25 nothing; no expectations are set, and therefore all expectations pass. On the
26 other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``,
27 which is a special expectation that logs a message and causes the test case to
32 An *expectation* specifies that we expect a piece of code to do something in a
33 test. An expectation is called like a function. A test is made by setting
34 expectations about the behavior of a piece of code under test. When one or more
35 expectations fail, the test case fails and information about the failure is
40 void add_test_basic(struct kunit *test)
42 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
43 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
46 In the above example, ``add_test_basic`` makes a number of assertions about the
47 behavior of a function called ``add``. The first parameter is always of type
48 ``struct kunit *``, which contains information about the current test context.
49 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 ``add`` passes all of these
51 expectations, the test case, ``add_test_basic`` will pass; if any one of these
52 expectations fails, the test case will fail.
54 A test case *fails* when any expectation is violated; however, the test will
55 continue to run, and try other expectations until the test case ends or is
56 otherwise terminated. This is as opposed to *assertions* which are discussed
59 To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.
62 A single test case should be short, easy to understand, and focused on a
65 For example, if we want to rigorously test the ``add`` function above, create
66 additional tests cases which would test each property that an ``add`` function
67 should have as shown below:
71 void add_test_basic(struct kunit *test)
73 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
74 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
77 void add_test_negative(struct kunit *test)
79 KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
82 void add_test_max(struct kunit *test)
84 KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
85 KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
88 void add_test_overflow(struct kunit *test)
90 KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
96 An assertion is like an expectation, except that the assertion immediately
97 terminates the test case if the condition is not satisfied. For example:
101 static void test_sort(struct kunit *test)
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;
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]);
115 In this example, the method under test should return pointer to a value. If the
116 pointer returns null or an errno, we want to stop the test since the following
117 expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us
118 to bail out of the test case if the appropriate conditions are not satisfied to
124 We need many test cases covering all the unit's behaviors. It is common to have
125 many similar tests. In order to reduce duplication in these closely related
126 tests, most unit testing frameworks (including KUnit) provide the concept of a
127 *test suite*. A test suite is a collection of test cases for a unit of code
128 with optional setup and teardown functions that run before/after the whole
129 suite and/or every test case. For example:
133 static struct kunit_case example_test_cases[] = {
134 KUNIT_CASE(example_test_foo),
135 KUNIT_CASE(example_test_bar),
136 KUNIT_CASE(example_test_baz),
140 static struct kunit_suite example_test_suite = {
142 .init = example_test_init,
143 .exit = example_test_exit,
144 .suite_init = example_suite_init,
145 .suite_exit = example_suite_exit,
146 .test_cases = example_test_cases,
148 kunit_test_suite(example_test_suite);
150 In the above example, the test suite ``example_test_suite`` would first run
151 ``example_suite_init``, then run the test cases ``example_test_foo``,
152 ``example_test_bar``, and ``example_test_baz``. Each would have
153 ``example_test_init`` called immediately before it and ``example_test_exit``
154 called immediately after it. Finally, ``example_suite_exit`` would be called
155 after everything else. ``kunit_test_suite(example_test_suite)`` registers the
156 test suite with the KUnit test framework.
159 A test case will only run if it is associated with a test suite.
161 ``kunit_test_suite(...)`` is a macro which tells the linker to put the
162 specified test suite in a special linker section so that it can be run by KUnit
163 either after ``late_init``, or when the test module is loaded (if the test was
166 For more information, see Documentation/dev-tools/kunit/api/test.rst.
168 Writing Tests For Other Architectures
169 -------------------------------------
171 It is better to write tests that run on UML to tests that only run under a
172 particular architecture. It is better to write tests that run under QEMU or
173 another easy to obtain (and monetarily free) software environment to a specific
176 Nevertheless, there are still valid reasons to write a test that is architecture
177 or hardware specific. For example, we might want to test code that really
178 belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
179 not depend on physical hardware. Some of our test cases may not need hardware,
180 only few tests actually require the hardware to test it. When hardware is not
181 available, instead of disabling tests, we can skip them.
183 Now that we have narrowed down exactly what bits are hardware specific, the
184 actual procedure for writing and running the tests is same as writing normal
188 We may have to reset hardware state. If this is not possible, we may only
189 be able to run one test case per invocation.
191 .. TODO(brendanhiggins@google.com): Add an actual example of an architecture-
192 dependent KUnit test.
200 Unit testing limits the amount of code under test to a single unit. It controls
201 what code gets run when the unit under test calls a function. Where a function
202 is exposed as part of an API such that the definition of that function can be
203 changed without affecting the rest of the code base. In the kernel, this comes
204 from two constructs: classes, which are structs that contain function pointers
205 provided by the implementer, and architecture-specific functions, which have
206 definitions selected at compile time.
211 Classes are not a construct that is built into the C programming language;
212 however, it is an easily derived concept. Accordingly, in most cases, every
213 project that does not use a standardized object oriented library (like GNOME's
214 GObject) has their own slightly different way of doing object oriented
215 programming; the Linux kernel is no exception.
217 The central concept in kernel object oriented programming is the class. In the
218 kernel, a *class* is a struct that contains function pointers. This creates a
219 contract between *implementers* and *users* since it forces them to use the
220 same function signature without having to call the function directly. To be a
221 class, the function pointers must specify that a pointer to the class, known as
222 a *class handle*, be one of the parameters. Thus the member functions (also
223 known as *methods*) have access to member variables (also known as *fields*)
224 allowing the same implementation to have multiple *instances*.
226 A class can be *overridden* by *child classes* by embedding the *parent class*
227 in the child class. Then when the child class *method* is called, the child
228 implementation knows that the pointer passed to it is of a parent contained
229 within the child. Thus, the child can compute the pointer to itself because the
230 pointer to the parent is always a fixed offset from the pointer to the child.
231 This offset is the offset of the parent contained in the child struct. For
237 int (*area)(struct shape *this);
246 int rectangle_area(struct shape *this)
248 struct rectangle *self = container_of(this, struct rectangle, parent);
250 return self->length * self->width;
253 void rectangle_new(struct rectangle *self, int length, int width)
255 self->parent.area = rectangle_area;
256 self->length = length;
260 In this example, computing the pointer to the child from the pointer to the
261 parent is done by ``container_of``.
266 In order to unit test a piece of code that calls a method in a class, the
267 behavior of the method must be controllable, otherwise the test ceases to be a
268 unit test and becomes an integration test.
270 A fake class implements a piece of code that is different than what runs in a
271 production instance, but behaves identical from the standpoint of the callers.
272 This is done to replace a dependency that is hard to deal with, or is slow. For
273 example, implementing a fake EEPROM that stores the "contents" in an
274 internal buffer. Assume we have a class that represents an EEPROM:
279 ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
280 ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
283 And we want to test code that buffers writes to the EEPROM:
287 struct eeprom_buffer {
288 ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
289 int flush(struct eeprom_buffer *this);
290 size_t flush_count; /* Flushes when buffer exceeds flush_count. */
293 struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
294 void destroy_eeprom_buffer(struct eeprom *eeprom);
296 We can test this code by *faking out* the underlying EEPROM:
301 struct eeprom parent;
302 char contents[FAKE_EEPROM_CONTENTS_SIZE];
305 ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
307 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
309 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
310 memcpy(buffer, this->contents + offset, count);
315 ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
317 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
319 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
320 memcpy(this->contents + offset, buffer, count);
325 void fake_eeprom_init(struct fake_eeprom *this)
327 this->parent.read = fake_eeprom_read;
328 this->parent.write = fake_eeprom_write;
329 memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
332 We can now use it to test ``struct eeprom_buffer``:
336 struct eeprom_buffer_test {
337 struct fake_eeprom *fake_eeprom;
338 struct eeprom_buffer *eeprom_buffer;
341 static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
343 struct eeprom_buffer_test *ctx = test->priv;
344 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
345 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
346 char buffer[] = {0xff};
348 eeprom_buffer->flush_count = SIZE_MAX;
350 eeprom_buffer->write(eeprom_buffer, buffer, 1);
351 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
353 eeprom_buffer->write(eeprom_buffer, buffer, 1);
354 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
356 eeprom_buffer->flush(eeprom_buffer);
357 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
358 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
361 static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
363 struct eeprom_buffer_test *ctx = test->priv;
364 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
365 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
366 char buffer[] = {0xff};
368 eeprom_buffer->flush_count = 2;
370 eeprom_buffer->write(eeprom_buffer, buffer, 1);
371 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
373 eeprom_buffer->write(eeprom_buffer, buffer, 1);
374 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
375 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
378 static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
380 struct eeprom_buffer_test *ctx = test->priv;
381 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
382 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
383 char buffer[] = {0xff, 0xff};
385 eeprom_buffer->flush_count = 2;
387 eeprom_buffer->write(eeprom_buffer, buffer, 1);
388 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
390 eeprom_buffer->write(eeprom_buffer, buffer, 2);
391 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
392 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
393 /* Should have only flushed the first two bytes. */
394 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
397 static int eeprom_buffer_test_init(struct kunit *test)
399 struct eeprom_buffer_test *ctx;
401 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
402 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
404 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
405 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
406 fake_eeprom_init(ctx->fake_eeprom);
408 ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
409 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
416 static void eeprom_buffer_test_exit(struct kunit *test)
418 struct eeprom_buffer_test *ctx = test->priv;
420 destroy_eeprom_buffer(ctx->eeprom_buffer);
423 Testing Against Multiple Inputs
424 -------------------------------
426 Testing just a few inputs is not enough to ensure that the code works correctly,
427 for example: testing a hash function.
429 We can write a helper macro or function. The function is called for each input.
430 For example, to test ``sha1sum(1)``, we can write:
434 #define TEST_SHA1(in, want) \
436 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
439 TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
440 TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");
442 Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more
443 detailed error and make the assertions clearer within the helper macros.
445 The ``_MSG`` variants are useful when the same expectation is called multiple
446 times (in a loop or helper function) and thus the line number is not enough to
447 identify what failed, as shown below.
449 In complicated cases, we recommend using a *table-driven test* compared to the
450 helper macro variation, for example:
457 struct sha1_test_case {
462 struct sha1_test_case cases[] = {
464 .str = "hello world",
465 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
468 .str = "hello world!",
469 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
472 for (i = 0; i < ARRAY_SIZE(cases); ++i) {
473 sha1sum(cases[i].str, out);
474 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
475 "sha1sum(%s)", cases[i].str);
479 There is more boilerplate code involved, but it can:
481 * be more readable when there are multiple inputs/outputs (due to field names).
483 * For example, see ``fs/ext4/inode-test.c``.
485 * reduce duplication if test cases are shared across multiple tests.
487 * For example: if we want to test ``sha256sum``, we could add a ``sha256``
488 field and reuse ``cases``.
490 * be converted to a "parameterized test".
492 Parameterized Testing
493 ~~~~~~~~~~~~~~~~~~~~~
495 The table-driven testing pattern is common enough that KUnit has special
498 By reusing the same ``cases`` array from above, we can write the test as a
499 "parameterized test" with the following.
503 // This is copy-pasted from above.
504 struct sha1_test_case {
508 struct sha1_test_case cases[] = {
510 .str = "hello world",
511 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
514 .str = "hello world!",
515 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
519 // Need a helper function to generate a name for each test case.
520 static void case_to_desc(const struct sha1_test_case *t, char *desc)
522 strcpy(desc, t->str);
524 // Creates `sha1_gen_params()` to iterate over `cases`.
525 KUNIT_ARRAY_PARAM(sha1, cases, case_to_desc);
527 // Looks no different from a normal test.
528 static void sha1_test(struct kunit *test)
530 // This function can just contain the body of the for-loop.
531 // The former `cases[i]` is accessible under test->param_value.
533 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
535 sha1sum(test_param->str, out);
536 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
537 "sha1sum(%s)", test_param->str);
540 // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
541 // function declared by KUNIT_ARRAY_PARAM.
542 static struct kunit_case sha1_test_cases[] = {
543 KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
547 .. _kunit-on-non-uml:
549 Exiting Early on Failed Expectations
550 ------------------------------------
552 We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue
553 execution. In some cases, it is unsafe to continue. We can use the
554 ``KUNIT_ASSERT`` variant to exit on failure.
558 void example_test_user_alloc_function(struct kunit *test)
560 void *object = alloc_some_object_for_me();
562 /* Make sure we got a valid pointer back. */
563 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object);
564 do_something_with_object(object);
570 Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit
571 will then ensure that the memory is freed once the test completes.
573 This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit
574 early from a test without having to worry about remembering to call ``kfree``.
579 void example_test_allocation(struct kunit *test)
581 char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
582 /* Ensure allocation succeeded. */
583 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);
585 KUNIT_ASSERT_STREQ(test, buffer, "");
589 Testing Static Functions
590 ------------------------
592 If we do not want to expose functions or variables for testing, one option is to
593 conditionally ``#include`` the test file at the end of your .c file. For
600 static int do_interesting_thing();
602 #ifdef CONFIG_MY_KUNIT_TEST
603 #include "my_kunit_test.c"
606 Injecting Test-Only Code
607 ------------------------
609 Similar to as shown above, we can add test-specific logic. For example:
615 #ifdef CONFIG_MY_KUNIT_TEST
616 /* Defined in my_kunit_test.c */
617 void test_only_hook(void);
619 void test_only_hook(void) { }
622 This test-only code can be made more useful by accessing the current ``kunit_test``
623 as shown in next section: *Accessing The Current Test*.
625 Accessing The Current Test
626 --------------------------
628 In some cases, we need to call test-only code from outside the test file.
629 For example, see example in section *Injecting Test-Only Code* or if
630 we are providing a fake implementation of an ops struct. Using
631 ``kunit_test`` field in ``task_struct``, we can access it via
632 ``current->kunit_test``.
634 The example below includes how to implement "mocking":
638 #include <linux/sched.h> /* for current */
642 int want_foo_called_with;
645 static int fake_foo(int arg)
647 struct kunit *test = current->kunit_test;
648 struct test_data *test_data = test->priv;
650 KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
651 return test_data->foo_result;
654 static void example_simple_test(struct kunit *test)
656 /* Assume priv (private, a member used to pass test data from
657 * the init function) is allocated in the suite's .init */
658 struct test_data *test_data = test->priv;
660 test_data->foo_result = 42;
661 test_data->want_foo_called_with = 1;
663 /* In a real test, we'd probably pass a pointer to fake_foo somewhere
664 * like an ops struct, etc. instead of calling it directly. */
665 KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
668 In this example, we are using the ``priv`` member of ``struct kunit`` as a way
669 of passing data to the test from the init function. In general ``priv`` is
670 pointer that can be used for any user data. This is preferred over static
671 variables, as it avoids concurrency issues.
673 Had we wanted something more flexible, we could have used a named ``kunit_resource``.
674 Each test can have multiple resources which have string names providing the same
675 flexibility as a ``priv`` member, but also, for example, allowing helper
676 functions to create resources without conflicting with each other. It is also
677 possible to define a clean up function for each resource, making it easy to
678 avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst.
680 Failing The Current Test
681 ------------------------
683 If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
684 which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
685 For example, we have an option to enable some extra debug checks on some data
686 structures as shown below:
690 #include <kunit/test-bug.h>
692 #ifdef CONFIG_EXTRA_DEBUG_CHECKS
693 static void validate_my_data(struct data *data)
698 kunit_fail_current_test("data %p is invalid", data);
700 /* Normal, non-KUnit, error reporting code here. */
703 static void my_debug_function(void) { }