1*4882a593Smuzhiyun // SPDX-License-Identifier: GPL-2.0
2*4882a593Smuzhiyun /*
3*4882a593Smuzhiyun * Example KUnit test to show how to use KUnit.
4*4882a593Smuzhiyun *
5*4882a593Smuzhiyun * Copyright (C) 2019, Google LLC.
6*4882a593Smuzhiyun * Author: Brendan Higgins <brendanhiggins@google.com>
7*4882a593Smuzhiyun */
8*4882a593Smuzhiyun
9*4882a593Smuzhiyun #include <kunit/test.h>
10*4882a593Smuzhiyun
11*4882a593Smuzhiyun /*
12*4882a593Smuzhiyun * This is the most fundamental element of KUnit, the test case. A test case
13*4882a593Smuzhiyun * makes a set EXPECTATIONs and ASSERTIONs about the behavior of some code; if
14*4882a593Smuzhiyun * any expectations or assertions are not met, the test fails; otherwise, the
15*4882a593Smuzhiyun * test passes.
16*4882a593Smuzhiyun *
17*4882a593Smuzhiyun * In KUnit, a test case is just a function with the signature
18*4882a593Smuzhiyun * `void (*)(struct kunit *)`. `struct kunit` is a context object that stores
19*4882a593Smuzhiyun * information about the current test.
20*4882a593Smuzhiyun */
example_simple_test(struct kunit * test)21*4882a593Smuzhiyun static void example_simple_test(struct kunit *test)
22*4882a593Smuzhiyun {
23*4882a593Smuzhiyun /*
24*4882a593Smuzhiyun * This is an EXPECTATION; it is how KUnit tests things. When you want
25*4882a593Smuzhiyun * to test a piece of code, you set some expectations about what the
26*4882a593Smuzhiyun * code should do. KUnit then runs the test and verifies that the code's
27*4882a593Smuzhiyun * behavior matched what was expected.
28*4882a593Smuzhiyun */
29*4882a593Smuzhiyun KUNIT_EXPECT_EQ(test, 1 + 1, 2);
30*4882a593Smuzhiyun }
31*4882a593Smuzhiyun
32*4882a593Smuzhiyun /*
33*4882a593Smuzhiyun * This is run once before each test case, see the comment on
34*4882a593Smuzhiyun * example_test_suite for more information.
35*4882a593Smuzhiyun */
example_test_init(struct kunit * test)36*4882a593Smuzhiyun static int example_test_init(struct kunit *test)
37*4882a593Smuzhiyun {
38*4882a593Smuzhiyun kunit_info(test, "initializing\n");
39*4882a593Smuzhiyun
40*4882a593Smuzhiyun return 0;
41*4882a593Smuzhiyun }
42*4882a593Smuzhiyun
43*4882a593Smuzhiyun /*
44*4882a593Smuzhiyun * Here we make a list of all the test cases we want to add to the test suite
45*4882a593Smuzhiyun * below.
46*4882a593Smuzhiyun */
47*4882a593Smuzhiyun static struct kunit_case example_test_cases[] = {
48*4882a593Smuzhiyun /*
49*4882a593Smuzhiyun * This is a helper to create a test case object from a test case
50*4882a593Smuzhiyun * function; its exact function is not important to understand how to
51*4882a593Smuzhiyun * use KUnit, just know that this is how you associate test cases with a
52*4882a593Smuzhiyun * test suite.
53*4882a593Smuzhiyun */
54*4882a593Smuzhiyun KUNIT_CASE(example_simple_test),
55*4882a593Smuzhiyun {}
56*4882a593Smuzhiyun };
57*4882a593Smuzhiyun
58*4882a593Smuzhiyun /*
59*4882a593Smuzhiyun * This defines a suite or grouping of tests.
60*4882a593Smuzhiyun *
61*4882a593Smuzhiyun * Test cases are defined as belonging to the suite by adding them to
62*4882a593Smuzhiyun * `kunit_cases`.
63*4882a593Smuzhiyun *
64*4882a593Smuzhiyun * Often it is desirable to run some function which will set up things which
65*4882a593Smuzhiyun * will be used by every test; this is accomplished with an `init` function
66*4882a593Smuzhiyun * which runs before each test case is invoked. Similarly, an `exit` function
67*4882a593Smuzhiyun * may be specified which runs after every test case and can be used to for
68*4882a593Smuzhiyun * cleanup. For clarity, running tests in a test suite would behave as follows:
69*4882a593Smuzhiyun *
70*4882a593Smuzhiyun * suite.init(test);
71*4882a593Smuzhiyun * suite.test_case[0](test);
72*4882a593Smuzhiyun * suite.exit(test);
73*4882a593Smuzhiyun * suite.init(test);
74*4882a593Smuzhiyun * suite.test_case[1](test);
75*4882a593Smuzhiyun * suite.exit(test);
76*4882a593Smuzhiyun * ...;
77*4882a593Smuzhiyun */
78*4882a593Smuzhiyun static struct kunit_suite example_test_suite = {
79*4882a593Smuzhiyun .name = "example",
80*4882a593Smuzhiyun .init = example_test_init,
81*4882a593Smuzhiyun .test_cases = example_test_cases,
82*4882a593Smuzhiyun };
83*4882a593Smuzhiyun
84*4882a593Smuzhiyun /*
85*4882a593Smuzhiyun * This registers the above test suite telling KUnit that this is a suite of
86*4882a593Smuzhiyun * tests that need to be run.
87*4882a593Smuzhiyun */
88*4882a593Smuzhiyun kunit_test_suites(&example_test_suite);
89*4882a593Smuzhiyun
90*4882a593Smuzhiyun MODULE_LICENSE("GPL v2");
91