Lines Matching +full:use +full:- +full:cases
1 .. SPDX-License-Identifier: GPL-2.0
6 Test Cases
7 ----------
13 .. code-block:: c
38 .. code-block:: c
59 To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.
66 additional tests cases which would test each property that an ``add`` function
69 .. code-block:: c
79 KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
85 KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
99 .. code-block:: c
111 for (i = 0; i < TEST_LEN-1; i++)
116 function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if
125 Warning: There is an exception to the above rule. You shouldn't use assertions
131 --------------------------
137 .. code-block:: c
151 .. code-block:: c
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
176 .. code-block:: c
196 ``example_suite_init``, then run the test cases ``example_test_foo``,
214 For more information, see Documentation/dev-tools/kunit/api/test.rst.
216 .. _kunit-on-non-uml:
219 -------------------------------------
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,
241 .. TODO([email protected]): Add an actual example of an architecture-
248 ------------------
255 provided by the implementer, and architecture-specific functions, which have
262 however, it is an easily derived concept. Accordingly, in most cases, every
263 project that does not use a standardized object oriented library (like GNOME's
269 contract between *implementers* and *users* since it forces them to use the
284 .. code-block:: c
300 return self->length * self->width;
305 self->parent.area = rectangle_area;
306 self->length = length;
307 self->width = width;
326 .. code-block:: c
335 .. code-block:: c
348 .. code-block:: c
359 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
360 memcpy(buffer, this->contents + offset, count);
369 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
370 memcpy(this->contents + offset, buffer, count);
377 this->parent.read = fake_eeprom_read;
378 this->parent.write = fake_eeprom_write;
379 memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
382 We can now use it to test ``struct eeprom_buffer``:
384 .. code-block:: c
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;
398 eeprom_buffer->flush_count = SIZE_MAX;
400 eeprom_buffer->write(eeprom_buffer, buffer, 1);
401 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
403 eeprom_buffer->write(eeprom_buffer, buffer, 1);
404 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
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);
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;
418 eeprom_buffer->flush_count = 2;
420 eeprom_buffer->write(eeprom_buffer, buffer, 1);
421 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
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);
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;
435 eeprom_buffer->flush_count = 2;
437 eeprom_buffer->write(eeprom_buffer, buffer, 1);
438 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
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);
444 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
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);
458 ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
459 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
461 test->priv = ctx;
468 struct eeprom_buffer_test *ctx = test->priv;
470 destroy_eeprom_buffer(ctx->eeprom_buffer);
474 -------------------------------
482 .. code-block:: c
492 Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more
499 In complicated cases, we recommend using a *table-driven test* compared to the
502 .. code-block:: c
512 struct sha1_test_case cases[] = {
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);
533 * For example, see ``fs/ext4/inode-test.c``.
535 * reduce duplication if test cases are shared across multiple tests.
538 field and reuse ``cases``.
545 The table-driven testing pattern is common enough that KUnit has special
548 By reusing the same ``cases`` array from above, we can write the test as a
551 .. code-block:: c
553 // This is copy-pasted from above.
558 const struct sha1_test_case cases[] = {
569 // Creates `sha1_gen_params()` to iterate over `cases` while using
571 KUNIT_ARRAY_PARAM_DESC(sha1, cases, str);
576 // This function can just contain the body of the for-loop.
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);
581 sha1sum(test_param->str, out);
582 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
583 "sha1sum(%s)", test_param->str);
586 // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
594 -----------------
596 Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit
599 This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit
603 .. code-block:: c
615 ---------------------------
617 If you need to perform some cleanup beyond simple use of ``kunit_kzalloc``,
624 (in some cases) destructors in RAII languages.
631 .. code-block:: C
650 pointer-sized argument, it's possible to automatically generate a wrapper
653 .. code-block:: C
662 You can use ``kunit_add_action_or_reset`` instead which runs the action
671 ------------------------
676 .. code-block:: c
692 .. code-block:: c
702 Injecting Test-Only Code
703 ------------------------
705 Similar to as shown above, we can add test-specific logic. For example:
707 .. code-block:: c
718 This test-only code can be made more useful by accessing the current ``kunit_test``
722 --------------------------
724 In some cases, we need to call test-only code from outside the test file. This
728 access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``.
732 return ``NULL``. This compiles down to either a no-op or a static key check,
737 .. code-block:: c
739 #include <kunit/test-bug.h> /* for kunit_get_current_test */
749 struct test_data *test_data = test->priv;
751 KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
752 return test_data->foo_result;
759 struct test_data *test_data = test->priv;
761 test_data->foo_result = 42;
762 test_data->want_foo_called_with = 1;
779 avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst.
782 ------------------------
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>``.
789 .. code-block:: c
791 #include <kunit/test-bug.h>
801 /* Normal, non-KUnit, error reporting code here. */
809 nothing. This compiles down to either a no-op or a static key check, so will
813 ---------------------------------
816 require a ``struct device`` or ``struct device_driver``. In many cases, setting
823 described in Documentation/driver-api/driver-model/devres.rst
825 To create a KUnit-managed ``struct device_driver``, use ``kunit_driver_create()``,
830 To create a fake device, use the ``kunit_device_register()``, which will create
831 and register a device, using a new KUnit-managed driver created with ``kunit_driver_create()``.
832 To provide a specific, non-KUnit-managed driver, use ``kunit_device_register_with_driver()``
833 instead. Like with managed drivers, KUnit-managed fake devices are automatically
838 instead of ``platform_device_register()`` in cases where the device is not otherwise
843 .. code-block:: c