Merge tag 'io_uring-5.14-2021-08-13' of git://git.kernel.dk/linux-block
[linux-2.6-microblaze.git] / Documentation / dev-tools / kunit / usage.rst
1 .. SPDX-License-Identifier: GPL-2.0
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
47 Writing Tests
48 -------------
49
50 Test Cases
51 ~~~~~~~~~~
52
53 The fundamental unit in KUnit is the test case. A test case is a function with
54 the signature ``void (*)(struct kunit *test)``. It calls a function to be tested
55 and then sets *expectations* for what should happen. For example:
56
57 .. code-block:: c
58
59         void example_test_success(struct kunit *test)
60         {
61         }
62
63         void example_test_failure(struct kunit *test)
64         {
65                 KUNIT_FAIL(test, "This test never passes.");
66         }
67
68 In the above example ``example_test_success`` always passes because it does
69 nothing; no expectations are set, so all expectations pass. On the other hand
70 ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, which is
71 a special expectation that logs a message and causes the test case to fail.
72
73 Expectations
74 ~~~~~~~~~~~~
75 An *expectation* is a way to specify that you expect a piece of code to do
76 something in a test. An expectation is called like a function. A test is made
77 by setting expectations about the behavior of a piece of code under test; when
78 one or more of the expectations fail, the test case fails and information about
79 the failure is logged. For example:
80
81 .. code-block:: c
82
83         void add_test_basic(struct kunit *test)
84         {
85                 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
86                 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
87         }
88
89 In the above example ``add_test_basic`` makes a number of assertions about the
90 behavior of a function called ``add``; the first parameter is always of type
91 ``struct kunit *``, which contains information about the current test context;
92 the second parameter, in this case, is what the value is expected to be; the
93 last value is what the value actually is. If ``add`` passes all of these
94 expectations, the test case, ``add_test_basic`` will pass; if any one of these
95 expectations fails, the test case will fail.
96
97 It is important to understand that a test case *fails* when any expectation is
98 violated; however, the test will continue running, potentially trying other
99 expectations until the test case ends or is otherwise terminated. This is as
100 opposed to *assertions* which are discussed later.
101
102 To learn about more expectations supported by KUnit, see
103 Documentation/dev-tools/kunit/api/test.rst.
104
105 .. note::
106    A single test case should be pretty short, pretty easy to understand,
107    focused on a single behavior.
108
109 For example, if we wanted to properly test the add function above, we would
110 create additional tests cases which would each test a different property that an
111 add function should have like this:
112
113 .. code-block:: c
114
115         void add_test_basic(struct kunit *test)
116         {
117                 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
118                 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
119         }
120
121         void add_test_negative(struct kunit *test)
122         {
123                 KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
124         }
125
126         void add_test_max(struct kunit *test)
127         {
128                 KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
129                 KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
130         }
131
132         void add_test_overflow(struct kunit *test)
133         {
134                 KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
135         }
136
137 Notice how it is immediately obvious what all the properties that we are testing
138 for are.
139
140 Assertions
141 ~~~~~~~~~~
142
143 KUnit also has the concept of an *assertion*. An assertion is just like an
144 expectation except the assertion immediately terminates the test case if it is
145 not satisfied.
146
147 For example:
148
149 .. code-block:: c
150
151         static void mock_test_do_expect_default_return(struct kunit *test)
152         {
153                 struct mock_test_context *ctx = test->priv;
154                 struct mock *mock = ctx->mock;
155                 int param0 = 5, param1 = -5;
156                 const char *two_param_types[] = {"int", "int"};
157                 const void *two_params[] = {&param0, &param1};
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.
173
174 Test Suites
175 ~~~~~~~~~~~
176
177 Now obviously one unit test isn't very helpful; the power comes from having
178 many test cases covering all of a unit's behaviors. Consequently it is common
179 to have many *similar* tests; in order to reduce duplication in these closely
180 related tests most unit testing frameworks - including KUnit - provide the
181 concept of a *test suite*. A *test suite* is just a collection of test cases
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.
185
186 Example:
187
188 .. code-block:: c
189
190         static struct kunit_case example_test_cases[] = {
191                 KUNIT_CASE(example_test_foo),
192                 KUNIT_CASE(example_test_bar),
193                 KUNIT_CASE(example_test_baz),
194                 {}
195         };
196
197         static struct kunit_suite example_test_suite = {
198                 .name = "example",
199                 .init = example_test_init,
200                 .exit = example_test_exit,
201                 .test_cases = example_test_cases,
202         };
203         kunit_test_suite(example_test_suite);
204
205 In the above example the test suite, ``example_test_suite``, would run the test
206 cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``;
207 each would have ``example_test_init`` called immediately before it and would
208 have ``example_test_exit`` called immediately after it.
209 ``kunit_test_suite(example_test_suite)`` registers the test suite with the
210 KUnit test framework.
211
212 .. note::
213    A test case will only be run if it is associated with a test suite.
214
215 ``kunit_test_suite(...)`` is a macro which tells the linker to put the specified
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).
219
220 For more information on these types of things see the
221 Documentation/dev-tools/kunit/api/test.rst.
222
223 Common Patterns
224 ===============
225
226 Isolating Behavior
227 ------------------
228
229 The most important aspect of unit testing that other forms of testing do not
230 provide is the ability to limit the amount of code under test to a single unit.
231 In practice, this is only possible by being able to control what code gets run
232 when the unit under test calls a function and this is usually accomplished
233 through some sort of indirection where a function is exposed as part of an API
234 such that the definition of that function can be changed without affecting the
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.
239
240 Classes
241 ~~~~~~~
242
243 Classes are not a construct that is built into the C programming language;
244 however, it is an easily derived concept. Accordingly, pretty much every project
245 that does not use a standardized object oriented library (like GNOME's GObject)
246 has their own slightly different way of doing object oriented programming; the
247 Linux kernel is no exception.
248
249 The central concept in kernel object oriented programming is the class. In the
250 kernel, a *class* is a struct that contains function pointers. This creates a
251 contract between *implementers* and *users* since it forces them to use the
252 same function signature without having to call the function directly. In order
253 for it to truly be a class, the function pointers must specify that a pointer
254 to the class, known as a *class handle*, be one of the parameters; this makes
255 it possible for the member functions (also known as *methods*) to have access
256 to member variables (more commonly known as *fields*) allowing the same
257 implementation to have multiple *instances*.
258
259 Typically a class can be *overridden* by *child classes* by embedding the
260 *parent class* in the child class. Then when a method provided by the child
261 class is called, the child implementation knows that the pointer passed to it is
262 of a parent contained within the child; because of this, the child can compute
263 the pointer to itself because the pointer to the parent is always a fixed offset
264 from the pointer to the child; this offset is the offset of the parent contained
265 in the child struct. For example:
266
267 .. code-block:: c
268
269         struct shape {
270                 int (*area)(struct shape *this);
271         };
272
273         struct rectangle {
274                 struct shape parent;
275                 int length;
276                 int width;
277         };
278
279         int rectangle_area(struct shape *this)
280         {
281                 struct rectangle *self = container_of(this, struct shape, parent);
282
283                 return self->length * self->width;
284         };
285
286         void rectangle_new(struct rectangle *self, int length, int width)
287         {
288                 self->parent.area = rectangle_area;
289                 self->length = length;
290                 self->width = width;
291         }
292
293 In this example (as in most kernel code) the operation of computing the pointer
294 to the child from the pointer to the parent is done by ``container_of``.
295
296 Faking Classes
297 ~~~~~~~~~~~~~~
298
299 In order to unit test a piece of code that calls a method in a class, the
300 behavior of the method must be controllable, otherwise the test ceases to be a
301 unit test and becomes an integration test.
302
303 A fake just provides an implementation of a piece of code that is different than
304 what runs in a production instance, but behaves identically from the standpoint
305 of the callers; this is usually done to replace a dependency that is hard to
306 deal with, or is slow.
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:
311
312 .. code-block:: c
313
314         struct eeprom {
315                 ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
316                 ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
317         };
318
319 And we want to test some code that buffers writes to the EEPROM:
320
321 .. code-block:: c
322
323         struct eeprom_buffer {
324                 ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
325                 int flush(struct eeprom_buffer *this);
326                 size_t flush_count; /* Flushes when buffer exceeds flush_count. */
327         };
328
329         struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
330         void destroy_eeprom_buffer(struct eeprom *eeprom);
331
332 We can easily test this code by *faking out* the underlying EEPROM:
333
334 .. code-block:: c
335
336         struct fake_eeprom {
337                 struct eeprom parent;
338                 char contents[FAKE_EEPROM_CONTENTS_SIZE];
339         };
340
341         ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
342         {
343                 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
344
345                 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
346                 memcpy(buffer, this->contents + offset, count);
347
348                 return count;
349         }
350
351         ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
352         {
353                 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
354
355                 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
356                 memcpy(this->contents + offset, buffer, count);
357
358                 return count;
359         }
360
361         void fake_eeprom_init(struct fake_eeprom *this)
362         {
363                 this->parent.read = fake_eeprom_read;
364                 this->parent.write = fake_eeprom_write;
365                 memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
366         }
367
368 We can now use it to test ``struct eeprom_buffer``:
369
370 .. code-block:: c
371
372         struct eeprom_buffer_test {
373                 struct fake_eeprom *fake_eeprom;
374                 struct eeprom_buffer *eeprom_buffer;
375         };
376
377         static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
378         {
379                 struct eeprom_buffer_test *ctx = test->priv;
380                 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
381                 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
382                 char buffer[] = {0xff};
383
384                 eeprom_buffer->flush_count = SIZE_MAX;
385
386                 eeprom_buffer->write(eeprom_buffer, buffer, 1);
387                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
388
389                 eeprom_buffer->write(eeprom_buffer, buffer, 1);
390                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
391
392                 eeprom_buffer->flush(eeprom_buffer);
393                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
394                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
395         }
396
397         static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
398         {
399                 struct eeprom_buffer_test *ctx = test->priv;
400                 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
401                 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
402                 char buffer[] = {0xff};
403
404                 eeprom_buffer->flush_count = 2;
405
406                 eeprom_buffer->write(eeprom_buffer, buffer, 1);
407                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
408
409                 eeprom_buffer->write(eeprom_buffer, buffer, 1);
410                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
411                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
412         }
413
414         static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
415         {
416                 struct eeprom_buffer_test *ctx = test->priv;
417                 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
418                 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
419                 char buffer[] = {0xff, 0xff};
420
421                 eeprom_buffer->flush_count = 2;
422
423                 eeprom_buffer->write(eeprom_buffer, buffer, 1);
424                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
425
426                 eeprom_buffer->write(eeprom_buffer, buffer, 2);
427                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
428                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
429                 /* Should have only flushed the first two bytes. */
430                 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
431         }
432
433         static int eeprom_buffer_test_init(struct kunit *test)
434         {
435                 struct eeprom_buffer_test *ctx;
436
437                 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
438                 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
439
440                 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
441                 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
442                 fake_eeprom_init(ctx->fake_eeprom);
443
444                 ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
445                 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
446
447                 test->priv = ctx;
448
449                 return 0;
450         }
451
452         static void eeprom_buffer_test_exit(struct kunit *test)
453         {
454                 struct eeprom_buffer_test *ctx = test->priv;
455
456                 destroy_eeprom_buffer(ctx->eeprom_buffer);
457         }
458
459 Testing against multiple inputs
460 -------------------------------
461
462 Testing just a few inputs might not be enough to have confidence that the code
463 works correctly, e.g. for a hash function.
464
465 In such cases, it can be helpful to have a helper macro or function, e.g. this
466 fictitious example for ``sha1sum(1)``
467
468 .. code-block:: c
469
470         #define TEST_SHA1(in, want) \
471                 sha1sum(in, out); \
472                 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
473
474         char out[40];
475         TEST_SHA1("hello world",  "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
476         TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");
477
478
479 Note the use of ``KUNIT_EXPECT_STREQ_MSG`` to give more context when it fails
480 and make it easier to track down. (Yes, in this example, ``want`` is likely
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.
486
487 In some cases, it can be helpful to write a *table-driven test* instead, e.g.
488
489 .. code-block:: c
490
491         int i;
492         char out[40];
493
494         struct sha1_test_case {
495                 const char *str;
496                 const char *sha1;
497         };
498
499         struct sha1_test_case cases[] = {
500                 {
501                         .str = "hello world",
502                         .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
503                 },
504                 {
505                         .str = "hello world!",
506                         .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
507                 },
508         };
509         for (i = 0; i < ARRAY_SIZE(cases); ++i) {
510                 sha1sum(cases[i].str, out);
511                 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
512                                       "sha1sum(%s)", cases[i].str);
513         }
514
515
516 There's more boilerplate involved, but it can:
517
518 * be more readable when there are multiple inputs/outputs thanks to field names,
519
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.
522
523   * E.g. if we wanted to also test ``sha256sum``, we could add a ``sha256``
524     field and reuse ``cases``.
525
526 * be converted to a "parameterized test", see below.
527
528 Parameterized Testing
529 ~~~~~~~~~~~~~~~~~~~~~
530
531 The table-driven testing pattern is common enough that KUnit has special
532 support for it.
533
534 Reusing the same ``cases`` array from above, we can write the test as a
535 "parameterized test" with the following.
536
537 .. code-block:: c
538
539         // This is copy-pasted from above.
540         struct sha1_test_case {
541                 const char *str;
542                 const char *sha1;
543         };
544         struct sha1_test_case cases[] = {
545                 {
546                         .str = "hello world",
547                         .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
548                 },
549                 {
550                         .str = "hello world!",
551                         .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
552                 },
553         };
554
555         // Need a helper function to generate a name for each test case.
556         static void case_to_desc(const struct sha1_test_case *t, char *desc)
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);
562
563         // Looks no different from a normal test.
564         static void sha1_test(struct kunit *test)
565         {
566                 // This function can just contain the body of the for-loop.
567                 // The former `cases[i]` is accessible under test->param_value.
568                 char out[40];
569                 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
570
571                 sha1sum(test_param->str, out);
572                 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
573                                       "sha1sum(%s)", test_param->str);
574         }
575
576         // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
577         // function declared by KUNIT_ARRAY_PARAM.
578         static struct kunit_case sha1_test_cases[] = {
579                 KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
580                 {}
581         };
582
583 .. _kunit-on-non-uml:
584
585 KUnit on non-UML architectures
586 ==============================
587
588 By default KUnit uses UML as a way to provide dependencies for code under test.
589 Under most circumstances KUnit's usage of UML should be treated as an
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.
594
595 Running existing KUnit tests on non-UML architectures
596 -----------------------------------------------------
597
598 There are some special considerations when running existing KUnit tests on
599 non-UML architectures:
600
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.
609
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.
612
613 Currently, the KUnit Wrapper (``tools/testing/kunit/kunit.py``) (aka
614 kunit_tool) only fully supports running tests inside of UML and QEMU; however,
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.
622
623 Again, all core KUnit framework features are fully supported on all
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:
627
628 *   i386
629 *   x86_64
630 *   arm
631 *   arm64
632 *   alpha
633 *   powerpc
634 *   riscv
635 *   s390
636 *   sparc
637
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):
643
644 .. code-block:: bash
645
646         tools/testing/kunit/kunit.py run --timeout=60 --jobs=12 --arch=arm --cross_compile=arm-linux-gnueabihf-
647
648 Alternatively, if you want to run your tests on real hardware or in some other
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!
652
653 For example, let's say you have the following kunitconfig:
654
655 .. code-block:: none
656
657         CONFIG_KUNIT=y
658         CONFIG_KUNIT_EXAMPLE_TEST=y
659
660 If you wanted to run this test on an x86 VM, you might add the following config
661 options to your ``.config``:
662
663 .. code-block:: none
664
665         CONFIG_KUNIT=y
666         CONFIG_KUNIT_EXAMPLE_TEST=y
667         CONFIG_SERIAL_8250=y
668         CONFIG_SERIAL_8250_CONSOLE=y
669
670 All these new options do is enable support for a common serial console needed
671 for logging.
672
673 Next, you could build a kernel with these tests as follows:
674
675
676 .. code-block:: bash
677
678         make ARCH=x86 olddefconfig
679         make ARCH=x86
680
681 Once you have built a kernel, you could run it on QEMU as follows:
682
683 .. code-block:: bash
684
685         qemu-system-x86_64 -enable-kvm \
686                            -m 1024 \
687                            -kernel arch/x86_64/boot/bzImage \
688                            -append 'console=ttyS0' \
689                            --nographic
690
691 Interspersed in the kernel logs you might see the following:
692
693 .. code-block:: none
694
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
701
702 Congratulations, you just ran a KUnit test on the x86 architecture!
703
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``:
707
708 .. code-block:: none
709
710         CONFIG_KUNIT=m
711         CONFIG_KUNIT_EXAMPLE_TEST=m
712
713 Once the kernel is built and installed, a simple
714
715 .. code-block:: bash
716
717         modprobe example-test
718
719 ...will run the tests.
720
721 .. note::
722    Note that you should make sure your test depends on ``KUNIT=y`` in Kconfig
723    if the test does not support module build.  Otherwise, it will trigger
724    compile errors if ``CONFIG_KUNIT`` is ``m``.
725
726 Writing new tests for other architectures
727 -----------------------------------------
728
729 The first thing you must do is ask yourself whether it is necessary to write a
730 KUnit test for a specific architecture, and then whether it is necessary to
731 write that test for a particular piece of hardware. In general, writing a test
732 that depends on having access to a particular piece of hardware or software (not
733 included in the Linux source repo) should be avoided at all costs.
734
735 Even if you only ever plan on running your KUnit test on your hardware
736 configuration, other people may want to run your tests and may not have access
737 to your hardware. If you write your test to run on UML, then anyone can run your
738 tests without knowing anything about your particular setup, and you can still
739 run your tests on your hardware setup just by compiling for your architecture.
740
741 .. important::
742    Always prefer tests that run on UML to tests that only run under a particular
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.
758
759 .. TODO(brendanhiggins@google.com): Add an actual example of an architecture-
760    dependent KUnit test.
761
762 KUnit debugfs representation
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``).