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 after each test case, see the comment on
  46  * example_test_suite for more information.
  47  */
  48 static void example_test_exit(struct kunit *test)
  49 {
  50         kunit_info(test, "cleaning up\n");
  51 }
  52
  53
  54 /*
  55  * This is run once before all test cases in the suite.
  56  * See the comment on example_test_suite for more information.
  57  */
  58 static int example_test_init_suite(struct kunit_suite *suite)
  59 {
  60         kunit_info(suite, "initializing suite\n");
  61
  62         return 0;
  63 }
  64
  65 /*
  66  * This is run once after all test cases in the suite.
  67  * See the comment on example_test_suite for more information.
  68  */
  69 static void example_test_exit_suite(struct kunit_suite *suite)
  70 {
  71         kunit_info(suite, "exiting suite\n");
  72 }
  73
  74
  75 /*
  76  * This test should always be skipped.
  77  */
  78 static void example_skip_test(struct kunit *test)
  79 {
  80         /* This line should run */
  81         kunit_info(test, "You should not see a line below.");
  82
  83         /* Skip (and abort) the test */
  84         kunit_skip(test, "this test should be skipped");
  85
  86         /* This line should not execute */
  87         KUNIT_FAIL(test, "You should not see this line.");
  88 }
  89
  90 /*
  91  * This test should always be marked skipped.
  92  */
  93 static void example_mark_skipped_test(struct kunit *test)
  94 {
  95         /* This line should run */
  96         kunit_info(test, "You should see a line below.");
  97
  98         /* Skip (but do not abort) the test */
  99         kunit_mark_skipped(test, "this test should be skipped");
 100
 101         /* This line should run */
 102         kunit_info(test, "You should see this line.");
 103 }
 104
 105 /*
 106  * This test shows off all the types of KUNIT_EXPECT macros.
 107  */
 108 static void example_all_expect_macros_test(struct kunit *test)
 109 {
 110         const u32 array1[] = { 0x0F, 0xFF };
 111         const u32 array2[] = { 0x1F, 0xFF };
 112
 113         /* Boolean assertions */
 114         KUNIT_EXPECT_TRUE(test, true);
 115         KUNIT_EXPECT_FALSE(test, false);
 116
 117         /* Integer assertions */
 118         KUNIT_EXPECT_EQ(test, 1, 1); /* check == */
 119         KUNIT_EXPECT_GE(test, 1, 1); /* check >= */
 120         KUNIT_EXPECT_LE(test, 1, 1); /* check <= */
 121         KUNIT_EXPECT_NE(test, 1, 0); /* check != */
 122         KUNIT_EXPECT_GT(test, 1, 0); /* check >  */
 123         KUNIT_EXPECT_LT(test, 0, 1); /* check <  */
 124
 125         /* Pointer assertions */
 126         KUNIT_EXPECT_NOT_ERR_OR_NULL(test, test);
 127         KUNIT_EXPECT_PTR_EQ(test, NULL, NULL);
 128         KUNIT_EXPECT_PTR_NE(test, test, NULL);
 129         KUNIT_EXPECT_NULL(test, NULL);
 130         KUNIT_EXPECT_NOT_NULL(test, test);
 131
 132         /* String assertions */
 133         KUNIT_EXPECT_STREQ(test, "hi", "hi");
 134         KUNIT_EXPECT_STRNEQ(test, "hi", "bye");
 135
 136         /* Memory block assertions */
 137         KUNIT_EXPECT_MEMEQ(test, array1, array1, sizeof(array1));
 138         KUNIT_EXPECT_MEMNEQ(test, array1, array2, sizeof(array1));
 139
 140         /*
 141          * There are also ASSERT variants of all of the above that abort test
 142          * execution if they fail. Useful for memory allocations, etc.
 143          */
 144         KUNIT_ASSERT_GT(test, sizeof(char), 0);
 145
 146         /*
 147          * There are also _MSG variants of all of the above that let you include
 148          * additional text on failure.
 149          */
 150         KUNIT_EXPECT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!");
 151         KUNIT_ASSERT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!");
 152 }
 153
 154 /* This is a function we'll replace with static stubs. */
 155 static int add_one(int i)
 156 {
 157         /* This will trigger the stub if active. */
 158         KUNIT_STATIC_STUB_REDIRECT(add_one, i);
 159
 160         return i + 1;
 161 }
 162
 163 /* This is used as a replacement for the above function. */
 164 static int subtract_one(int i)
 165 {
 166         /* We don't need to trigger the stub from the replacement. */
 167
 168         return i - 1;
 169 }
 170
 171 /*
 172  * This test shows the use of static stubs.
 173  */
 174 static void example_static_stub_test(struct kunit *test)
 175 {
 176         /* By default, function is not stubbed. */
 177         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 178
 179         /* Replace add_one() with subtract_one(). */
 180         kunit_activate_static_stub(test, add_one, subtract_one);
 181
 182         /* add_one() is now replaced. */
 183         KUNIT_EXPECT_EQ(test, add_one(1), 0);
 184
 185         /* Return add_one() to normal. */
 186         kunit_deactivate_static_stub(test, add_one);
 187         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 188 }
 189
 190 static const struct example_param {
 191         int value;
 192 } example_params_array[] = {
 193         { .value = 2, },
 194         { .value = 1, },
 195         { .value = 0, },
 196 };
 197
 198 static void example_param_get_desc(const struct example_param *p, char *desc)
 199 {
 200         snprintf(desc, KUNIT_PARAM_DESC_SIZE, "example value %d", p->value);
 201 }
 202
 203 KUNIT_ARRAY_PARAM(example, example_params_array, example_param_get_desc);
 204
 205 /*
 206  * This test shows the use of params.
 207  */
 208 static void example_params_test(struct kunit *test)
 209 {
 210         const struct example_param *param = test->param_value;
 211
 212         /* By design, param pointer will not be NULL */
 213         KUNIT_ASSERT_NOT_NULL(test, param);
 214
 215         /* Test can be skipped on unsupported param values */
 216         if (!param->value)
 217                 kunit_skip(test, "unsupported param value");
 218
 219         /* You can use param values for parameterized testing */
 220         KUNIT_EXPECT_EQ(test, param->value % param->value, 0);
 221 }
 222
 223 /*
 224  * This test should always pass. Can be used to practice filtering attributes.
 225  */
 226 static void example_slow_test(struct kunit *test)
 227 {
 228         KUNIT_EXPECT_EQ(test, 1 + 1, 2);
 229 }
 230
 231 /*
 232  * Here we make a list of all the test cases we want to add to the test suite
 233  * below.
 234  */
 235 static struct kunit_case example_test_cases[] = {
 236         /*
 237          * This is a helper to create a test case object from a test case
 238          * function; its exact function is not important to understand how to
 239          * use KUnit, just know that this is how you associate test cases with a
 240          * test suite.
 241          */
 242         KUNIT_CASE(example_simple_test),
 243         KUNIT_CASE(example_skip_test),
 244         KUNIT_CASE(example_mark_skipped_test),
 245         KUNIT_CASE(example_all_expect_macros_test),
 246         KUNIT_CASE(example_static_stub_test),
 247         KUNIT_CASE_PARAM(example_params_test, example_gen_params),
 248         KUNIT_CASE_SLOW(example_slow_test),
 249         {}
 250 };
 251
 252 /*
 253  * This defines a suite or grouping of tests.
 254  *
 255  * Test cases are defined as belonging to the suite by adding them to
 256  * `kunit_cases`.
 257  *
 258  * Often it is desirable to run some function which will set up things which
 259  * will be used by every test; this is accomplished with an `init` function
 260  * which runs before each test case is invoked. Similarly, an `exit` function
 261  * may be specified which runs after every test case and can be used to for
 262  * cleanup. For clarity, running tests in a test suite would behave as follows:
 263  *
 264  * suite.suite_init(suite);
 265  * suite.init(test);
 266  * suite.test_case[0](test);
 267  * suite.exit(test);
 268  * suite.init(test);
 269  * suite.test_case[1](test);
 270  * suite.exit(test);
 271  * suite.suite_exit(suite);
 272  * ...;
 273  */
 274 static struct kunit_suite example_test_suite = {
 275         .name = "example",
 276         .init = example_test_init,
 277         .exit = example_test_exit,
 278         .suite_init = example_test_init_suite,
 279         .suite_exit = example_test_exit_suite,
 280         .test_cases = example_test_cases,
 281 };
 282
 283 /*
 284  * This registers the above test suite telling KUnit that this is a suite of
 285  * tests that need to be run.
 286  */
 287 kunit_test_suites(&example_test_suite);
 288
 289 MODULE_LICENSE("GPL v2");