lib/kunit/kunit-example-test.c

   1 // SPDX-License-Identifier: GPL-2.0
   2 /*
   3  * Example KUnit test to show how to use KUnit.
   4  *
   5  * Copyright (C) 2019, Google LLC.
   6  * Author: Brendan Higgins <brendanhiggins@google.com>
   7  */
   8
   9 #include <kunit/test.h>
  10 #include <kunit/static_stub.h>
  11
  12 /*
  13  * This is the most fundamental element of KUnit, the test case. A test case
  14  * makes a set EXPECTATIONs and ASSERTIONs about the behavior of some code; if
  15  * any expectations or assertions are not met, the test fails; otherwise, the
  16  * test passes.
  17  *
  18  * In KUnit, a test case is just a function with the signature
  19  * `void (*)(struct kunit *)`. `struct kunit` is a context object that stores
  20  * information about the current test.
  21  */
  22 static void example_simple_test(struct kunit *test)
  23 {
  24         /*
  25          * This is an EXPECTATION; it is how KUnit tests things. When you want
  26          * to test a piece of code, you set some expectations about what the
  27          * code should do. KUnit then runs the test and verifies that the code's
  28          * behavior matched what was expected.
  29          */
  30         KUNIT_EXPECT_EQ(test, 1 + 1, 2);
  31 }
  32
  33 /*
  34  * This is run once before each test case, see the comment on
  35  * example_test_suite for more information.
  36  */
  37 static int example_test_init(struct kunit *test)
  38 {
  39         kunit_info(test, "initializing\n");
  40
  41         return 0;
  42 }
  43
  44 /*
  45  * This is run once before all test cases in the suite.
  46  * See the comment on example_test_suite for more information.
  47  */
  48 static int example_test_init_suite(struct kunit_suite *suite)
  49 {
  50         kunit_info(suite, "initializing suite\n");
  51
  52         return 0;
  53 }
  54
  55 /*
  56  * This test should always be skipped.
  57  */
  58 static void example_skip_test(struct kunit *test)
  59 {
  60         /* This line should run */
  61         kunit_info(test, "You should not see a line below.");
  62
  63         /* Skip (and abort) the test */
  64         kunit_skip(test, "this test should be skipped");
  65
  66         /* This line should not execute */
  67         KUNIT_FAIL(test, "You should not see this line.");
  68 }
  69
  70 /*
  71  * This test should always be marked skipped.
  72  */
  73 static void example_mark_skipped_test(struct kunit *test)
  74 {
  75         /* This line should run */
  76         kunit_info(test, "You should see a line below.");
  77
  78         /* Skip (but do not abort) the test */
  79         kunit_mark_skipped(test, "this test should be skipped");
  80
  81         /* This line should run */
  82         kunit_info(test, "You should see this line.");
  83 }
  84
  85 /*
  86  * This test shows off all the types of KUNIT_EXPECT macros.
  87  */
  88 static void example_all_expect_macros_test(struct kunit *test)
  89 {
  90         const u32 array1[] = { 0x0F, 0xFF };
  91         const u32 array2[] = { 0x1F, 0xFF };
  92
  93         /* Boolean assertions */
  94         KUNIT_EXPECT_TRUE(test, true);
  95         KUNIT_EXPECT_FALSE(test, false);
  96
  97         /* Integer assertions */
  98         KUNIT_EXPECT_EQ(test, 1, 1); /* check == */
  99         KUNIT_EXPECT_GE(test, 1, 1); /* check >= */
 100         KUNIT_EXPECT_LE(test, 1, 1); /* check <= */
 101         KUNIT_EXPECT_NE(test, 1, 0); /* check != */
 102         KUNIT_EXPECT_GT(test, 1, 0); /* check >  */
 103         KUNIT_EXPECT_LT(test, 0, 1); /* check <  */
 104
 105         /* Pointer assertions */
 106         KUNIT_EXPECT_NOT_ERR_OR_NULL(test, test);
 107         KUNIT_EXPECT_PTR_EQ(test, NULL, NULL);
 108         KUNIT_EXPECT_PTR_NE(test, test, NULL);
 109         KUNIT_EXPECT_NULL(test, NULL);
 110         KUNIT_EXPECT_NOT_NULL(test, test);
 111
 112         /* String assertions */
 113         KUNIT_EXPECT_STREQ(test, "hi", "hi");
 114         KUNIT_EXPECT_STRNEQ(test, "hi", "bye");
 115
 116         /* Memory block assertions */
 117         KUNIT_EXPECT_MEMEQ(test, array1, array1, sizeof(array1));
 118         KUNIT_EXPECT_MEMNEQ(test, array1, array2, sizeof(array1));
 119
 120         /*
 121          * There are also ASSERT variants of all of the above that abort test
 122          * execution if they fail. Useful for memory allocations, etc.
 123          */
 124         KUNIT_ASSERT_GT(test, sizeof(char), 0);
 125
 126         /*
 127          * There are also _MSG variants of all of the above that let you include
 128          * additional text on failure.
 129          */
 130         KUNIT_EXPECT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!");
 131         KUNIT_ASSERT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!");
 132 }
 133
 134 /* This is a function we'll replace with static stubs. */
 135 static int add_one(int i)
 136 {
 137         /* This will trigger the stub if active. */
 138         KUNIT_STATIC_STUB_REDIRECT(add_one, i);
 139
 140         return i + 1;
 141 }
 142
 143 /* This is used as a replacement for the above function. */
 144 static int subtract_one(int i)
 145 {
 146         /* We don't need to trigger the stub from the replacement. */
 147
 148         return i - 1;
 149 }
 150
 151 /*
 152  * This test shows the use of static stubs.
 153  */
 154 static void example_static_stub_test(struct kunit *test)
 155 {
 156         /* By default, function is not stubbed. */
 157         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 158
 159         /* Replace add_one() with subtract_one(). */
 160         kunit_activate_static_stub(test, add_one, subtract_one);
 161
 162         /* add_one() is now replaced. */
 163         KUNIT_EXPECT_EQ(test, add_one(1), 0);
 164
 165         /* Return add_one() to normal. */
 166         kunit_deactivate_static_stub(test, add_one);
 167         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 168 }
 169
 170 /*
 171  * Here we make a list of all the test cases we want to add to the test suite
 172  * below.
 173  */
 174 static struct kunit_case example_test_cases[] = {
 175         /*
 176          * This is a helper to create a test case object from a test case
 177          * function; its exact function is not important to understand how to
 178          * use KUnit, just know that this is how you associate test cases with a
 179          * test suite.
 180          */
 181         KUNIT_CASE(example_simple_test),
 182         KUNIT_CASE(example_skip_test),
 183         KUNIT_CASE(example_mark_skipped_test),
 184         KUNIT_CASE(example_all_expect_macros_test),
 185         KUNIT_CASE(example_static_stub_test),
 186         {}
 187 };
 188
 189 /*
 190  * This defines a suite or grouping of tests.
 191  *
 192  * Test cases are defined as belonging to the suite by adding them to
 193  * `kunit_cases`.
 194  *
 195  * Often it is desirable to run some function which will set up things which
 196  * will be used by every test; this is accomplished with an `init` function
 197  * which runs before each test case is invoked. Similarly, an `exit` function
 198  * may be specified which runs after every test case and can be used to for
 199  * cleanup. For clarity, running tests in a test suite would behave as follows:
 200  *
 201  * suite.suite_init(suite);
 202  * suite.init(test);
 203  * suite.test_case[0](test);
 204  * suite.exit(test);
 205  * suite.init(test);
 206  * suite.test_case[1](test);
 207  * suite.exit(test);
 208  * suite.suite_exit(suite);
 209  * ...;
 210  */
 211 static struct kunit_suite example_test_suite = {
 212         .name = "example",
 213         .init = example_test_init,
 214         .suite_init = example_test_init_suite,
 215         .test_cases = example_test_cases,
 216 };
 217
 218 /*
 219  * This registers the above test suite telling KUnit that this is a suite of
 220  * tests that need to be run.
 221  */
 222 kunit_test_suites(&example_test_suite);
 223
 224 MODULE_LICENSE("GPL v2");