Lines Matching full:test
6 Test Cases
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
15 void example_test_success(struct kunit *test)
19 void example_test_failure(struct kunit *test)
21 KUNIT_FAIL(test, "This test never passes.");
27 which is a special expectation that logs a message and causes the test case to
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));
48 ``struct kunit *``, which contains information about the current test context.
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
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
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));
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);
112 KUNIT_EXPECT_LE(test, a[i], a[i + 1]);
115 In this example, we need to be able to allocate an array to test the ``sort()``
116 function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if
120 In other test frameworks, ``ASSERT`` macros are often implemented by calling
121 ``return`` so they only work from the test function. In KUnit, we stop the
127 run when a test is shutting down, and an assertion here prevents further
142 /* Before. Not easy to tell why the test failed. */
143 KUNIT_EXPECT_EQ(test, strlen(some_str), 40);
146 KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str);
154 KUNIT_EXPECT_EQ(test, some_setup_function(), 0);
158 KUNIT_FAIL(test, "Failed to setup thing for testing");
161 Test Suites
164 We need many test cases covering all the unit's behaviors. It is common to have
167 *test suite*. A test suite is a collection of test cases for a unit of code
169 suite and/or every test case.
172 A test case will only run if it is associated with a test suite.
195 In the above example, the test suite ``example_test_suite`` would first run
196 ``example_suite_init``, then run the test cases ``example_test_foo``,
201 test suite with the KUnit test framework.
210 specified test suite in a special linker section so that it can be run by KUnit
211 either after ``late_init``, or when the test module is loaded (if the test was
214 For more information, see Documentation/dev-tools/kunit/api/test.rst.
226 Nevertheless, there are still valid reasons to write a test that is architecture
227 or hardware specific. For example, we might want to test code that really
228 belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
229 not depend on physical hardware. Some of our test cases may not need hardware,
230 only few tests actually require the hardware to test it. When hardware is not
239 be able to run one test case per invocation.
242 dependent KUnit test.
250 Unit testing limits the amount of code under test to a single unit. It controls
251 what code gets run when the unit under test calls a function. Where a function
316 In order to unit test a piece of code that calls a method in a class, the
317 behavior of the method must be controllable, otherwise the test ceases to be a
318 unit test and becomes an integration test.
333 And we want to test code that buffers writes to the EEPROM:
346 We can test this code by *faking out* the underlying EEPROM:
382 We can now use it to test ``struct eeprom_buffer``:
391 static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
393 struct eeprom_buffer_test *ctx = test->priv;
401 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
404 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
407 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
408 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
411 static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
413 struct eeprom_buffer_test *ctx = test->priv;
421 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
424 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
425 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
428 static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
430 struct eeprom_buffer_test *ctx = test->priv;
438 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
441 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
442 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
444 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
447 static int eeprom_buffer_test_init(struct kunit *test)
451 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
452 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
454 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
455 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
459 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
461 test->priv = ctx;
466 static void eeprom_buffer_test_exit(struct kunit *test)
468 struct eeprom_buffer_test *ctx = test->priv;
480 For example, to test ``sha1sum(1)``, we can write:
486 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
499 In complicated cases, we recommend using a *table-driven test* compared to the
524 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
533 * For example, see ``fs/ext4/inode-test.c``.
535 * reduce duplication if test cases are shared across multiple tests.
537 * For example: if we want to test ``sha256sum``, we could add a ``sha256``
540 * be converted to a "parameterized test".
548 By reusing the same ``cases`` array from above, we can write the test as a
549 "parameterized test" with the following.
573 // Looks no different from a normal test.
574 static void sha1_test(struct kunit *test)
577 // The former `cases[i]` is accessible under test->param_value.
579 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
582 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
597 will then ensure that the memory is freed once the test completes.
600 early from a test without having to worry about remembering to call ``kfree``.
605 void example_test_allocation(struct kunit *test)
607 char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
609 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);
611 KUNIT_ASSERT_STREQ(test, buffer, "");
619 run when the test exits (whether cleanly, or via a failed assertion).
640 void example_device_test(struct kunit *test)
646 kunit_add_action(test, &cleanup_device, &dev);
656 kunit_add_action(test, &device_unregister_wrapper, &dev);
689 Alternatively, you could conditionally ``#include`` the test file at the end of
702 Injecting Test-Only Code
705 Similar to as shown above, we can add test-specific logic. For example:
718 This test-only code can be made more useful by accessing the current ``kunit_test``
719 as shown in next section: *Accessing The Current Test*.
721 Accessing The Current Test
724 In some cases, we need to call test-only code from outside the test file. This
726 to fail any current test from within an error handler.
728 access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``.
731 KUnit is not enabled, or if no test is running in the current task, it will
733 so will have a negligible performance impact when no test is running.
739 #include <kunit/test-bug.h> /* for kunit_get_current_test */
748 struct kunit *test = kunit_get_current_test();
749 struct test_data *test_data = test->priv;
751 KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
755 static void example_simple_test(struct kunit *test)
757 /* Assume priv (private, a member used to pass test data from
759 struct test_data *test_data = test->priv;
764 /* In a real test, we'd probably pass a pointer to fake_foo somewhere
766 KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
770 of passing data to the test from the init function. In general ``priv`` is
775 Each test can have multiple resources which have string names providing the same
781 Failing The Current Test
784 If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
785 which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
791 #include <kunit/test-bug.h>
808 KUnit is not enabled, or if no test is running in the current task, it will do
810 have a negligible performance impact when no test is running.
817 up a real device is not required to test any given function, so a fake device
827 will automatically be destroyed when the corresponding test finishes, but can also
834 cleaned up when the test finishes, but can be manually cleaned up early with
847 static void test_my_device(struct kunit *test)
853 fake_device = kunit_device_register(test, "my_device");
854 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device)
859 // Everything is cleaned up automatically when the test ends.