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 */
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 * This test shows the use of static stubs.
173 */
174static void example_static_stub_test(struct kunit *test)
175{
176	/* By default, function is not stubbed. */
177	KUNIT_EXPECT_EQ(test, add_one(1), 2);
178
179	/* Replace add_one() with subtract_one(). */
180	kunit_activate_static_stub(test, add_one, subtract_one);
181
182	/* add_one() is now replaced. */
183	KUNIT_EXPECT_EQ(test, add_one(1), 0);
184
185	/* Return add_one() to normal. */
186	kunit_deactivate_static_stub(test, add_one);
187	KUNIT_EXPECT_EQ(test, add_one(1), 2);
188}
189
190static const struct example_param {
191	int value;
192} example_params_array[] = {
193	{ .value = 2, },
194	{ .value = 1, },
195	{ .value = 0, },
196};
197
198static void example_param_get_desc(const struct example_param *p, char *desc)
199{
200	snprintf(desc, KUNIT_PARAM_DESC_SIZE, "example value %d", p->value);
201}
202
203KUNIT_ARRAY_PARAM(example, example_params_array, example_param_get_desc);
204
205/*
206 * This test shows the use of params.
207 */
208static void example_params_test(struct kunit *test)
209{
210	const struct example_param *param = test->param_value;
211
212	/* By design, param pointer will not be NULL */
213	KUNIT_ASSERT_NOT_NULL(test, param);
214
215	/* Test can be skipped on unsupported param values */
216	if (!param->value)
217		kunit_skip(test, "unsupported param value");
218
219	/* You can use param values for parameterized testing */
220	KUNIT_EXPECT_EQ(test, param->value % param->value, 0);
221}
222
223/*
224 * This test should always pass. Can be used to practice filtering attributes.
225 */
226static void example_slow_test(struct kunit *test)
227{
228	KUNIT_EXPECT_EQ(test, 1 + 1, 2);
229}
230
231/*
232 * Here we make a list of all the test cases we want to add to the test suite
233 * below.
234 */
235static struct kunit_case example_test_cases[] = {
236	/*
237	 * This is a helper to create a test case object from a test case
238	 * function; its exact function is not important to understand how to
239	 * use KUnit, just know that this is how you associate test cases with a
240	 * test suite.
241	 */
242	KUNIT_CASE(example_simple_test),
243	KUNIT_CASE(example_skip_test),
244	KUNIT_CASE(example_mark_skipped_test),
245	KUNIT_CASE(example_all_expect_macros_test),
246	KUNIT_CASE(example_static_stub_test),
247	KUNIT_CASE_PARAM(example_params_test, example_gen_params),
248	KUNIT_CASE_SLOW(example_slow_test),
249	{}
250};
251
252/*
253 * This defines a suite or grouping of tests.
254 *
255 * Test cases are defined as belonging to the suite by adding them to
256 * `kunit_cases`.
257 *
258 * Often it is desirable to run some function which will set up things which
259 * will be used by every test; this is accomplished with an `init` function
260 * which runs before each test case is invoked. Similarly, an `exit` function
261 * may be specified which runs after every test case and can be used to for
262 * cleanup. For clarity, running tests in a test suite would behave as follows:
263 *
264 * suite.suite_init(suite);
265 * suite.init(test);
266 * suite.test_case[0](test);
267 * suite.exit(test);
268 * suite.init(test);
269 * suite.test_case[1](test);
270 * suite.exit(test);
271 * suite.suite_exit(suite);
272 * ...;
273 */
274static struct kunit_suite example_test_suite = {
275	.name = "example",
276	.init = example_test_init,
277	.exit = example_test_exit,
278	.suite_init = example_test_init_suite,
279	.suite_exit = example_test_exit_suite,
280	.test_cases = example_test_cases,
281};
282
283/*
284 * This registers the above test suite telling KUnit that this is a suite of
285 * tests that need to be run.
286 */
287kunit_test_suites(&example_test_suite);
288
289MODULE_LICENSE("GPL v2");
290