lib/kunit/kunit-example-test.c

0001 // SPDX-License-Identifier: GPL-2.0
0002 /*
0003  * Example KUnit test to show how to use KUnit.
0004  *
0005  * Copyright (C) 2019, Google LLC.
0006  * Author: Brendan Higgins <brendanhiggins@google.com>
0007  */
0008
0009 #include <kunit/test.h>
0010
0011 /*
0012  * This is the most fundamental element of KUnit, the test case. A test case
0013  * makes a set EXPECTATIONs and ASSERTIONs about the behavior of some code; if
0014  * any expectations or assertions are not met, the test fails; otherwise, the
0015  * test passes.
0016  *
0017  * In KUnit, a test case is just a function with the signature
0018  * `void (*)(struct kunit *)`. `struct kunit` is a context object that stores
0019  * information about the current test.
0020  */
0021 static void example_simple_test(struct kunit *test)
0022 {
0023     /*
0024      * This is an EXPECTATION; it is how KUnit tests things. When you want
0025      * to test a piece of code, you set some expectations about what the
0026      * code should do. KUnit then runs the test and verifies that the code's
0027      * behavior matched what was expected.
0028      */
0029     KUNIT_EXPECT_EQ(test, 1 + 1, 2);
0030 }
0031
0032 /*
0033  * This is run once before each test case, see the comment on
0034  * example_test_suite for more information.
0035  */
0036 static int example_test_init(struct kunit *test)
0037 {
0038     kunit_info(test, "initializing\n");
0039
0040     return 0;
0041 }
0042
0043 /*
0044  * This is run once before all test cases in the suite.
0045  * See the comment on example_test_suite for more information.
0046  */
0047 static int example_test_init_suite(struct kunit_suite *suite)
0048 {
0049     kunit_info(suite, "initializing suite\n");
0050
0051     return 0;
0052 }
0053
0054 /*
0055  * This test should always be skipped.
0056  */
0057 static void example_skip_test(struct kunit *test)
0058 {
0059     /* This line should run */
0060     kunit_info(test, "You should not see a line below.");
0061
0062     /* Skip (and abort) the test */
0063     kunit_skip(test, "this test should be skipped");
0064
0065     /* This line should not execute */
0066     KUNIT_FAIL(test, "You should not see this line.");
0067 }
0068
0069 /*
0070  * This test should always be marked skipped.
0071  */
0072 static void example_mark_skipped_test(struct kunit *test)
0073 {
0074     /* This line should run */
0075     kunit_info(test, "You should see a line below.");
0076
0077     /* Skip (but do not abort) the test */
0078     kunit_mark_skipped(test, "this test should be skipped");
0079
0080     /* This line should run */
0081     kunit_info(test, "You should see this line.");
0082 }
0083
0084 /*
0085  * This test shows off all the types of KUNIT_EXPECT macros.
0086  */
0087 static void example_all_expect_macros_test(struct kunit *test)
0088 {
0089     /* Boolean assertions */
0090     KUNIT_EXPECT_TRUE(test, true);
0091     KUNIT_EXPECT_FALSE(test, false);
0092
0093     /* Integer assertions */
0094     KUNIT_EXPECT_EQ(test, 1, 1); /* check == */
0095     KUNIT_EXPECT_GE(test, 1, 1); /* check >= */
0096     KUNIT_EXPECT_LE(test, 1, 1); /* check <= */
0097     KUNIT_EXPECT_NE(test, 1, 0); /* check != */
0098     KUNIT_EXPECT_GT(test, 1, 0); /* check >  */
0099     KUNIT_EXPECT_LT(test, 0, 1); /* check <  */
0100
0101     /* Pointer assertions */
0102     KUNIT_EXPECT_NOT_ERR_OR_NULL(test, test);
0103     KUNIT_EXPECT_PTR_EQ(test, NULL, NULL);
0104     KUNIT_EXPECT_PTR_NE(test, test, NULL);
0105     KUNIT_EXPECT_NULL(test, NULL);
0106     KUNIT_EXPECT_NOT_NULL(test, test);
0107
0108     /* String assertions */
0109     KUNIT_EXPECT_STREQ(test, "hi", "hi");
0110     KUNIT_EXPECT_STRNEQ(test, "hi", "bye");
0111
0112     /*
0113      * There are also ASSERT variants of all of the above that abort test
0114      * execution if they fail. Useful for memory allocations, etc.
0115      */
0116     KUNIT_ASSERT_GT(test, sizeof(char), 0);
0117
0118     /*
0119      * There are also _MSG variants of all of the above that let you include
0120      * additional text on failure.
0121      */
0122     KUNIT_EXPECT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!");
0123     KUNIT_ASSERT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!");
0124 }
0125
0126 /*
0127  * Here we make a list of all the test cases we want to add to the test suite
0128  * below.
0129  */
0130 static struct kunit_case example_test_cases[] = {
0131     /*
0132      * This is a helper to create a test case object from a test case
0133      * function; its exact function is not important to understand how to
0134      * use KUnit, just know that this is how you associate test cases with a
0135      * test suite.
0136      */
0137     KUNIT_CASE(example_simple_test),
0138     KUNIT_CASE(example_skip_test),
0139     KUNIT_CASE(example_mark_skipped_test),
0140     KUNIT_CASE(example_all_expect_macros_test),
0141     {}
0142 };
0143
0144 /*
0145  * This defines a suite or grouping of tests.
0146  *
0147  * Test cases are defined as belonging to the suite by adding them to
0148  * `kunit_cases`.
0149  *
0150  * Often it is desirable to run some function which will set up things which
0151  * will be used by every test; this is accomplished with an `init` function
0152  * which runs before each test case is invoked. Similarly, an `exit` function
0153  * may be specified which runs after every test case and can be used to for
0154  * cleanup. For clarity, running tests in a test suite would behave as follows:
0155  *
0156  * suite.suite_init(suite);
0157  * suite.init(test);
0158  * suite.test_case[0](test);
0159  * suite.exit(test);
0160  * suite.init(test);
0161  * suite.test_case[1](test);
0162  * suite.exit(test);
0163  * suite.suite_exit(suite);
0164  * ...;
0165  */
0166 static struct kunit_suite example_test_suite = {
0167     .name = "example",
0168     .init = example_test_init,
0169     .suite_init = example_test_init_suite,
0170     .test_cases = example_test_cases,
0171 };
0172
0173 /*
0174  * This registers the above test suite telling KUnit that this is a suite of
0175  * tests that need to be run.
0176  */
0177 kunit_test_suites(&example_test_suite);
0178
0179 MODULE_LICENSE("GPL v2");