1======================
2Linux Kernel Selftests
3======================
4
5The kernel contains a set of "self tests" under the tools/testing/selftests/
6directory. These are intended to be small tests to exercise individual code
7paths in the kernel. Tests are intended to be run after building, installing
8and booting a kernel.
9
10On some systems, hot-plug tests could hang forever waiting for cpu and
11memory to be ready to be offlined. A special hot-plug target is created
12to run full range of hot-plug tests. In default mode, hot-plug tests run
13in safe mode with a limited scope. In limited mode, cpu-hotplug test is
14run on a single cpu as opposed to all hotplug capable cpus, and memory
15hotplug test is run on 2% of hotplug capable memory instead of 10%.
16
17Running the selftests (hotplug tests are run in limited mode)
18=============================================================
19
20To build the tests::
21
22  $ make -C tools/testing/selftests
23
24To run the tests::
25
26  $ make -C tools/testing/selftests run_tests
27
28To build and run the tests with a single command, use::
29
30  $ make kselftest
31
32Note that some tests will require root privileges.
33
34
35Running a subset of selftests
36=============================
37
38You can use the "TARGETS" variable on the make command line to specify
39single test to run, or a list of tests to run.
40
41To run only tests targeted for a single subsystem::
42
43  $ make -C tools/testing/selftests TARGETS=ptrace run_tests
44
45You can specify multiple tests to build and run::
46
47  $  make TARGETS="size timers" kselftest
48
49See the top-level tools/testing/selftests/Makefile for the list of all
50possible targets.
51
52
53Running the full range hotplug selftests
54========================================
55
56To build the hotplug tests::
57
58  $ make -C tools/testing/selftests hotplug
59
60To run the hotplug tests::
61
62  $ make -C tools/testing/selftests run_hotplug
63
64Note that some tests will require root privileges.
65
66
67Install selftests
68=================
69
70You can use kselftest_install.sh tool installs selftests in default
71location which is tools/testing/selftests/kselftest or a user specified
72location.
73
74To install selftests in default location::
75
76   $ cd tools/testing/selftests
77   $ ./kselftest_install.sh
78
79To install selftests in a user specified location::
80
81   $ cd tools/testing/selftests
82   $ ./kselftest_install.sh install_dir
83
84Running installed selftests
85===========================
86
87Kselftest install as well as the Kselftest tarball provide a script
88named "run_kselftest.sh" to run the tests.
89
90You can simply do the following to run the installed Kselftests. Please
91note some tests will require root privileges::
92
93   $ cd kselftest
94   $ ./run_kselftest.sh
95
96Contributing new tests
97======================
98
99In general, the rules for selftests are
100
101 * Do as much as you can if you're not root;
102
103 * Don't take too long;
104
105 * Don't break the build on any architecture, and
106
107 * Don't cause the top-level "make run_tests" to fail if your feature is
108   unconfigured.
109
110Contributing new tests (details)
111================================
112
113 * Use TEST_GEN_XXX if such binaries or files are generated during
114   compiling.
115
116   TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by
117   default.
118
119   TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
120   executable which is not tested by default.
121   TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
122   test.
123
124Test Harness
125============
126
127The kselftest_harness.h file contains useful helpers to build tests.  The tests
128from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example.
129
130Example
131-------
132
133.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
134    :doc: example
135
136
137Helpers
138-------
139
140.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
141    :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
142                FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN
143
144Operators
145---------
146
147.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
148    :doc: operators
149
150.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
151    :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE
152                ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE
153                ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT
154                EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE
155                EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE
156