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 * This custom function allocates memory and sets the information we want 282 * stored in the kunit_resource->data field. 283 */ 284 static int example_resource_init(struct kunit_resource *res, void *context) 285 { 286 int *info = kmalloc(sizeof(*info), GFP_KERNEL); 287 288 if (!info) 289 return -ENOMEM; 290 *info = *(int *)context; 291 res->data = info; 292 return 0; 293 } 294 295 /* 296 * This function deallocates memory for the kunit_resource->data field. 297 */ 298 static void example_resource_free(struct kunit_resource *res) 299 { 300 kfree(res->data); 301 } 302 303 /* 304 * This match function is invoked by kunit_find_resource() to locate 305 * a test resource based on certain criteria. 306 */ 307 static bool example_resource_alloc_match(struct kunit *test, 308 struct kunit_resource *res, 309 void *match_data) 310 { 311 return res->data && res->free == example_resource_free; 312 } 313 314 /* 315 * This is an example of a function that provides a description for each of the 316 * parameters in a parameterized test. 317 */ 318 static void example_param_array_get_desc(struct kunit *test, const void *p, char *desc) 319 { 320 const struct example_param *param = p; 321 322 snprintf(desc, KUNIT_PARAM_DESC_SIZE, 323 "example check if %d is less than or equal to 3", param->value); 324 } 325 326 /* 327 * This function gets passed in the parameterized test context i.e. the 328 * struct kunit belonging to the parameterized test. You can use this function 329 * to add resources you want shared across the whole parameterized test or 330 * for additional setup. 331 */ 332 static int example_param_init(struct kunit *test) 333 { 334 int ctx = 3; /* Data to be stored. */ 335 size_t arr_size = ARRAY_SIZE(example_params_array); 336 337 /* 338 * This allocates a struct kunit_resource, sets its data field to 339 * ctx, and adds it to the struct kunit's resources list. Note that 340 * this is parameterized test managed. So, it doesn't need to have 341 * a custom exit function to deallocation as it will get cleaned up at 342 * the end of the parameterized test. 343 */ 344 void *data = kunit_alloc_resource(test, example_resource_init, example_resource_free, 345 GFP_KERNEL, &ctx); 346 347 if (!data) 348 return -ENOMEM; 349 /* 350 * Pass the parameter array information to the parameterized test context 351 * struct kunit. Note that you will need to provide kunit_array_gen_params() 352 * as the generator function to KUNIT_CASE_PARAM_WITH_INIT() when registering 353 * a parameter array this route. 354 */ 355 kunit_register_params_array(test, example_params_array, arr_size, 356 example_param_array_get_desc); 357 return 0; 358 } 359 360 /* 361 * This is an example of a test that uses shared resources available in the 362 * parameterized test context. 363 */ 364 static void example_params_test_with_init(struct kunit *test) 365 { 366 int threshold; 367 struct kunit_resource *res; 368 const struct example_param *param = test->param_value; 369 370 /* By design, param pointer will not be NULL. */ 371 KUNIT_ASSERT_NOT_NULL(test, param); 372 373 /* 374 * Here we pass test->parent to search for shared resources in the 375 * parameterized test context. 376 */ 377 res = kunit_find_resource(test->parent, example_resource_alloc_match, NULL); 378 379 KUNIT_ASSERT_NOT_NULL(test, res); 380 381 /* Since kunit_resource->data is a void pointer we need to typecast it. */ 382 threshold = *((int *)res->data); 383 384 /* Assert that the parameter is less than or equal to a certain threshold. */ 385 KUNIT_ASSERT_LE(test, param->value, threshold); 386 387 /* This decreases the reference count after calling kunit_find_resource(). */ 388 kunit_put_resource(res); 389 } 390 391 /* 392 * Helper function to create a parameter array of Fibonacci numbers. This example 393 * highlights a parameter generation scenario that is: 394 * 1. Not feasible to fully pre-generate at compile time. 395 * 2. Challenging to implement with a standard generate_params() function, 396 * as it only provides the previous parameter, while Fibonacci requires 397 * access to two preceding values for calculation. 398 */ 399 static void *make_fibonacci_params(struct kunit *test, size_t seq_size) 400 { 401 int *seq; 402 403 if (seq_size <= 0) 404 return NULL; 405 /* 406 * Using kunit_kmalloc_array here ties the lifetime of the array to 407 * the parameterized test i.e. it will get automatically cleaned up 408 * by KUnit after the parameterized test finishes. 409 */ 410 seq = kunit_kmalloc_array(test, seq_size, sizeof(int), GFP_KERNEL); 411 412 if (!seq) 413 return NULL; 414 if (seq_size >= 1) 415 seq[0] = 0; 416 if (seq_size >= 2) 417 seq[1] = 1; 418 for (int i = 2; i < seq_size; i++) 419 seq[i] = seq[i - 1] + seq[i - 2]; 420 return seq; 421 } 422 423 /* 424 * This is an example of a function that provides a description for each of the 425 * parameters. 426 */ 427 static void example_param_dynamic_arr_get_desc(struct kunit *test, const void *p, char *desc) 428 { 429 const int *fib_num = p; 430 431 snprintf(desc, KUNIT_PARAM_DESC_SIZE, "fibonacci param: %d", *fib_num); 432 } 433 434 /* 435 * Example of a parameterized test param_init() function that registers a dynamic 436 * array of parameters. 437 */ 438 static int example_param_init_dynamic_arr(struct kunit *test) 439 { 440 size_t seq_size; 441 int *fibonacci_params; 442 443 kunit_info(test, "initializing parameterized test\n"); 444 445 seq_size = 6; 446 fibonacci_params = make_fibonacci_params(test, seq_size); 447 448 if (!fibonacci_params) 449 return -ENOMEM; 450 451 /* 452 * Passes the dynamic parameter array information to the parameterized test 453 * context struct kunit. The array and its metadata will be stored in 454 * test->parent->params_array. The array itself will be located in 455 * params_data.params. 456 * 457 * Note that you will need to pass kunit_array_gen_params() as the 458 * generator function to KUNIT_CASE_PARAM_WITH_INIT() when registering 459 * a parameter array this route. 460 */ 461 kunit_register_params_array(test, fibonacci_params, seq_size, 462 example_param_dynamic_arr_get_desc); 463 return 0; 464 } 465 466 /* 467 * Example of a parameterized test param_exit() function that outputs a log 468 * at the end of the parameterized test. It could also be used for any other 469 * teardown logic. 470 */ 471 static void example_param_exit_dynamic_arr(struct kunit *test) 472 { 473 kunit_info(test, "exiting parameterized test\n"); 474 } 475 476 /* 477 * Example of test that uses the registered dynamic array to perform assertions 478 * and expectations. 479 */ 480 static void example_params_test_with_init_dynamic_arr(struct kunit *test) 481 { 482 const int *param = test->param_value; 483 int param_val; 484 485 /* By design, param pointer will not be NULL. */ 486 KUNIT_ASSERT_NOT_NULL(test, param); 487 488 param_val = *param; 489 KUNIT_EXPECT_EQ(test, param_val - param_val, 0); 490 } 491 492 /* 493 * Here we make a list of all the test cases we want to add to the test suite 494 * below. 495 */ 496 static struct kunit_case example_test_cases[] = { 497 /* 498 * This is a helper to create a test case object from a test case 499 * function; its exact function is not important to understand how to 500 * use KUnit, just know that this is how you associate test cases with a 501 * test suite. 502 */ 503 KUNIT_CASE(example_simple_test), 504 KUNIT_CASE(example_skip_test), 505 KUNIT_CASE(example_mark_skipped_test), 506 KUNIT_CASE(example_all_expect_macros_test), 507 KUNIT_CASE(example_static_stub_test), 508 KUNIT_CASE(example_static_stub_using_fn_ptr_test), 509 KUNIT_CASE(example_priv_test), 510 KUNIT_CASE_PARAM(example_params_test, example_gen_params), 511 KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, kunit_array_gen_params, 512 example_param_init, NULL), 513 KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_dynamic_arr, 514 kunit_array_gen_params, example_param_init_dynamic_arr, 515 example_param_exit_dynamic_arr), 516 KUNIT_CASE_SLOW(example_slow_test), 517 {} 518 }; 519 520 /* 521 * This defines a suite or grouping of tests. 522 * 523 * Test cases are defined as belonging to the suite by adding them to 524 * `kunit_cases`. 525 * 526 * Often it is desirable to run some function which will set up things which 527 * will be used by every test; this is accomplished with an `init` function 528 * which runs before each test case is invoked. Similarly, an `exit` function 529 * may be specified which runs after every test case and can be used to for 530 * cleanup. For clarity, running tests in a test suite would behave as follows: 531 * 532 * suite.suite_init(suite); 533 * suite.init(test); 534 * suite.test_case[0](test); 535 * suite.exit(test); 536 * suite.init(test); 537 * suite.test_case[1](test); 538 * suite.exit(test); 539 * suite.suite_exit(suite); 540 * ...; 541 */ 542 static struct kunit_suite example_test_suite = { 543 .name = "example", 544 .init = example_test_init, 545 .exit = example_test_exit, 546 .suite_init = example_test_init_suite, 547 .suite_exit = example_test_exit_suite, 548 .test_cases = example_test_cases, 549 }; 550 551 /* 552 * This registers the above test suite telling KUnit that this is a suite of 553 * tests that need to be run. 554 */ 555 kunit_test_suites(&example_test_suite); 556 557 static int __init init_add(int x, int y) 558 { 559 return (x + y); 560 } 561 562 /* 563 * This test should always pass. Can be used to test init suites. 564 */ 565 static void __init example_init_test(struct kunit *test) 566 { 567 KUNIT_EXPECT_EQ(test, init_add(1, 1), 2); 568 } 569 570 /* 571 * The kunit_case struct cannot be marked as __initdata as this will be 572 * used in debugfs to retrieve results after test has run 573 */ 574 static struct kunit_case __refdata example_init_test_cases[] = { 575 KUNIT_CASE(example_init_test), 576 {} 577 }; 578 579 /* 580 * The kunit_suite struct cannot be marked as __initdata as this will be 581 * used in debugfs to retrieve results after test has run 582 */ 583 static struct kunit_suite example_init_test_suite = { 584 .name = "example_init", 585 .test_cases = example_init_test_cases, 586 }; 587 588 /* 589 * This registers the test suite and marks the suite as using init data 590 * and/or functions. 591 */ 592 kunit_test_init_section_suites(&example_init_test_suite); 593 594 MODULE_DESCRIPTION("Example KUnit test suite"); 595 MODULE_LICENSE("GPL v2"); 596