xref: /linux/lib/kunit/kunit-example-test.c (revision 30bbcb44707a97fcb62246bebc8b413b5ab293f8)
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