Commit | Line | Data |
---|---|---|
d8e2a76b BH |
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> | |
e047c5ea | 10 | #include <kunit/static_stub.h> |
d8e2a76b BH |
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 | ||
1cdba21d DL |
44 | /* |
45 | * This is run once before all test cases in the suite. | |
46 | * See the comment on example_test_suite for more information. | |
47 | */ | |
48 | static int example_test_init_suite(struct kunit_suite *suite) | |
49 | { | |
50 | kunit_info(suite, "initializing suite\n"); | |
51 | ||
52 | return 0; | |
53 | } | |
54 | ||
d99ea675 DG |
55 | /* |
56 | * This test should always be skipped. | |
57 | */ | |
58 | static void example_skip_test(struct kunit *test) | |
59 | { | |
60 | /* This line should run */ | |
61 | kunit_info(test, "You should not see a line below."); | |
62 | ||
63 | /* Skip (and abort) the test */ | |
64 | kunit_skip(test, "this test should be skipped"); | |
65 | ||
66 | /* This line should not execute */ | |
67 | KUNIT_FAIL(test, "You should not see this line."); | |
68 | } | |
69 | ||
70 | /* | |
71 | * This test should always be marked skipped. | |
72 | */ | |
73 | static void example_mark_skipped_test(struct kunit *test) | |
74 | { | |
75 | /* This line should run */ | |
76 | kunit_info(test, "You should see a line below."); | |
77 | ||
78 | /* Skip (but do not abort) the test */ | |
79 | kunit_mark_skipped(test, "this test should be skipped"); | |
80 | ||
81 | /* This line should run */ | |
82 | kunit_info(test, "You should see this line."); | |
83 | } | |
7b339105 DL |
84 | |
85 | /* | |
86 | * This test shows off all the types of KUNIT_EXPECT macros. | |
87 | */ | |
88 | static void example_all_expect_macros_test(struct kunit *test) | |
89 | { | |
3b30fb62 MC |
90 | const u32 array1[] = { 0x0F, 0xFF }; |
91 | const u32 array2[] = { 0x1F, 0xFF }; | |
92 | ||
7b339105 DL |
93 | /* Boolean assertions */ |
94 | KUNIT_EXPECT_TRUE(test, true); | |
95 | KUNIT_EXPECT_FALSE(test, false); | |
96 | ||
97 | /* Integer assertions */ | |
98 | KUNIT_EXPECT_EQ(test, 1, 1); /* check == */ | |
99 | KUNIT_EXPECT_GE(test, 1, 1); /* check >= */ | |
100 | KUNIT_EXPECT_LE(test, 1, 1); /* check <= */ | |
101 | KUNIT_EXPECT_NE(test, 1, 0); /* check != */ | |
102 | KUNIT_EXPECT_GT(test, 1, 0); /* check > */ | |
103 | KUNIT_EXPECT_LT(test, 0, 1); /* check < */ | |
104 | ||
105 | /* Pointer assertions */ | |
106 | KUNIT_EXPECT_NOT_ERR_OR_NULL(test, test); | |
107 | KUNIT_EXPECT_PTR_EQ(test, NULL, NULL); | |
108 | KUNIT_EXPECT_PTR_NE(test, test, NULL); | |
de82c15d RR |
109 | KUNIT_EXPECT_NULL(test, NULL); |
110 | KUNIT_EXPECT_NOT_NULL(test, test); | |
7b339105 DL |
111 | |
112 | /* String assertions */ | |
113 | KUNIT_EXPECT_STREQ(test, "hi", "hi"); | |
114 | KUNIT_EXPECT_STRNEQ(test, "hi", "bye"); | |
115 | ||
3b30fb62 MC |
116 | /* Memory block assertions */ |
117 | KUNIT_EXPECT_MEMEQ(test, array1, array1, sizeof(array1)); | |
118 | KUNIT_EXPECT_MEMNEQ(test, array1, array2, sizeof(array1)); | |
119 | ||
7b339105 DL |
120 | /* |
121 | * There are also ASSERT variants of all of the above that abort test | |
122 | * execution if they fail. Useful for memory allocations, etc. | |
123 | */ | |
124 | KUNIT_ASSERT_GT(test, sizeof(char), 0); | |
125 | ||
126 | /* | |
127 | * There are also _MSG variants of all of the above that let you include | |
128 | * additional text on failure. | |
129 | */ | |
130 | KUNIT_EXPECT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!"); | |
131 | KUNIT_ASSERT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!"); | |
132 | } | |
133 | ||
e047c5ea DG |
134 | /* This is a function we'll replace with static stubs. */ |
135 | static int add_one(int i) | |
136 | { | |
137 | /* This will trigger the stub if active. */ | |
138 | KUNIT_STATIC_STUB_REDIRECT(add_one, i); | |
139 | ||
140 | return i + 1; | |
141 | } | |
142 | ||
143 | /* This is used as a replacement for the above function. */ | |
144 | static int subtract_one(int i) | |
145 | { | |
146 | /* We don't need to trigger the stub from the replacement. */ | |
147 | ||
148 | return i - 1; | |
149 | } | |
150 | ||
151 | /* | |
152 | * This test shows the use of static stubs. | |
153 | */ | |
154 | static void example_static_stub_test(struct kunit *test) | |
155 | { | |
156 | /* By default, function is not stubbed. */ | |
157 | KUNIT_EXPECT_EQ(test, add_one(1), 2); | |
158 | ||
159 | /* Replace add_one() with subtract_one(). */ | |
160 | kunit_activate_static_stub(test, add_one, subtract_one); | |
161 | ||
162 | /* add_one() is now replaced. */ | |
163 | KUNIT_EXPECT_EQ(test, add_one(1), 0); | |
164 | ||
165 | /* Return add_one() to normal. */ | |
166 | kunit_deactivate_static_stub(test, add_one); | |
167 | KUNIT_EXPECT_EQ(test, add_one(1), 2); | |
168 | } | |
169 | ||
d8e2a76b BH |
170 | /* |
171 | * Here we make a list of all the test cases we want to add to the test suite | |
172 | * below. | |
173 | */ | |
174 | static struct kunit_case example_test_cases[] = { | |
175 | /* | |
176 | * This is a helper to create a test case object from a test case | |
177 | * function; its exact function is not important to understand how to | |
178 | * use KUnit, just know that this is how you associate test cases with a | |
179 | * test suite. | |
180 | */ | |
181 | KUNIT_CASE(example_simple_test), | |
d99ea675 DG |
182 | KUNIT_CASE(example_skip_test), |
183 | KUNIT_CASE(example_mark_skipped_test), | |
7b339105 | 184 | KUNIT_CASE(example_all_expect_macros_test), |
e047c5ea | 185 | KUNIT_CASE(example_static_stub_test), |
d8e2a76b BH |
186 | {} |
187 | }; | |
188 | ||
189 | /* | |
190 | * This defines a suite or grouping of tests. | |
191 | * | |
192 | * Test cases are defined as belonging to the suite by adding them to | |
193 | * `kunit_cases`. | |
194 | * | |
195 | * Often it is desirable to run some function which will set up things which | |
196 | * will be used by every test; this is accomplished with an `init` function | |
197 | * which runs before each test case is invoked. Similarly, an `exit` function | |
198 | * may be specified which runs after every test case and can be used to for | |
199 | * cleanup. For clarity, running tests in a test suite would behave as follows: | |
200 | * | |
1cdba21d | 201 | * suite.suite_init(suite); |
d8e2a76b BH |
202 | * suite.init(test); |
203 | * suite.test_case[0](test); | |
204 | * suite.exit(test); | |
205 | * suite.init(test); | |
206 | * suite.test_case[1](test); | |
207 | * suite.exit(test); | |
1cdba21d | 208 | * suite.suite_exit(suite); |
d8e2a76b BH |
209 | * ...; |
210 | */ | |
211 | static struct kunit_suite example_test_suite = { | |
212 | .name = "example", | |
213 | .init = example_test_init, | |
1cdba21d | 214 | .suite_init = example_test_init_suite, |
d8e2a76b BH |
215 | .test_cases = example_test_cases, |
216 | }; | |
217 | ||
218 | /* | |
219 | * This registers the above test suite telling KUnit that this is a suite of | |
220 | * tests that need to be run. | |
221 | */ | |
c475c77d AM |
222 | kunit_test_suites(&example_test_suite); |
223 | ||
224 | MODULE_LICENSE("GPL v2"); |