1 .. SPDX-License-Identifier: GPL-2.0
2
3 Writing Tests
4 =============
5
6 Test Cases
7 ----------
8
9 The fundamental unit in KUnit is the test case
10 the signature ``void (*)(struct kunit *test)``
11 and then sets *expectations* for what should h
12
13 .. code-block:: c
14
15 void example_test_success(struct kunit
16 {
17 }
18
19 void example_test_failure(struct kunit
20 {
21 KUNIT_FAIL(test, "This test ne
22 }
23
24 In the above example, ``example_test_success``
25 nothing; no expectations are set, and therefor
26 other hand ``example_test_failure`` always fai
27 which is a special expectation that logs a mes
28 fail.
29
30 Expectations
31 ~~~~~~~~~~~~
32 An *expectation* specifies that we expect a pi
33 test. An expectation is called like a function
34 expectations about the behavior of a piece of
35 expectations fail, the test case fails and inf
36 logged. 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
43 KUNIT_EXPECT_EQ(test, 2, add(1
44 }
45
46 In the above example, ``add_test_basic`` makes
47 behavior of a function called ``add``. The fir
48 ``struct kunit *``, which contains information
49 The second parameter, in this case, is what th
50 last value is what the value actually is. If `
51 expectations, the test case, ``add_test_basic`
52 expectations fails, the test case will fail.
53
54 A test case *fails* when any expectation is vi
55 continue to run, and try other expectations un
56 otherwise terminated. This is as opposed to *a
57 later.
58
59 To learn about more KUnit expectations, see Do
60
61 .. note::
62 A single test case should be short, easy to
63 single behavior.
64
65 For example, if we want to rigorously test the
66 additional tests cases which would test each p
67 should 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
74 KUNIT_EXPECT_EQ(test, 2, add(1
75 }
76
77 void add_test_negative(struct kunit *t
78 {
79 KUNIT_EXPECT_EQ(test, 0, add(-
80 }
81
82 void add_test_max(struct kunit *test)
83 {
84 KUNIT_EXPECT_EQ(test, INT_MAX,
85 KUNIT_EXPECT_EQ(test, -1, add(
86 }
87
88 void add_test_overflow(struct kunit *t
89 {
90 KUNIT_EXPECT_EQ(test, INT_MIN,
91 }
92
93 Assertions
94 ~~~~~~~~~~
95
96 An assertion is like an expectation, except th
97 terminates the test case if the condition is n
98
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
148 Alternatively, one can take full control over
149 ``KUNIT_FAIL()``, e.g.
150
151 .. code-block:: c
152
153 /* Before */
154 KUNIT_EXPECT_EQ(test, some_setup_funct
155
156 /* After: full control over the failur
157 if (some_setup_function())
158 KUNIT_FAIL(test, "Failed to se
159
160
161 Test Suites
162 ~~~~~~~~~~~
163
164 We need many test cases covering all the unit'
165 many similar tests. In order to reduce duplica
166 tests, most unit testing frameworks (including
167 *test suite*. A test suite is a collection of
168 with optional setup and teardown functions tha
169 suite and/or every test case.
170
171 .. note::
172 A test case will only run if it is associat
173
174 For example:
175
176 .. code-block:: c
177
178 static struct kunit_case example_test_
179 KUNIT_CASE(example_test_foo),
180 KUNIT_CASE(example_test_bar),
181 KUNIT_CASE(example_test_baz),
182 {}
183 };
184
185 static struct kunit_suite example_test
186 .name = "example",
187 .init = example_test_init,
188 .exit = example_test_exit,
189 .suite_init = example_suite_in
190 .suite_exit = example_suite_ex
191 .test_cases = example_test_cas
192 };
193 kunit_test_suite(example_test_suite);
194
195 In the above example, the test suite ``example
196 ``example_suite_init``, then run the test case
197 ``example_test_bar``, and ``example_test_baz``
198 ``example_test_init`` called immediately befor
199 called immediately after it. Finally, ``exampl
200 after everything else. ``kunit_test_suite(exam
201 test suite with the KUnit test framework.
202
203 .. note::
204 The ``exit`` and ``suite_exit`` functions w
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
218 Writing Tests For Other Architectures
219 -------------------------------------
220
221 It is better to write tests that run on UML to
222 particular architecture. It is better to write
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
244 Common Patterns
245 ===============
246
247 Isolating Behavior
248 ------------------
249
250 Unit testing limits the amount of code under t
251 what code gets run when the unit under test ca
252 is exposed as part of an API such that the def
253 changed without affecting the rest of the code
254 from two constructs: classes, which are struct
255 provided by the implementer, and architecture-
256 definitions selected at compile time.
257
258 Classes
259 ~~~~~~~
260
261 Classes are not a construct that is built into
262 however, it is an easily derived concept. Acco
263 project that does not use a standardized objec
264 GObject) has their own slightly different way
265 programming; the Linux kernel is no exception.
266
267 The central concept in kernel object oriented
268 kernel, a *class* is a struct that contains fu
269 contract between *implementers* and *users* si
270 same function signature without having to call
271 class, the function pointers must specify that
272 a *class handle*, be one of the parameters. Th
273 known as *methods*) have access to member vari
274 allowing the same implementation to have multi
275
276 A class can be *overridden* by *child classes*
277 in the child class. Then when the child class
278 implementation knows that the pointer passed t
279 within the child. Thus, the child can compute
280 pointer to the parent is always a fixed offset
281 This offset is the offset of the parent contai
282 example:
283
284 .. code-block:: c
285
286 struct shape {
287 int (*area)(struct shape *this
288 };
289
290 struct rectangle {
291 struct shape parent;
292 int length;
293 int width;
294 };
295
296 int rectangle_area(struct shape *this)
297 {
298 struct rectangle *self = conta
299
300 return self->length * self->wi
301 };
302
303 void rectangle_new(struct rectangle *s
304 {
305 self->parent.area = rectangle_
306 self->length = length;
307 self->width = width;
308 }
309
310 In this example, computing the pointer to the
311 parent is done by ``container_of``.
312
313 Faking Classes
314 ~~~~~~~~~~~~~~
315
316 In order to unit test a piece of code that cal
317 behavior of the method must be controllable, o
318 unit test and becomes an integration test.
319
320 A fake class implements a piece of code that i
321 production instance, but behaves identical fro
322 This is done to replace a dependency that is h
323 example, implementing a fake EEPROM that store
324 internal buffer. Assume we have a class that r
325
326 .. code-block:: c
327
328 struct eeprom {
329 ssize_t (*read)(struct eeprom
330 ssize_t (*write)(struct eeprom
331 };
332
333 And we want to test code that buffers writes t
334
335 .. code-block:: c
336
337 struct eeprom_buffer {
338 ssize_t (*write)(struct eeprom
339 int flush(struct eeprom_buffer
340 size_t flush_count; /* Flushes
341 };
342
343 struct eeprom_buffer *new_eeprom_buffe
344 void destroy_eeprom_buffer(struct eepr
345
346 We can test this code by *faking out* the unde
347
348 .. code-block:: c
349
350 struct fake_eeprom {
351 struct eeprom parent;
352 char contents[FAKE_EEPROM_CONT
353 };
354
355 ssize_t fake_eeprom_read(struct eeprom
356 {
357 struct fake_eeprom *this = con
358
359 count = min(count, FAKE_EEPROM
360 memcpy(buffer, this->contents
361
362 return count;
363 }
364
365 ssize_t fake_eeprom_write(struct eepro
366 {
367 struct fake_eeprom *this = con
368
369 count = min(count, FAKE_EEPROM
370 memcpy(this->contents + offset
371
372 return count;
373 }
374
375 void fake_eeprom_init(struct fake_eepr
376 {
377 this->parent.read = fake_eepro
378 this->parent.write = fake_eepr
379 memset(this->contents, 0, FAKE
380 }
381
382 We can now use it to test ``struct eeprom_buff
383
384 .. code-block:: c
385
386 struct eeprom_buffer_test {
387 struct fake_eeprom *fake_eepro
388 struct eeprom_buffer *eeprom_b
389 };
390
391 static void eeprom_buffer_test_does_no
392 {
393 struct eeprom_buffer_test *ctx
394 struct eeprom_buffer *eeprom_b
395 struct fake_eeprom *fake_eepro
396 char buffer[] = {0xff};
397
398 eeprom_buffer->flush_count = S
399
400 eeprom_buffer->write(eeprom_bu
401 KUNIT_EXPECT_EQ(test, fake_eep
402
403 eeprom_buffer->write(eeprom_bu
404 KUNIT_EXPECT_EQ(test, fake_eep
405
406 eeprom_buffer->flush(eeprom_bu
407 KUNIT_EXPECT_EQ(test, fake_eep
408 KUNIT_EXPECT_EQ(test, fake_eep
409 }
410
411 static void eeprom_buffer_test_flushes
412 {
413 struct eeprom_buffer_test *ctx
414 struct eeprom_buffer *eeprom_b
415 struct fake_eeprom *fake_eepro
416 char buffer[] = {0xff};
417
418 eeprom_buffer->flush_count = 2
419
420 eeprom_buffer->write(eeprom_bu
421 KUNIT_EXPECT_EQ(test, fake_eep
422
423 eeprom_buffer->write(eeprom_bu
424 KUNIT_EXPECT_EQ(test, fake_eep
425 KUNIT_EXPECT_EQ(test, fake_eep
426 }
427
428 static void eeprom_buffer_test_flushes
429 {
430 struct eeprom_buffer_test *ctx
431 struct eeprom_buffer *eeprom_b
432 struct fake_eeprom *fake_eepro
433 char buffer[] = {0xff, 0xff};
434
435 eeprom_buffer->flush_count = 2
436
437 eeprom_buffer->write(eeprom_bu
438 KUNIT_EXPECT_EQ(test, fake_eep
439
440 eeprom_buffer->write(eeprom_bu
441 KUNIT_EXPECT_EQ(test, fake_eep
442 KUNIT_EXPECT_EQ(test, fake_eep
443 /* Should have only flushed th
444 KUNIT_EXPECT_EQ(test, fake_eep
445 }
446
447 static int eeprom_buffer_test_init(str
448 {
449 struct eeprom_buffer_test *ctx
450
451 ctx = kunit_kzalloc(test, size
452 KUNIT_ASSERT_NOT_ERR_OR_NULL(t
453
454 ctx->fake_eeprom = kunit_kzall
455 KUNIT_ASSERT_NOT_ERR_OR_NULL(t
456 fake_eeprom_init(ctx->fake_eep
457
458 ctx->eeprom_buffer = new_eepro
459 KUNIT_ASSERT_NOT_ERR_OR_NULL(t
460
461 test->priv = ctx;
462
463 return 0;
464 }
465
466 static void eeprom_buffer_test_exit(st
467 {
468 struct eeprom_buffer_test *ctx
469
470 destroy_eeprom_buffer(ctx->eep
471 }
472
473 Testing Against Multiple Inputs
474 -------------------------------
475
476 Testing just a few inputs is not enough to ens
477 for example: testing a hash function.
478
479 We can write a helper macro or function. The f
480 For example, to test ``sha1sum(1)``, we can wr
481
482 .. code-block:: c
483
484 #define TEST_SHA1(in, want) \
485 sha1sum(in, out); \
486 KUNIT_EXPECT_STREQ_MSG(test, o
487
488 char out[40];
489 TEST_SHA1("hello world", "2aae6c35c94
490 TEST_SHA1("hello world!", "430ce34d020
491
492 Note the use of the ``_MSG`` version of ``KUNI
493 detailed error and make the assertions clearer
494
495 The ``_MSG`` variants are useful when the same
496 times (in a loop or helper function) and thus
497 identify what failed, as shown below.
498
499 In complicated cases, we recommend using a *ta
500 helper macro variation, for example:
501
502 .. code-block:: c
503
504 int i;
505 char out[40];
506
507 struct sha1_test_case {
508 const char *str;
509 const char *sha1;
510 };
511
512 struct sha1_test_case cases[] = {
513 {
514 .str = "hello world",
515 .sha1 = "2aae6c35c94fc
516 },
517 {
518 .str = "hello world!",
519 .sha1 = "430ce34d02072
520 },
521 };
522 for (i = 0; i < ARRAY_SIZE(cases); ++i
523 sha1sum(cases[i].str, out);
524 KUNIT_EXPECT_STREQ_MSG(test, o
525 "sha1sum
526 }
527
528
529 There is more boilerplate code involved, but i
530
531 * be more readable when there are multiple inp
532
533 * For example, see ``fs/ext4/inode-test.c``.
534
535 * reduce duplication if test cases are shared
536
537 * For example: if we want to test ``sha256su
538 field and reuse ``cases``.
539
540 * be converted to a "parameterized test".
541
542 Parameterized Testing
543 ~~~~~~~~~~~~~~~~~~~~~
544
545 The table-driven testing pattern is common eno
546 support for it.
547
548 By reusing the same ``cases`` array from above
549 "parameterized test" with the following.
550
551 .. code-block:: c
552
553 // This is copy-pasted from above.
554 struct sha1_test_case {
555 const char *str;
556 const char *sha1;
557 };
558 const struct sha1_test_case cases[] =
559 {
560 .str = "hello world",
561 .sha1 = "2aae6c35c94fc
562 },
563 {
564 .str = "hello world!",
565 .sha1 = "430ce34d02072
566 },
567 };
568
569 // Creates `sha1_gen_params()` to iter
570 // the struct member `str` for the cas
571 KUNIT_ARRAY_PARAM_DESC(sha1, cases, st
572
573 // Looks no different from a normal te
574 static void sha1_test(struct kunit *te
575 {
576 // This function can just cont
577 // The former `cases[i]` is ac
578 char out[40];
579 struct sha1_test_case *test_pa
580
581 sha1sum(test_param->str, out);
582 KUNIT_EXPECT_STREQ_MSG(test, o
583 "sha1sum
584 }
585
586 // Instead of KUNIT_CASE, we use KUNIT
587 // function declared by KUNIT_ARRAY_PA
588 static struct kunit_case sha1_test_cas
589 KUNIT_CASE_PARAM(sha1_test, sh
590 {}
591 };
592
593 Allocating Memory
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
683 /* In my_file.h */
684
685 #if IS_ENABLED(CONFIG_KUNIT)
686 int do_interesting_thing(void)
687 #endif
688
689 Alternatively, you could conditionally ``#incl
690 your .c file. For example:
691
692 .. code-block:: c
693
694 /* In my_file.c */
695
696 static int do_interesting_thing();
697
698 #ifdef CONFIG_MY_KUNIT_TEST
699 #include "my_kunit_test.c"
700 #endif
701
702 Injecting Test-Only Code
703 ------------------------
704
705 Similar to as shown above, we can add test-spe
706
707 .. code-block:: c
708
709 /* In my_file.h */
710
711 #ifdef CONFIG_MY_KUNIT_TEST
712 /* Defined in my_kunit_test.c */
713 void test_only_hook(void);
714 #else
715 void test_only_hook(void) { }
716 #endif
717
718 This test-only code can be made more useful by
719 as shown in next section: *Accessing The Curre
720
721 Accessing The Current Test
722 --------------------------
723
724 In some cases, we need to call test-only code
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
730 ``kunit_get_current_test()`` is safe to call e
731 KUnit is not enabled, or if no test is running
732 return ``NULL``. This compiles down to either
733 so will have a negligible performance impact w
734
735 The example below uses this to implement a "mo
736
737 .. code-block:: c
738
739 #include <kunit/test-bug.h> /* for kun
740
741 struct test_data {
742 int foo_result;
743 int want_foo_called_with;
744 };
745
746 static int fake_foo(int arg)
747 {
748 struct kunit *test = kunit_get
749 struct test_data *test_data =
750
751 KUNIT_EXPECT_EQ(test, test_dat
752 return test_data->foo_result;
753 }
754
755 static void example_simple_test(struct
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
764 /* In a real test, we'd probab
765 * like an ops struct, etc. in
766 KUNIT_EXPECT_EQ(test, fake_foo
767 }
768
769 In this example, we are using the ``priv`` mem
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
774 Had we wanted something more flexible, we coul
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
781 Failing The Current Test
782 ------------------------
783
784 If we want to fail the current test, we can us
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
789 .. code-block:: c
790
791 #include <kunit/test-bug.h>
792
793 #ifdef CONFIG_EXTRA_DEBUG_CHECKS
794 static void validate_my_data(struct da
795 {
796 if (is_valid(data))
797 return;
798
799 kunit_fail_current_test("data
800
801 /* Normal, non-KUnit, error re
802 }
803 #else
804 static void my_debug_function(void) {
805 #endif
806
807 ``kunit_fail_current_test()`` is safe to call
808 KUnit is not enabled, or if no test is running
809 nothing. This compiles down to either a no-op
810 have a negligible performance impact when no t
811
812 Managing Fake Devices and Drivers
813 ---------------------------------
814
815 When testing drivers or code which interacts w
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
820 KUnit provides helper functions to create and
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
825 To create a KUnit-managed ``struct device_driv
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
830 To create a fake device, use the ``kunit_devic
831 and register a device, using a new KUnit-manag
832 To provide a specific, non-KUnit-managed drive
833 instead. Like with managed drivers, KUnit-mana
834 cleaned up when the test finishes, but can be
835 ``kunit_device_unregister()``.
836
837 The KUnit devices should be used in preference
838 instead of ``platform_device_register()`` in c
839 a platform device.
840
841 For example:
842
843 .. code-block:: c
844
845 #include <kunit/device.h>
846
847 static void test_my_device(struct kuni
848 {
849 struct device *fake_device;
850 const char *dev_managed_string
851
852 // Create a fake device.
853 fake_device = kunit_device_reg
854 KUNIT_ASSERT_NOT_ERR_OR_NULL(t
855
856 // Pass it to functions which
857 dev_managed_string = devm_kstr
858
859 // Everything is cleaned up au
860 }
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.