860 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Writing Tests4=============5 6Test Cases7----------8 9The fundamental unit in KUnit is the test case. A test case is a function with10the signature ``void (*)(struct kunit *test)``. It calls the function under test11and then sets *expectations* for what should happen. For example:12 13.. code-block:: c14 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 does25nothing; no expectations are set, and therefore all expectations pass. On the26other 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 to28fail.29 30Expectations31~~~~~~~~~~~~32An *expectation* specifies that we expect a piece of code to do something in a33test. An expectation is called like a function. A test is made by setting34expectations about the behavior of a piece of code under test. When one or more35expectations fail, the test case fails and information about the failure is36logged. For example:37 38.. code-block:: c39 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 the47behavior of a function called ``add``. The first parameter is always of type48``struct kunit *``, which contains information about the current test context.49The second parameter, in this case, is what the value is expected to be. The50last value is what the value actually is. If ``add`` passes all of these51expectations, the test case, ``add_test_basic`` will pass; if any one of these52expectations fails, the test case will fail.53 54A test case *fails* when any expectation is violated; however, the test will55continue to run, and try other expectations until the test case ends or is56otherwise terminated. This is as opposed to *assertions* which are discussed57later.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 a63 single behavior.64 65For example, if we want to rigorously test the ``add`` function above, create66additional tests cases which would test each property that an ``add`` function67should have as shown below:68 69.. code-block:: c70 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 93Assertions94~~~~~~~~~~95 96An assertion is like an expectation, except that the assertion immediately97terminates the test case if the condition is not satisfied. For example:98 99.. code-block:: c100 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 if117there's an allocation error.118 119.. note::120 In other test frameworks, ``ASSERT`` macros are often implemented by calling121 ``return`` so they only work from the test function. In KUnit, we stop the122 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 assertions126 in the suite's exit() function, or in the free function for a resource. These127 run when a test is shutting down, and an assertion here prevents further128 cleanup code from running, potentially leading to a memory leak.129 130Customizing error messages131--------------------------132 133Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG``134variant. These take a format string and arguments to provide additional135context to the automatically generated error messages.136 137.. code-block:: c138 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 using149``KUNIT_FAIL()``, e.g.150 151.. code-block:: c152 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 160 161Test Suites162~~~~~~~~~~~163 164We need many test cases covering all the unit's behaviors. It is common to have165many similar tests. In order to reduce duplication in these closely related166tests, most unit testing frameworks (including KUnit) provide the concept of a167*test suite*. A test suite is a collection of test cases for a unit of code168with optional setup and teardown functions that run before/after the whole169suite and/or every test case.170 171.. note::172 A test case will only run if it is associated with a test suite.173 174For example:175 176.. code-block:: c177 178 static struct kunit_case example_test_cases[] = {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_suite = {186 .name = "example",187 .init = example_test_init,188 .exit = example_test_exit,189 .suite_init = example_suite_init,190 .suite_exit = example_suite_exit,191 .test_cases = example_test_cases,192 };193 kunit_test_suite(example_test_suite);194 195In the above example, the test suite ``example_test_suite`` would first run196``example_suite_init``, then run the test cases ``example_test_foo``,197``example_test_bar``, and ``example_test_baz``. Each would have198``example_test_init`` called immediately before it and ``example_test_exit``199called immediately after it. Finally, ``example_suite_exit`` would be called200after everything else. ``kunit_test_suite(example_test_suite)`` registers the201test suite with the KUnit test framework.202 203.. note::204 The ``exit`` and ``suite_exit`` functions will run even if ``init`` or205 ``suite_init`` fail. Make sure that they can handle any inconsistent206 state which may result from ``init`` or ``suite_init`` encountering errors207 or exiting early.208 209``kunit_test_suite(...)`` is a macro which tells the linker to put the210specified test suite in a special linker section so that it can be run by KUnit211either after ``late_init``, or when the test module is loaded (if the test was212built as a module).213 214For more information, see Documentation/dev-tools/kunit/api/test.rst.215 216.. _kunit-on-non-uml:217 218Writing Tests For Other Architectures219-------------------------------------220 221It is better to write tests that run on UML to tests that only run under a222particular architecture. It is better to write tests that run under QEMU or223another easy to obtain (and monetarily free) software environment to a specific224piece of hardware.225 226Nevertheless, there are still valid reasons to write a test that is architecture227or hardware specific. For example, we might want to test code that really228belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does229not depend on physical hardware. Some of our test cases may not need hardware,230only few tests actually require the hardware to test it. When hardware is not231available, instead of disabling tests, we can skip them.232 233Now that we have narrowed down exactly what bits are hardware specific, the234actual procedure for writing and running the tests is same as writing normal235KUnit tests.236 237.. important::238 We may have to reset hardware state. If this is not possible, we may only239 be able to run one test case per invocation.240 241.. TODO(brendanhiggins@google.com): Add an actual example of an architecture-242 dependent KUnit test.243 244Common Patterns245===============246 247Isolating Behavior248------------------249 250Unit testing limits the amount of code under test to a single unit. It controls251what code gets run when the unit under test calls a function. Where a function252is exposed as part of an API such that the definition of that function can be253changed without affecting the rest of the code base. In the kernel, this comes254from two constructs: classes, which are structs that contain function pointers255provided by the implementer, and architecture-specific functions, which have256definitions selected at compile time.257 258Classes259~~~~~~~260 261Classes are not a construct that is built into the C programming language;262however, it is an easily derived concept. Accordingly, in most cases, every263project that does not use a standardized object oriented library (like GNOME's264GObject) has their own slightly different way of doing object oriented265programming; the Linux kernel is no exception.266 267The central concept in kernel object oriented programming is the class. In the268kernel, a *class* is a struct that contains function pointers. This creates a269contract between *implementers* and *users* since it forces them to use the270same function signature without having to call the function directly. To be a271class, the function pointers must specify that a pointer to the class, known as272a *class handle*, be one of the parameters. Thus the member functions (also273known as *methods*) have access to member variables (also known as *fields*)274allowing the same implementation to have multiple *instances*.275 276A class can be *overridden* by *child classes* by embedding the *parent class*277in the child class. Then when the child class *method* is called, the child278implementation knows that the pointer passed to it is of a parent contained279within the child. Thus, the child can compute the pointer to itself because the280pointer to the parent is always a fixed offset from the pointer to the child.281This offset is the offset of the parent contained in the child struct. For282example:283 284.. code-block:: c285 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 = container_of(this, struct rectangle, parent);299 300 return self->length * self->width;301 };302 303 void rectangle_new(struct rectangle *self, int length, int width)304 {305 self->parent.area = rectangle_area;306 self->length = length;307 self->width = width;308 }309 310In this example, computing the pointer to the child from the pointer to the311parent is done by ``container_of``.312 313Faking Classes314~~~~~~~~~~~~~~315 316In order to unit test a piece of code that calls a method in a class, the317behavior of the method must be controllable, otherwise the test ceases to be a318unit test and becomes an integration test.319 320A fake class implements a piece of code that is different than what runs in a321production instance, but behaves identical from the standpoint of the callers.322This is done to replace a dependency that is hard to deal with, or is slow. For323example, implementing a fake EEPROM that stores the "contents" in an324internal buffer. Assume we have a class that represents an EEPROM:325 326.. code-block:: c327 328 struct eeprom {329 ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);330 ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);331 };332 333And we want to test code that buffers writes to the EEPROM:334 335.. code-block:: c336 337 struct eeprom_buffer {338 ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);339 int flush(struct eeprom_buffer *this);340 size_t flush_count; /* Flushes when buffer exceeds flush_count. */341 };342 343 struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);344 void destroy_eeprom_buffer(struct eeprom *eeprom);345 346We can test this code by *faking out* the underlying EEPROM:347 348.. code-block:: c349 350 struct fake_eeprom {351 struct eeprom parent;352 char contents[FAKE_EEPROM_CONTENTS_SIZE];353 };354 355 ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)356 {357 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);358 359 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);360 memcpy(buffer, this->contents + offset, count);361 362 return count;363 }364 365 ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)366 {367 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);368 369 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);370 memcpy(this->contents + offset, buffer, count);371 372 return count;373 }374 375 void fake_eeprom_init(struct fake_eeprom *this)376 {377 this->parent.read = fake_eeprom_read;378 this->parent.write = fake_eeprom_write;379 memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);380 }381 382We can now use it to test ``struct eeprom_buffer``:383 384.. code-block:: c385 386 struct eeprom_buffer_test {387 struct fake_eeprom *fake_eeprom;388 struct eeprom_buffer *eeprom_buffer;389 };390 391 static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)392 {393 struct eeprom_buffer_test *ctx = test->priv;394 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;395 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;396 char buffer[] = {0xff};397 398 eeprom_buffer->flush_count = SIZE_MAX;399 400 eeprom_buffer->write(eeprom_buffer, buffer, 1);401 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);402 403 eeprom_buffer->write(eeprom_buffer, buffer, 1);404 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);405 406 eeprom_buffer->flush(eeprom_buffer);407 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);408 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);409 }410 411 static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)412 {413 struct eeprom_buffer_test *ctx = test->priv;414 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;415 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;416 char buffer[] = {0xff};417 418 eeprom_buffer->flush_count = 2;419 420 eeprom_buffer->write(eeprom_buffer, buffer, 1);421 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);422 423 eeprom_buffer->write(eeprom_buffer, buffer, 1);424 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);425 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);426 }427 428 static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)429 {430 struct eeprom_buffer_test *ctx = test->priv;431 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;432 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;433 char buffer[] = {0xff, 0xff};434 435 eeprom_buffer->flush_count = 2;436 437 eeprom_buffer->write(eeprom_buffer, buffer, 1);438 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);439 440 eeprom_buffer->write(eeprom_buffer, buffer, 2);441 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);442 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);443 /* Should have only flushed the first two bytes. */444 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);445 }446 447 static int eeprom_buffer_test_init(struct kunit *test)448 {449 struct eeprom_buffer_test *ctx;450 451 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);452 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);453 454 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);455 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);456 fake_eeprom_init(ctx->fake_eeprom);457 458 ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);459 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);460 461 test->priv = ctx;462 463 return 0;464 }465 466 static void eeprom_buffer_test_exit(struct kunit *test)467 {468 struct eeprom_buffer_test *ctx = test->priv;469 470 destroy_eeprom_buffer(ctx->eeprom_buffer);471 }472 473Testing Against Multiple Inputs474-------------------------------475 476Testing just a few inputs is not enough to ensure that the code works correctly,477for example: testing a hash function.478 479We can write a helper macro or function. The function is called for each input.480For example, to test ``sha1sum(1)``, we can write:481 482.. code-block:: c483 484 #define TEST_SHA1(in, want) \485 sha1sum(in, out); \486 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);487 488 char out[40];489 TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");490 TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");491 492Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more493detailed error and make the assertions clearer within the helper macros.494 495The ``_MSG`` variants are useful when the same expectation is called multiple496times (in a loop or helper function) and thus the line number is not enough to497identify what failed, as shown below.498 499In complicated cases, we recommend using a *table-driven test* compared to the500helper macro variation, for example:501 502.. code-block:: c503 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 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",516 },517 {518 .str = "hello world!",519 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",520 },521 };522 for (i = 0; i < ARRAY_SIZE(cases); ++i) {523 sha1sum(cases[i].str, out);524 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,525 "sha1sum(%s)", cases[i].str);526 }527 528 529There is more boilerplate code involved, but it can:530 531* be more readable when there are multiple inputs/outputs (due to field names).532 533 * For example, see ``fs/ext4/inode-test.c``.534 535* reduce duplication if test cases are shared across multiple tests.536 537 * For example: if we want to test ``sha256sum``, we could add a ``sha256``538 field and reuse ``cases``.539 540* be converted to a "parameterized test".541 542Parameterized Testing543~~~~~~~~~~~~~~~~~~~~~544 545The table-driven testing pattern is common enough that KUnit has special546support for it.547 548By reusing the same ``cases`` array from above, we can write the test as a549"parameterized test" with the following.550 551.. code-block:: c552 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 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",562 },563 {564 .str = "hello world!",565 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",566 },567 };568 569 // Creates `sha1_gen_params()` to iterate over `cases` while using570 // the struct member `str` for the case description.571 KUNIT_ARRAY_PARAM_DESC(sha1, cases, str);572 573 // Looks no different from a normal test.574 static void sha1_test(struct kunit *test)575 {576 // This function can just contain the body of the for-loop.577 // The former `cases[i]` is accessible under test->param_value.578 char out[40];579 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);580 581 sha1sum(test_param->str, out);582 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,583 "sha1sum(%s)", test_param->str);584 }585 586 // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the587 // function declared by KUNIT_ARRAY_PARAM or KUNIT_ARRAY_PARAM_DESC.588 static struct kunit_case sha1_test_cases[] = {589 KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),590 {}591 };592 593Allocating Memory594-----------------595 596Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit597will then ensure that the memory is freed once the test completes.598 599This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit600early from a test without having to worry about remembering to call ``kfree``.601For example:602 603.. code-block:: c604 605 void example_test_allocation(struct kunit *test)606 {607 char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);608 /* Ensure allocation succeeded. */609 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);610 611 KUNIT_ASSERT_STREQ(test, buffer, "");612 }613 614Registering Cleanup Actions615---------------------------616 617If you need to perform some cleanup beyond simple use of ``kunit_kzalloc``,618you can register a custom "deferred action", which is a cleanup function619run when the test exits (whether cleanly, or via a failed assertion).620 621Actions are simple functions with no return value, and a single ``void*``622context argument, and fulfill the same role as "cleanup" functions in Python623and Go tests, "defer" statements in languages which support them, and624(in some cases) destructors in RAII languages.625 626These are very useful for unregistering things from global lists, closing627files or other resources, or freeing resources.628 629For example:630 631.. code-block:: C632 633 static void cleanup_device(void *ctx)634 {635 struct device *dev = (struct device *)ctx;636 637 device_unregister(dev);638 }639 640 void example_device_test(struct kunit *test)641 {642 struct my_device dev;643 644 device_register(&dev);645 646 kunit_add_action(test, &cleanup_device, &dev);647 }648 649Note that, for functions like device_unregister which only accept a single650pointer-sized argument, it's possible to automatically generate a wrapper651with the ``KUNIT_DEFINE_ACTION_WRAPPER()`` macro, for example:652 653.. code-block:: C654 655 KUNIT_DEFINE_ACTION_WRAPPER(device_unregister, device_unregister_wrapper, struct device *);656 kunit_add_action(test, &device_unregister_wrapper, &dev);657 658You should do this in preference to manually casting to the ``kunit_action_t`` type,659as casting function pointers will break Control Flow Integrity (CFI).660 661``kunit_add_action`` can fail if, for example, the system is out of memory.662You can use ``kunit_add_action_or_reset`` instead which runs the action663immediately if it cannot be deferred.664 665If you need more control over when the cleanup function is called, you666can trigger it early using ``kunit_release_action``, or cancel it entirely667with ``kunit_remove_action``.668 669 670Testing Static Functions671------------------------672 673If we do not want to expose functions or variables for testing, one option is to674conditionally export the used symbol. For example:675 676.. code-block:: c677 678 /* In my_file.c */679 680 VISIBLE_IF_KUNIT int do_interesting_thing();681 EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);682 683 /* In my_file.h */684 685 #if IS_ENABLED(CONFIG_KUNIT)686 int do_interesting_thing(void);687 #endif688 689Alternatively, you could conditionally ``#include`` the test file at the end of690your .c file. For example:691 692.. code-block:: c693 694 /* In my_file.c */695 696 static int do_interesting_thing();697 698 #ifdef CONFIG_MY_KUNIT_TEST699 #include "my_kunit_test.c"700 #endif701 702Injecting Test-Only Code703------------------------704 705Similar to as shown above, we can add test-specific logic. For example:706 707.. code-block:: c708 709 /* In my_file.h */710 711 #ifdef CONFIG_MY_KUNIT_TEST712 /* Defined in my_kunit_test.c */713 void test_only_hook(void);714 #else715 void test_only_hook(void) { }716 #endif717 718This test-only code can be made more useful by accessing the current ``kunit_test``719as shown in next section: *Accessing The Current Test*.720 721Accessing The Current Test722--------------------------723 724In some cases, we need to call test-only code from outside the test file. This725is helpful, for example, when providing a fake implementation of a function, or726to fail any current test from within an error handler.727We can do this via the ``kunit_test`` field in ``task_struct``, which we can728access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``.729 730``kunit_get_current_test()`` is safe to call even if KUnit is not enabled. If731KUnit is not enabled, or if no test is running in the current task, it will732return ``NULL``. This compiles down to either a no-op or a static key check,733so will have a negligible performance impact when no test is running.734 735The example below uses this to implement a "mock" implementation of a function, ``foo``:736 737.. code-block:: c738 739 #include <kunit/test-bug.h> /* for kunit_get_current_test */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_current_test();749 struct test_data *test_data = test->priv;750 751 KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);752 return test_data->foo_result;753 }754 755 static void example_simple_test(struct kunit *test)756 {757 /* Assume priv (private, a member used to pass test data from758 * the init function) is allocated in the suite's .init */759 struct test_data *test_data = test->priv;760 761 test_data->foo_result = 42;762 test_data->want_foo_called_with = 1;763 764 /* In a real test, we'd probably pass a pointer to fake_foo somewhere765 * like an ops struct, etc. instead of calling it directly. */766 KUNIT_EXPECT_EQ(test, fake_foo(1), 42);767 }768 769In this example, we are using the ``priv`` member of ``struct kunit`` as a way770of passing data to the test from the init function. In general ``priv`` is771pointer that can be used for any user data. This is preferred over static772variables, as it avoids concurrency issues.773 774Had we wanted something more flexible, we could have used a named ``kunit_resource``.775Each test can have multiple resources which have string names providing the same776flexibility as a ``priv`` member, but also, for example, allowing helper777functions to create resources without conflicting with each other. It is also778possible to define a clean up function for each resource, making it easy to779avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst.780 781Failing The Current Test782------------------------783 784If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``785which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.786For example, we have an option to enable some extra debug checks on some data787structures as shown below:788 789.. code-block:: c790 791 #include <kunit/test-bug.h>792 793 #ifdef CONFIG_EXTRA_DEBUG_CHECKS794 static void validate_my_data(struct data *data)795 {796 if (is_valid(data))797 return;798 799 kunit_fail_current_test("data %p is invalid", data);800 801 /* Normal, non-KUnit, error reporting code here. */802 }803 #else804 static void my_debug_function(void) { }805 #endif806 807``kunit_fail_current_test()`` is safe to call even if KUnit is not enabled. If808KUnit is not enabled, or if no test is running in the current task, it will do809nothing. This compiles down to either a no-op or a static key check, so will810have a negligible performance impact when no test is running.811 812Managing Fake Devices and Drivers813---------------------------------814 815When testing drivers or code which interacts with drivers, many functions will816require a ``struct device`` or ``struct device_driver``. In many cases, setting817up a real device is not required to test any given function, so a fake device818can be used instead.819 820KUnit provides helper functions to create and manage these fake devices, which821are internally of type ``struct kunit_device``, and are attached to a special822``kunit_bus``. These devices support managed device resources (devres), as823described in Documentation/driver-api/driver-model/devres.rst824 825To create a KUnit-managed ``struct device_driver``, use ``kunit_driver_create()``,826which will create a driver with the given name, on the ``kunit_bus``. This driver827will automatically be destroyed when the corresponding test finishes, but can also828be manually destroyed with ``driver_unregister()``.829 830To create a fake device, use the ``kunit_device_register()``, which will create831and register a device, using a new KUnit-managed driver created with ``kunit_driver_create()``.832To provide a specific, non-KUnit-managed driver, use ``kunit_device_register_with_driver()``833instead. Like with managed drivers, KUnit-managed fake devices are automatically834cleaned up when the test finishes, but can be manually cleaned up early with835``kunit_device_unregister()``.836 837The KUnit devices should be used in preference to ``root_device_register()``, and838instead of ``platform_device_register()`` in cases where the device is not otherwise839a platform device.840 841For example:842 843.. code-block:: c844 845 #include <kunit/device.h>846 847 static void test_my_device(struct kunit *test)848 {849 struct device *fake_device;850 const char *dev_managed_string;851 852 // Create a fake device.853 fake_device = kunit_device_register(test, "my_device");854 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device)855 856 // Pass it to functions which need a device.857 dev_managed_string = devm_kstrdup(fake_device, "Hello, World!");858 859 // Everything is cleaned up automatically when the test ends.860 }