projects/linux·blob master · refs

624 lines · 17.5 KiB

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 <[email protected]>
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 */
22static 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 */
37static 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 */
48static 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 */
58static 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 */
69static 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 */
78static 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 */
93static 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 */
108static 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. */
155static 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. */
164static 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 */
179static int (* const add_one_fn_ptr)(int i) = add_one;
180
181/*
182 * This test shows the use of static stubs.
183 */
184static 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 */
208static 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
224static 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
233static 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
238KUNIT_ARRAY_PARAM(example, example_params_array, example_param_get_desc);
239
240/*
241 * This test shows the use of params.
242 */
243static 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 */
261static 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 */
275static 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 */
284static int example_resource_init(struct kunit_resource *res, void *context)
285{
286 int *info = kmalloc_obj(*info);
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 */
298static 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 */
307static 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 */
318static 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 */
332static 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 */
364static 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 */
399static 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 */
427static 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 */
438static 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 */
471static 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 */
480static 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 */
496static 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 */
542static 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 */
555kunit_test_suites(&example_test_suite);
556
557static 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 */
565static 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 */
574static 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 */
583static 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 */
592kunit_test_init_section_suites(&example_init_test_suite);
593
594/*
595 * This test should always be skipped.
596 */
597static void example_skip_suite_test(struct kunit *test)
598{
599 /* This line should never be seen */
600 KUNIT_FAIL(test, "You should not see a this.");
601}
602
603static struct kunit_case example_skip_suite_test_cases[] = {
604 KUNIT_CASE(example_skip_suite_test),
605 {}
606};
607
608static int example_skip_suite_init(struct kunit_suite *suite)
609{
610 kunit_mark_skipped(suite, "Test suite expected to be skipped");
611 return 0;
612}
613
614static struct kunit_suite example_test_skip_suite = {
615 .name = "example_skip_suite",
616 .suite_init = example_skip_suite_init,
617 .test_cases = example_skip_suite_test_cases,
618};
619
620/* This registers a test suite that will be skipped */
621kunit_test_suite(example_test_skip_suite);
622
623MODULE_DESCRIPTION("Example KUnit test suite");
624MODULE_LICENSE("GPL v2");