5 The kernel contains a set of "self tests" under the tools/testing/selftests/
6 directory. These are intended to be small tests to exercise individual code
7 paths in the kernel. Tests are intended to be run after building, installing
10 You can find additional information on Kselftest framework, how to
11 write new tests using the framework on Kselftest wiki:
13 https://kselftest.wiki.kernel.org/
15 On some systems, hot-plug tests could hang forever waiting for cpu and
16 memory to be ready to be offlined. A special hot-plug target is created
17 to run the full range of hot-plug tests. In default mode, hot-plug tests run
18 in safe mode with a limited scope. In limited mode, cpu-hotplug test is
19 run on a single cpu as opposed to all hotplug capable cpus, and memory
20 hotplug test is run on 2% of hotplug capable memory instead of 10%.
22 Running the selftests (hotplug tests are run in limited mode)
23 =============================================================
27 $ make -C tools/testing/selftests
31 $ make -C tools/testing/selftests run_tests
33 To build and run the tests with a single command, use::
37 Note that some tests will require root privileges.
39 Kselftest supports saving output files in a separate directory and then
40 running tests. To locate output files in a separate directory two syntaxes
41 are supported. In both cases the working directory must be the root of the
42 kernel src. This is applicable to "Running a subset of selftests" section
45 To build, save output files in a separate directory with O= ::
47 $ make O=/tmp/kselftest kselftest
49 To build, save output files in a separate directory with KBUILD_OUTPUT ::
51 $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
53 The O= assignment takes precedence over the KBUILD_OUTPUT environment
56 The above commands by default run the tests and print full pass/fail report.
57 Kselftest supports "summary" option to make it easier to understand the test
58 results. Please find the detailed individual test results for each test in
59 /tmp/testname file(s) when summary option is specified. This is applicable
60 to "Running a subset of selftests" section below.
62 To run kselftest with summary option enabled ::
64 $ make summary=1 kselftest
66 Running a subset of selftests
67 =============================
69 You can use the "TARGETS" variable on the make command line to specify
70 single test to run, or a list of tests to run.
72 To run only tests targeted for a single subsystem::
74 $ make -C tools/testing/selftests TARGETS=ptrace run_tests
76 You can specify multiple tests to build and run::
78 $ make TARGETS="size timers" kselftest
80 To build, save output files in a separate directory with O= ::
82 $ make O=/tmp/kselftest TARGETS="size timers" kselftest
84 To build, save output files in a separate directory with KBUILD_OUTPUT ::
86 $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
88 See the top-level tools/testing/selftests/Makefile for the list of all
91 Running the full range hotplug selftests
92 ========================================
94 To build the hotplug tests::
96 $ make -C tools/testing/selftests hotplug
98 To run the hotplug tests::
100 $ make -C tools/testing/selftests run_hotplug
102 Note that some tests will require root privileges.
108 You can use the kselftest_install.sh tool to install selftests in the
109 default location, which is tools/testing/selftests/kselftest, or in a
110 user specified location.
112 To install selftests in default location::
114 $ cd tools/testing/selftests
115 $ ./kselftest_install.sh
117 To install selftests in a user specified location::
119 $ cd tools/testing/selftests
120 $ ./kselftest_install.sh install_dir
122 Running installed selftests
123 ===========================
125 Kselftest install as well as the Kselftest tarball provide a script
126 named "run_kselftest.sh" to run the tests.
128 You can simply do the following to run the installed Kselftests. Please
129 note some tests will require root privileges::
134 Contributing new tests
135 ======================
137 In general, the rules for selftests are
139 * Do as much as you can if you're not root;
141 * Don't take too long;
143 * Don't break the build on any architecture, and
145 * Don't cause the top-level "make run_tests" to fail if your feature is
148 Contributing new tests (details)
149 ================================
151 * Use TEST_GEN_XXX if such binaries or files are generated during
154 TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by
157 TEST_CUSTOM_PROGS should be used by tests that require custom build
158 rules and prevent common build rule use.
160 TEST_PROGS are for test shell scripts. Please ensure shell script has
161 its exec bit set. Otherwise, lib.mk run_tests will generate a warning.
163 TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests.
165 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
166 executable which is not tested by default.
167 TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
170 * First use the headers inside the kernel source and/or git repo, and then the
171 system headers. Headers for the kernel release as opposed to headers
172 installed by the distro on the system should be the primary focus to be able
175 * If a test needs specific kernel config options enabled, add a config file in
176 the test directory to enable them.
178 e.g: tools/testing/selftests/android/config
183 The kselftest_harness.h file contains useful helpers to build tests. The tests
184 from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example.
189 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
196 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
197 :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
198 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN
203 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
206 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
207 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE
208 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE
209 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT
210 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE
211 EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE