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 */ 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 * This test shows the use of static stubs. 173 */ 174 static 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 190 static const struct example_param { 191 int value; 192 } example_params_array[] = { 193 { .value = 3, }, 194 { .value = 2, }, 195 { .value = 1, }, 196 { .value = 0, }, 197 }; 198 199 static void example_param_get_desc(const struct example_param *p, char *desc) 200 { 201 snprintf(desc, KUNIT_PARAM_DESC_SIZE, "example value %d", p->value); 202 } 203 204 KUNIT_ARRAY_PARAM(example, example_params_array, example_param_get_desc); 205 206 /* 207 * This test shows the use of params. 208 */ 209 static void example_params_test(struct kunit *test) 210 { 211 const struct example_param *param = test->param_value; 212 213 /* By design, param pointer will not be NULL */ 214 KUNIT_ASSERT_NOT_NULL(test, param); 215 216 /* Test can be skipped on unsupported param values */ 217 if (!is_power_of_2(param->value)) 218 kunit_skip(test, "unsupported param value %d", param->value); 219 220 /* You can use param values for parameterized testing */ 221 KUNIT_EXPECT_EQ(test, param->value % param->value, 0); 222 } 223 224 /* 225 * This test shows the use of test->priv. 226 */ 227 static void example_priv_test(struct kunit *test) 228 { 229 /* unless setup in suite->init(), test->priv is NULL */ 230 KUNIT_ASSERT_NULL(test, test->priv); 231 232 /* but can be used to pass arbitrary data to other functions */ 233 test->priv = kunit_kzalloc(test, 1, GFP_KERNEL); 234 KUNIT_EXPECT_NOT_NULL(test, test->priv); 235 KUNIT_ASSERT_PTR_EQ(test, test->priv, kunit_get_current_test()->priv); 236 } 237 238 /* 239 * This test should always pass. Can be used to practice filtering attributes. 240 */ 241 static void example_slow_test(struct kunit *test) 242 { 243 KUNIT_EXPECT_EQ(test, 1 + 1, 2); 244 } 245 246 /* 247 * Here we make a list of all the test cases we want to add to the test suite 248 * below. 249 */ 250 static struct kunit_case example_test_cases[] = { 251 /* 252 * This is a helper to create a test case object from a test case 253 * function; its exact function is not important to understand how to 254 * use KUnit, just know that this is how you associate test cases with a 255 * test suite. 256 */ 257 KUNIT_CASE(example_simple_test), 258 KUNIT_CASE(example_skip_test), 259 KUNIT_CASE(example_mark_skipped_test), 260 KUNIT_CASE(example_all_expect_macros_test), 261 KUNIT_CASE(example_static_stub_test), 262 KUNIT_CASE(example_priv_test), 263 KUNIT_CASE_PARAM(example_params_test, example_gen_params), 264 KUNIT_CASE_SLOW(example_slow_test), 265 {} 266 }; 267 268 /* 269 * This defines a suite or grouping of tests. 270 * 271 * Test cases are defined as belonging to the suite by adding them to 272 * `kunit_cases`. 273 * 274 * Often it is desirable to run some function which will set up things which 275 * will be used by every test; this is accomplished with an `init` function 276 * which runs before each test case is invoked. Similarly, an `exit` function 277 * may be specified which runs after every test case and can be used to for 278 * cleanup. For clarity, running tests in a test suite would behave as follows: 279 * 280 * suite.suite_init(suite); 281 * suite.init(test); 282 * suite.test_case[0](test); 283 * suite.exit(test); 284 * suite.init(test); 285 * suite.test_case[1](test); 286 * suite.exit(test); 287 * suite.suite_exit(suite); 288 * ...; 289 */ 290 static struct kunit_suite example_test_suite = { 291 .name = "example", 292 .init = example_test_init, 293 .exit = example_test_exit, 294 .suite_init = example_test_init_suite, 295 .suite_exit = example_test_exit_suite, 296 .test_cases = example_test_cases, 297 }; 298 299 /* 300 * This registers the above test suite telling KUnit that this is a suite of 301 * tests that need to be run. 302 */ 303 kunit_test_suites(&example_test_suite); 304 305 static int __init init_add(int x, int y) 306 { 307 return (x + y); 308 } 309 310 /* 311 * This test should always pass. Can be used to test init suites. 312 */ 313 static void __init example_init_test(struct kunit *test) 314 { 315 KUNIT_EXPECT_EQ(test, init_add(1, 1), 2); 316 } 317 318 /* 319 * The kunit_case struct cannot be marked as __initdata as this will be 320 * used in debugfs to retrieve results after test has run 321 */ 322 static struct kunit_case __refdata example_init_test_cases[] = { 323 KUNIT_CASE(example_init_test), 324 {} 325 }; 326 327 /* 328 * The kunit_suite struct cannot be marked as __initdata as this will be 329 * used in debugfs to retrieve results after test has run 330 */ 331 static struct kunit_suite example_init_test_suite = { 332 .name = "example_init", 333 .test_cases = example_init_test_cases, 334 }; 335 336 /* 337 * This registers the test suite and marks the suite as using init data 338 * and/or functions. 339 */ 340 kunit_test_init_section_suites(&example_init_test_suite); 341 342 MODULE_LICENSE("GPL v2"); 343