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 11 /* 12 * This is the most fundamental element of KUnit, the test case. A test case 13 * makes a set EXPECTATIONs and ASSERTIONs about the behavior of some code; if 14 * any expectations or assertions are not met, the test fails; otherwise, the 15 * test passes. 16 * 17 * In KUnit, a test case is just a function with the signature 18 * `void (*)(struct kunit *)`. `struct kunit` is a context object that stores 19 * information about the current test. 20 */ 21 static void example_simple_test(struct kunit *test) 22 { 23 /* 24 * This is an EXPECTATION; it is how KUnit tests things. When you want 25 * to test a piece of code, you set some expectations about what the 26 * code should do. KUnit then runs the test and verifies that the code's 27 * behavior matched what was expected. 28 */ 29 KUNIT_EXPECT_EQ(test, 1 + 1, 2); 30 } 31 32 /* 33 * This is run once before each test case, see the comment on 34 * example_test_suite for more information. 35 */ 36 static int example_test_init(struct kunit *test) 37 { 38 kunit_info(test, "initializing\n"); 39 40 return 0; 41 } 42 43 /* 44 * This is run once before all test cases in the suite. 45 * See the comment on example_test_suite for more information. 46 */ 47 static int example_test_init_suite(struct kunit_suite *suite) 48 { 49 kunit_info(suite, "initializing suite\n"); 50 51 return 0; 52 } 53 54 /* 55 * This test should always be skipped. 56 */ 57 static void example_skip_test(struct kunit *test) 58 { 59 /* This line should run */ 60 kunit_info(test, "You should not see a line below."); 61 62 /* Skip (and abort) the test */ 63 kunit_skip(test, "this test should be skipped"); 64 65 /* This line should not execute */ 66 KUNIT_FAIL(test, "You should not see this line."); 67 } 68 69 /* 70 * This test should always be marked skipped. 71 */ 72 static void example_mark_skipped_test(struct kunit *test) 73 { 74 /* This line should run */ 75 kunit_info(test, "You should see a line below."); 76 77 /* Skip (but do not abort) the test */ 78 kunit_mark_skipped(test, "this test should be skipped"); 79 80 /* This line should run */ 81 kunit_info(test, "You should see this line."); 82 } 83 84 /* 85 * This test shows off all the types of KUNIT_EXPECT macros. 86 */ 87 static void example_all_expect_macros_test(struct kunit *test) 88 { 89 const u32 array1[] = { 0x0F, 0xFF }; 90 const u32 array2[] = { 0x1F, 0xFF }; 91 92 /* Boolean assertions */ 93 KUNIT_EXPECT_TRUE(test, true); 94 KUNIT_EXPECT_FALSE(test, false); 95 96 /* Integer assertions */ 97 KUNIT_EXPECT_EQ(test, 1, 1); /* check == */ 98 KUNIT_EXPECT_GE(test, 1, 1); /* check >= */ 99 KUNIT_EXPECT_LE(test, 1, 1); /* check <= */ 100 KUNIT_EXPECT_NE(test, 1, 0); /* check != */ 101 KUNIT_EXPECT_GT(test, 1, 0); /* check > */ 102 KUNIT_EXPECT_LT(test, 0, 1); /* check < */ 103 104 /* Pointer assertions */ 105 KUNIT_EXPECT_NOT_ERR_OR_NULL(test, test); 106 KUNIT_EXPECT_PTR_EQ(test, NULL, NULL); 107 KUNIT_EXPECT_PTR_NE(test, test, NULL); 108 KUNIT_EXPECT_NULL(test, NULL); 109 KUNIT_EXPECT_NOT_NULL(test, test); 110 111 /* String assertions */ 112 KUNIT_EXPECT_STREQ(test, "hi", "hi"); 113 KUNIT_EXPECT_STRNEQ(test, "hi", "bye"); 114 115 /* Memory block assertions */ 116 KUNIT_EXPECT_MEMEQ(test, array1, array1, sizeof(array1)); 117 KUNIT_EXPECT_MEMNEQ(test, array1, array2, sizeof(array1)); 118 119 /* 120 * There are also ASSERT variants of all of the above that abort test 121 * execution if they fail. Useful for memory allocations, etc. 122 */ 123 KUNIT_ASSERT_GT(test, sizeof(char), 0); 124 125 /* 126 * There are also _MSG variants of all of the above that let you include 127 * additional text on failure. 128 */ 129 KUNIT_EXPECT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!"); 130 KUNIT_ASSERT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!"); 131 } 132 133 /* 134 * Here we make a list of all the test cases we want to add to the test suite 135 * below. 136 */ 137 static struct kunit_case example_test_cases[] = { 138 /* 139 * This is a helper to create a test case object from a test case 140 * function; its exact function is not important to understand how to 141 * use KUnit, just know that this is how you associate test cases with a 142 * test suite. 143 */ 144 KUNIT_CASE(example_simple_test), 145 KUNIT_CASE(example_skip_test), 146 KUNIT_CASE(example_mark_skipped_test), 147 KUNIT_CASE(example_all_expect_macros_test), 148 {} 149 }; 150 151 /* 152 * This defines a suite or grouping of tests. 153 * 154 * Test cases are defined as belonging to the suite by adding them to 155 * `kunit_cases`. 156 * 157 * Often it is desirable to run some function which will set up things which 158 * will be used by every test; this is accomplished with an `init` function 159 * which runs before each test case is invoked. Similarly, an `exit` function 160 * may be specified which runs after every test case and can be used to for 161 * cleanup. For clarity, running tests in a test suite would behave as follows: 162 * 163 * suite.suite_init(suite); 164 * suite.init(test); 165 * suite.test_case[0](test); 166 * suite.exit(test); 167 * suite.init(test); 168 * suite.test_case[1](test); 169 * suite.exit(test); 170 * suite.suite_exit(suite); 171 * ...; 172 */ 173 static struct kunit_suite example_test_suite = { 174 .name = "example", 175 .init = example_test_init, 176 .suite_init = example_test_init_suite, 177 .test_cases = example_test_cases, 178 }; 179 180 /* 181 * This registers the above test suite telling KUnit that this is a suite of 182 * tests that need to be run. 183 */ 184 kunit_test_suites(&example_test_suite); 185 186 MODULE_LICENSE("GPL v2"); 187