^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Using KUnit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) The purpose of this document is to describe what KUnit is, how it works, how it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) is intended to be used, and all the concepts and terminology that are needed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) understand it. This guide assumes a working knowledge of the Linux kernel and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) some basic knowledge of testing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) For a high level introduction to KUnit, including setting up KUnit for your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) project, see :doc:`start`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Organization of this document
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) This document is organized into two main sections: Testing and Isolating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Behavior. The first covers what unit tests are and how to use KUnit to write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) them. The second covers how to use KUnit to isolate code and make it possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) to unit test code that was otherwise un-unit-testable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Testing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) What is KUnit?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) "K" is short for "kernel" so "KUnit" is the "(Linux) Kernel Unit Testing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Framework." KUnit is intended first and foremost for writing unit tests; it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) general enough that it can be used to write integration tests; however, this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) a secondary goal. KUnit has no ambition of being the only testing framework for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) the kernel; for example, it does not intend to be an end-to-end testing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) framework.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) What is Unit Testing?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) A `unit test <https://martinfowler.com/bliki/UnitTest.html>`_ is a test that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) tests code at the smallest possible scope, a *unit* of code. In the C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) programming language that's a function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Unit tests should be written for all the publicly exposed functions in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) compilation unit; so that is all the functions that are exported in either a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) *class* (defined below) or all functions which are **not** static.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Writing Tests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) Test Cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) ~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) The fundamental unit in KUnit is the test case. A test case is a function with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) the signature ``void (*)(struct kunit *test)``. It calls a function to be tested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) and then sets *expectations* for what should happen. For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) void example_test_success(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) void example_test_failure(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) KUNIT_FAIL(test, "This test never passes.");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) In the above example ``example_test_success`` always passes because it does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) nothing; no expectations are set, so all expectations pass. On the other hand
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) a special expectation that logs a message and causes the test case to fail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) Expectations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) An *expectation* is a way to specify that you expect a piece of code to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) something in a test. An expectation is called like a function. A test is made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) by setting expectations about the behavior of a piece of code under test; when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) one or more of the expectations fail, the test case fails and information about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) the failure is logged. For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) void add_test_basic(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) KUNIT_EXPECT_EQ(test, 1, add(1, 0));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) KUNIT_EXPECT_EQ(test, 2, add(1, 1));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) In the above example ``add_test_basic`` makes a number of assertions about the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) behavior of a function called ``add``; the first parameter is always of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) ``struct kunit *``, which contains information about the current test context;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) the second parameter, in this case, is what the value is expected to be; the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) last value is what the value actually is. If ``add`` passes all of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) expectations, the test case, ``add_test_basic`` will pass; if any one of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) expectations fails, the test case will fail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) It is important to understand that a test case *fails* when any expectation is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) violated; however, the test will continue running, potentially trying other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) expectations until the test case ends or is otherwise terminated. This is as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) opposed to *assertions* which are discussed later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) To learn about more expectations supported by KUnit, see :doc:`api/test`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) A single test case should be pretty short, pretty easy to understand,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) focused on a single behavior.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) For example, if we wanted to properly test the add function above, we would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) create additional tests cases which would each test a different property that an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) add function should have like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) void add_test_basic(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) KUNIT_EXPECT_EQ(test, 1, add(1, 0));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) KUNIT_EXPECT_EQ(test, 2, add(1, 1));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) void add_test_negative(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) void add_test_max(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) void add_test_overflow(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Notice how it is immediately obvious what all the properties that we are testing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) for are.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) Assertions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) ~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) KUnit also has the concept of an *assertion*. An assertion is just like an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) expectation except the assertion immediately terminates the test case if it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) not satisfied.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) static void mock_test_do_expect_default_return(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) struct mock_test_context *ctx = test->priv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) struct mock *mock = ctx->mock;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) int param0 = 5, param1 = -5;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) const char *two_param_types[] = {"int", "int"};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) const void *two_params[] = {¶m0, ¶m1};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) const void *ret;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) ret = mock->do_expect(mock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) "test_printk", test_printk,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) two_param_types, two_params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) ARRAY_SIZE(two_params));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ret);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) KUNIT_EXPECT_EQ(test, -4, *((int *) ret));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) In this example, the method under test should return a pointer to a value, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) if the pointer returned by the method is null or an errno, we don't want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) bother continuing the test since the following expectation could crash the test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us to bail out of the test case if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) the appropriate conditions have not been satisfied to complete the test.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) Test Suites
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) ~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) Now obviously one unit test isn't very helpful; the power comes from having
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) many test cases covering all of a unit's behaviors. Consequently it is common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) to have many *similar* tests; in order to reduce duplication in these closely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) related tests most unit testing frameworks - including KUnit - provide the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) concept of a *test suite*. A *test suite* is just a collection of test cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) for a unit of code with a set up function that gets invoked before every test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) case and then a tear down function that gets invoked after every test case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) completes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) Example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) static struct kunit_case example_test_cases[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) KUNIT_CASE(example_test_foo),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) KUNIT_CASE(example_test_bar),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) KUNIT_CASE(example_test_baz),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) {}
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) static struct kunit_suite example_test_suite = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) .name = "example",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) .init = example_test_init,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) .exit = example_test_exit,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) .test_cases = example_test_cases,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) kunit_test_suite(example_test_suite);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) In the above example the test suite, ``example_test_suite``, would run the test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) cases ``example_test_foo``, ``example_test_bar``, and ``example_test_baz``;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) each would have ``example_test_init`` called immediately before it and would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) have ``example_test_exit`` called immediately after it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) ``kunit_test_suite(example_test_suite)`` registers the test suite with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) KUnit test framework.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) A test case will only be run if it is associated with a test suite.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) ``kunit_test_suite(...)`` is a macro which tells the linker to put the specified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) test suite in a special linker section so that it can be run by KUnit either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) after late_init, or when the test module is loaded (depending on whether the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) test was built in or not).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) For more information on these types of things see the :doc:`api/test`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) Isolating Behavior
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) The most important aspect of unit testing that other forms of testing do not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) provide is the ability to limit the amount of code under test to a single unit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) In practice, this is only possible by being able to control what code gets run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) when the unit under test calls a function and this is usually accomplished
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) through some sort of indirection where a function is exposed as part of an API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) such that the definition of that function can be changed without affecting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) rest of the code base. In the kernel this primarily comes from two constructs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) classes, structs that contain function pointers that are provided by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) implementer, and architecture-specific functions which have definitions selected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) at compile time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) Classes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) Classes are not a construct that is built into the C programming language;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) however, it is an easily derived concept. Accordingly, pretty much every project
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) that does not use a standardized object oriented library (like GNOME's GObject)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) has their own slightly different way of doing object oriented programming; the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) Linux kernel is no exception.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) The central concept in kernel object oriented programming is the class. In the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) kernel, a *class* is a struct that contains function pointers. This creates a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) contract between *implementers* and *users* since it forces them to use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) same function signature without having to call the function directly. In order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) for it to truly be a class, the function pointers must specify that a pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) to the class, known as a *class handle*, be one of the parameters; this makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) it possible for the member functions (also known as *methods*) to have access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) to member variables (more commonly known as *fields*) allowing the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) implementation to have multiple *instances*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) Typically a class can be *overridden* by *child classes* by embedding the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) *parent class* in the child class. Then when a method provided by the child
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) class is called, the child implementation knows that the pointer passed to it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) of a parent contained within the child; because of this, the child can compute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) the pointer to itself because the pointer to the parent is always a fixed offset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) from the pointer to the child; this offset is the offset of the parent contained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) in the child struct. For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) struct shape {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) int (*area)(struct shape *this);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) struct rectangle {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) struct shape parent;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) int length;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) int width;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) int rectangle_area(struct shape *this)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) struct rectangle *self = container_of(this, struct shape, parent);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) return self->length * self->width;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) void rectangle_new(struct rectangle *self, int length, int width)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) self->parent.area = rectangle_area;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) self->length = length;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) self->width = width;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) In this example (as in most kernel code) the operation of computing the pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) to the child from the pointer to the parent is done by ``container_of``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) Faking Classes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) In order to unit test a piece of code that calls a method in a class, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) behavior of the method must be controllable, otherwise the test ceases to be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) unit test and becomes an integration test.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) A fake just provides an implementation of a piece of code that is different than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) what runs in a production instance, but behaves identically from the standpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) of the callers; this is usually done to replace a dependency that is hard to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) deal with, or is slow.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) A good example for this might be implementing a fake EEPROM that just stores the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) "contents" in an internal buffer. For example, let's assume we have a class that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) represents an EEPROM:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) struct eeprom {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) And we want to test some code that buffers writes to the EEPROM:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) struct eeprom_buffer {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) int flush(struct eeprom_buffer *this);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) size_t flush_count; /* Flushes when buffer exceeds flush_count. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) void destroy_eeprom_buffer(struct eeprom *eeprom);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) We can easily test this code by *faking out* the underlying EEPROM:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) struct fake_eeprom {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) struct eeprom parent;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) char contents[FAKE_EEPROM_CONTENTS_SIZE];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) memcpy(buffer, this->contents + offset, count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) return count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) memcpy(this->contents + offset, buffer, count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) return count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) void fake_eeprom_init(struct fake_eeprom *this)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) this->parent.read = fake_eeprom_read;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) this->parent.write = fake_eeprom_write;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) We can now use it to test ``struct eeprom_buffer``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) struct eeprom_buffer_test {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) struct fake_eeprom *fake_eeprom;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) struct eeprom_buffer *eeprom_buffer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) struct eeprom_buffer_test *ctx = test->priv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) char buffer[] = {0xff};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) eeprom_buffer->flush_count = SIZE_MAX;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) eeprom_buffer->write(eeprom_buffer, buffer, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) eeprom_buffer->write(eeprom_buffer, buffer, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) eeprom_buffer->flush(eeprom_buffer);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) struct eeprom_buffer_test *ctx = test->priv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) char buffer[] = {0xff};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) eeprom_buffer->flush_count = 2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) eeprom_buffer->write(eeprom_buffer, buffer, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) eeprom_buffer->write(eeprom_buffer, buffer, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) struct eeprom_buffer_test *ctx = test->priv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) char buffer[] = {0xff, 0xff};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) eeprom_buffer->flush_count = 2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) eeprom_buffer->write(eeprom_buffer, buffer, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) eeprom_buffer->write(eeprom_buffer, buffer, 2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) /* Should have only flushed the first two bytes. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) static int eeprom_buffer_test_init(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) struct eeprom_buffer_test *ctx;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) fake_eeprom_init(ctx->fake_eeprom);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) test->priv = ctx;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) static void eeprom_buffer_test_exit(struct kunit *test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) struct eeprom_buffer_test *ctx = test->priv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) destroy_eeprom_buffer(ctx->eeprom_buffer);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) .. _kunit-on-non-uml:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) KUnit on non-UML architectures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) By default KUnit uses UML as a way to provide dependencies for code under test.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) Under most circumstances KUnit's usage of UML should be treated as an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) implementation detail of how KUnit works under the hood. Nevertheless, there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) are instances where being able to run architecture-specific code or test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) against real hardware is desirable. For these reasons KUnit supports running on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) other architectures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) Running existing KUnit tests on non-UML architectures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) -----------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) There are some special considerations when running existing KUnit tests on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) non-UML architectures:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) * Hardware may not be deterministic, so a test that always passes or fails
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) when run under UML may not always do so on real hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) * Hardware and VM environments may not be hermetic. KUnit tries its best to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) provide a hermetic environment to run tests; however, it cannot manage state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) that it doesn't know about outside of the kernel. Consequently, tests that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) may be hermetic on UML may not be hermetic on other architectures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) * Some features and tooling may not be supported outside of UML.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) * Hardware and VMs are slower than UML.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) None of these are reasons not to run your KUnit tests on real hardware; they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) only things to be aware of when doing so.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) The biggest impediment will likely be that certain KUnit features and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) infrastructure may not support your target environment. For example, at this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) time the KUnit Wrapper (``tools/testing/kunit/kunit.py``) does not work outside
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) of UML. Unfortunately, there is no way around this. Using UML (or even just a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) particular architecture) allows us to make a lot of assumptions that make it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) possible to do things which might otherwise be impossible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) Nevertheless, all core KUnit framework features are fully supported on all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) architectures, and using them is straightforward: all you need to do is to take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) your kunitconfig, your Kconfig options for the tests you would like to run, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) merge them into whatever config your are using for your platform. That's it!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) For example, let's say you have the following kunitconfig:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) CONFIG_KUNIT=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) CONFIG_KUNIT_EXAMPLE_TEST=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) If you wanted to run this test on an x86 VM, you might add the following config
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) options to your ``.config``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) CONFIG_KUNIT=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) CONFIG_KUNIT_EXAMPLE_TEST=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) CONFIG_SERIAL_8250=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) CONFIG_SERIAL_8250_CONSOLE=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) All these new options do is enable support for a common serial console needed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) for logging.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) Next, you could build a kernel with these tests as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) .. code-block:: bash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) make ARCH=x86 olddefconfig
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) make ARCH=x86
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) Once you have built a kernel, you could run it on QEMU as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) .. code-block:: bash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) qemu-system-x86_64 -enable-kvm \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) -m 1024 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) -kernel arch/x86_64/boot/bzImage \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) -append 'console=ttyS0' \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) --nographic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) Interspersed in the kernel logs you might see the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) TAP version 14
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) # Subtest: example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) 1..1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) # example_simple_test: initializing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) ok 1 - example_simple_test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) ok 1 - example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) Congratulations, you just ran a KUnit test on the x86 architecture!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) In a similar manner, kunit and kunit tests can also be built as modules,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) so if you wanted to run tests in this way you might add the following config
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) options to your ``.config``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) CONFIG_KUNIT=m
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) CONFIG_KUNIT_EXAMPLE_TEST=m
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) Once the kernel is built and installed, a simple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) .. code-block:: bash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) modprobe example-test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) ...will run the tests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) Note that you should make sure your test depends on ``KUNIT=y`` in Kconfig
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) if the test does not support module build. Otherwise, it will trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) compile errors if ``CONFIG_KUNIT`` is ``m``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) Writing new tests for other architectures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) The first thing you must do is ask yourself whether it is necessary to write a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) KUnit test for a specific architecture, and then whether it is necessary to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) write that test for a particular piece of hardware. In general, writing a test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) that depends on having access to a particular piece of hardware or software (not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) included in the Linux source repo) should be avoided at all costs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) Even if you only ever plan on running your KUnit test on your hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) configuration, other people may want to run your tests and may not have access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) to your hardware. If you write your test to run on UML, then anyone can run your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) tests without knowing anything about your particular setup, and you can still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) run your tests on your hardware setup just by compiling for your architecture.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) .. important::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) Always prefer tests that run on UML to tests that only run under a particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) architecture, and always prefer tests that run under QEMU or another easy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) (and monetarily free) to obtain software environment to a specific piece of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) Nevertheless, there are still valid reasons to write an architecture or hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) specific test: for example, you might want to test some code that really belongs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) in ``arch/some-arch/*``. Even so, try your best to write the test so that it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) does not depend on physical hardware: if some of your test cases don't need the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) hardware, only require the hardware for tests that actually need it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) Now that you have narrowed down exactly what bits are hardware specific, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) actual procedure for writing and running the tests is pretty much the same as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) writing normal KUnit tests. One special caveat is that you have to reset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) hardware state in between test cases; if this is not possible, you may only be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) able to run one test case per invocation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) .. TODO(brendanhiggins@google.com): Add an actual example of an architecture-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) dependent KUnit test.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) KUnit debugfs representation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) When kunit test suites are initialized, they create an associated directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) in ``/sys/kernel/debug/kunit/<test-suite>``. The directory contains one file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) - results: "cat results" displays results of each test case and the results
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) of the entire suite for the last test run.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) The debugfs representation is primarily of use when kunit test suites are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) run in a native environment, either as modules or builtin. Having a way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) to display results like this is valuable as otherwise results can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) intermixed with other events in dmesg output. The maximum size of each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) results file is KUNIT_LOG_SIZE bytes (defined in ``include/kunit/test.h``).
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags