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, the method under test should return pointer to a value. If the
116 pointer returns null or an errno, we want to stop the test since the following
117 expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us
118 to bail out of the test case if the appropriate conditions are not satisfied to
119 complete the test.
121 Test Suites
124 We need many test cases covering all the unit's behaviors. It is common to have
127 *test suite*. A test suite is a collection of test cases for a unit of code
129 suite and/or every test case. For example:
150 In the above example, the test suite ``example_test_suite`` would first run
151 ``example_suite_init``, then run the test cases ``example_test_foo``,
156 test suite with the KUnit test framework.
159 A test case will only run if it is associated with a test suite.
162 specified test suite in a special linker section so that it can be run by KUnit
163 either after ``late_init``, or when the test module is loaded (if the test was
166 For more information, see Documentation/dev-tools/kunit/api/test.rst.
178 Nevertheless, there are still valid reasons to write a test that is architecture
179 or hardware specific. For example, we might want to test code that really
180 belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
181 not depend on physical hardware. Some of our test cases may not need hardware,
182 only few tests actually require the hardware to test it. When hardware is not
191 be able to run one test case per invocation.
194 dependent KUnit test.
202 Unit testing limits the amount of code under test to a single unit. It controls
203 what code gets run when the unit under test calls a function. Where a function
268 In order to unit test a piece of code that calls a method in a class, the
269 behavior of the method must be controllable, otherwise the test ceases to be a
270 unit test and becomes an integration test.
285 And we want to test code that buffers writes to the EEPROM:
298 We can test this code by *faking out* the underlying EEPROM:
334 We can now use it to test ``struct eeprom_buffer``:
343 static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
345 struct eeprom_buffer_test *ctx = test->priv;
353 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
356 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
359 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
360 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
363 static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
365 struct eeprom_buffer_test *ctx = test->priv;
373 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
376 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
377 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
380 static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
382 struct eeprom_buffer_test *ctx = test->priv;
390 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
393 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
394 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
396 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
399 static int eeprom_buffer_test_init(struct kunit *test)
403 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
404 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
406 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
407 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
411 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
413 test->priv = ctx;
418 static void eeprom_buffer_test_exit(struct kunit *test)
420 struct eeprom_buffer_test *ctx = test->priv;
432 For example, to test ``sha1sum(1)``, we can write:
438 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
451 In complicated cases, we recommend using a *table-driven test* compared to the
476 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
485 * For example, see ``fs/ext4/inode-test.c``.
487 * reduce duplication if test cases are shared across multiple tests.
489 * For example: if we want to test ``sha256sum``, we could add a ``sha256``
492 * be converted to a "parameterized test".
500 By reusing the same ``cases`` array from above, we can write the test as a
501 "parameterized test" with the following.
521 // Need a helper function to generate a name for each test case.
529 // Looks no different from a normal test.
530 static void sha1_test(struct kunit *test)
533 // The former `cases[i]` is accessible under test->param_value.
535 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
538 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
552 We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue
558 void example_test_user_alloc_function(struct kunit *test)
563 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object);
571 will then ensure that the memory is freed once the test completes.
574 early from a test without having to worry about remembering to call ``kfree``.
579 void example_test_allocation(struct kunit *test)
581 char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
583 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);
585 KUNIT_ASSERT_STREQ(test, buffer, "");
593 conditionally ``#include`` the test file at the end of your .c file. For
606 Injecting Test-Only Code
609 Similar to as shown above, we can add test-specific logic. For example:
622 This test-only code can be made more useful by accessing the current ``kunit_test``
623 as shown in next section: *Accessing The Current Test*.
625 Accessing The Current Test
628 In some cases, we need to call test-only code from outside the test file.
629 For example, see example in section *Injecting Test-Only Code* or if
647 struct kunit *test = current->kunit_test;
648 struct test_data *test_data = test->priv;
650 KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
654 static void example_simple_test(struct kunit *test)
656 /* Assume priv (private, a member used to pass test data from
658 struct test_data *test_data = test->priv;
663 /* In a real test, we'd probably pass a pointer to fake_foo somewhere
665 KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
669 of passing data to the test from the init function. In general ``priv`` is
674 Each test can have multiple resources which have string names providing the same
678 avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst.
680 Failing The Current Test
683 If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
684 which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
690 #include <kunit/test-bug.h>