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 */
example_simple_test(struct kunit * test)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 */
example_test_init(struct kunit * test)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 */
example_test_exit(struct kunit * test)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 */
example_test_init_suite(struct kunit_suite * suite)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 */
example_test_exit_suite(struct kunit_suite * suite)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 */
example_skip_test(struct kunit * test)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 */
example_mark_skipped_test(struct kunit * test)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 */
example_all_expect_macros_test(struct kunit * test)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. */
add_one(int i)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. */
subtract_one(int i)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 */
example_static_stub_test(struct kunit * test)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 */
example_static_stub_using_fn_ptr_test(struct kunit * test)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
example_param_get_desc(const struct example_param * p,char * desc)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 */
example_params_test(struct kunit * test)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 */
example_priv_test(struct kunit * test)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 */
example_slow_test(struct kunit * test)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
init_add(int x,int y)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 */
example_init_test(struct kunit * test)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_DESCRIPTION("Example KUnit test suite");
378 MODULE_LICENSE("GPL v2");
379