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  * If the function to be replaced is static within a module it is
 173  * useful to export a pointer to that function instead of having
 174  * to change the static function to a non-static exported function.
 175  *
 176  * This pointer simulates a module exporting a pointer to a static
 177  * function.
 178  */
 179 static int (* const add_one_fn_ptr)(int i) = add_one;
 180
 181 /*
 182  * This test shows the use of static stubs.
 183  */
 184 static void example_static_stub_test(struct kunit *test)
 185 {
 186         /* By default, function is not stubbed. */
 187         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 188
 189         /* Replace add_one() with subtract_one(). */
 190         kunit_activate_static_stub(test, add_one, subtract_one);
 191
 192         /* add_one() is now replaced. */
 193         KUNIT_EXPECT_EQ(test, add_one(1), 0);
 194
 195         /* Return add_one() to normal. */
 196         kunit_deactivate_static_stub(test, add_one);
 197         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 198 }
 199
 200 /*
 201  * This test shows the use of static stubs when the function being
 202  * replaced is provided as a pointer-to-function instead of the
 203  * actual function. This is useful for providing access to static
 204  * functions in a module by exporting a pointer to that function
 205  * instead of having to change the static function to a non-static
 206  * exported function.
 207  */
 208 static void example_static_stub_using_fn_ptr_test(struct kunit *test)
 209 {
 210         /* By default, function is not stubbed. */
 211         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 212
 213         /* Replace add_one() with subtract_one(). */
 214         kunit_activate_static_stub(test, add_one_fn_ptr, subtract_one);
 215
 216         /* add_one() is now replaced. */
 217         KUNIT_EXPECT_EQ(test, add_one(1), 0);
 218
 219         /* Return add_one() to normal. */
 220         kunit_deactivate_static_stub(test, add_one_fn_ptr);
 221         KUNIT_EXPECT_EQ(test, add_one(1), 2);
 222 }
 223
 224 static const struct example_param {
 225         int value;
 226 } example_params_array[] = {
 227         { .value = 3, },
 228         { .value = 2, },
 229         { .value = 1, },
 230         { .value = 0, },
 231 };
 232
 233 static void example_param_get_desc(const struct example_param *p, char *desc)
 234 {
 235         snprintf(desc, KUNIT_PARAM_DESC_SIZE, "example value %d", p->value);
 236 }
 237
 238 KUNIT_ARRAY_PARAM(example, example_params_array, example_param_get_desc);
 239
 240 /*
 241  * This test shows the use of params.
 242  */
 243 static void example_params_test(struct kunit *test)
 244 {
 245         const struct example_param *param = test->param_value;
 246
 247         /* By design, param pointer will not be NULL */
 248         KUNIT_ASSERT_NOT_NULL(test, param);
 249
 250         /* Test can be skipped on unsupported param values */
 251         if (!is_power_of_2(param->value))
 252                 kunit_skip(test, "unsupported param value %d", param->value);
 253
 254         /* You can use param values for parameterized testing */
 255         KUNIT_EXPECT_EQ(test, param->value % param->value, 0);
 256 }
 257
 258 /*
 259  * This test shows the use of test->priv.
 260  */
 261 static void example_priv_test(struct kunit *test)
 262 {
 263         /* unless setup in suite->init(), test->priv is NULL */
 264         KUNIT_ASSERT_NULL(test, test->priv);
 265
 266         /* but can be used to pass arbitrary data to other functions */
 267         test->priv = kunit_kzalloc(test, 1, GFP_KERNEL);
 268         KUNIT_EXPECT_NOT_NULL(test, test->priv);
 269         KUNIT_ASSERT_PTR_EQ(test, test->priv, kunit_get_current_test()->priv);
 270 }
 271
 272 /*
 273  * This test should always pass. Can be used to practice filtering attributes.
 274  */
 275 static void example_slow_test(struct kunit *test)
 276 {
 277         KUNIT_EXPECT_EQ(test, 1 + 1, 2);
 278 }
 279
 280 /*
 281  * Here we make a list of all the test cases we want to add to the test suite
 282  * below.
 283  */
 284 static struct kunit_case example_test_cases[] = {
 285         /*
 286          * This is a helper to create a test case object from a test case
 287          * function; its exact function is not important to understand how to
 288          * use KUnit, just know that this is how you associate test cases with a
 289          * test suite.
 290          */
 291         KUNIT_CASE(example_simple_test),
 292         KUNIT_CASE(example_skip_test),
 293         KUNIT_CASE(example_mark_skipped_test),
 294         KUNIT_CASE(example_all_expect_macros_test),
 295         KUNIT_CASE(example_static_stub_test),
 296         KUNIT_CASE(example_static_stub_using_fn_ptr_test),
 297         KUNIT_CASE(example_priv_test),
 298         KUNIT_CASE_PARAM(example_params_test, example_gen_params),
 299         KUNIT_CASE_SLOW(example_slow_test),
 300         {}
 301 };
 302
 303 /*
 304  * This defines a suite or grouping of tests.
 305  *
 306  * Test cases are defined as belonging to the suite by adding them to
 307  * `kunit_cases`.
 308  *
 309  * Often it is desirable to run some function which will set up things which
 310  * will be used by every test; this is accomplished with an `init` function
 311  * which runs before each test case is invoked. Similarly, an `exit` function
 312  * may be specified which runs after every test case and can be used to for
 313  * cleanup. For clarity, running tests in a test suite would behave as follows:
 314  *
 315  * suite.suite_init(suite);
 316  * suite.init(test);
 317  * suite.test_case[0](test);
 318  * suite.exit(test);
 319  * suite.init(test);
 320  * suite.test_case[1](test);
 321  * suite.exit(test);
 322  * suite.suite_exit(suite);
 323  * ...;
 324  */
 325 static struct kunit_suite example_test_suite = {
 326         .name = "example",
 327         .init = example_test_init,
 328         .exit = example_test_exit,
 329         .suite_init = example_test_init_suite,
 330         .suite_exit = example_test_exit_suite,
 331         .test_cases = example_test_cases,
 332 };
 333
 334 /*
 335  * This registers the above test suite telling KUnit that this is a suite of
 336  * tests that need to be run.
 337  */
 338 kunit_test_suites(&example_test_suite);
 339
 340 static int __init init_add(int x, int y)
 341 {
 342         return (x + y);
 343 }
 344
 345 /*
 346  * This test should always pass. Can be used to test init suites.
 347  */
 348 static void __init example_init_test(struct kunit *test)
 349 {
 350         KUNIT_EXPECT_EQ(test, init_add(1, 1), 2);
 351 }
 352
 353 /*
 354  * The kunit_case struct cannot be marked as __initdata as this will be
 355  * used in debugfs to retrieve results after test has run
 356  */
 357 static struct kunit_case __refdata example_init_test_cases[] = {
 358         KUNIT_CASE(example_init_test),
 359         {}
 360 };
 361
 362 /*
 363  * The kunit_suite struct cannot be marked as __initdata as this will be
 364  * used in debugfs to retrieve results after test has run
 365  */
 366 static struct kunit_suite example_init_test_suite = {
 367         .name = "example_init",
 368         .test_cases = example_init_test_cases,
 369 };
 370
 371 /*
 372  * This registers the test suite and marks the suite as using init data
 373  * and/or functions.
 374  */
 375 kunit_test_init_section_suites(&example_init_test_suite);
 376
 377 MODULE_LICENSE("GPL v2");