iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
From the kernel source tree, the documented workflow is to prepare headers, build the in-tree selftests, and run either the full suite or only the subsystem affected by your patch. The shortest full-suite path is make kselftest; the explicit sequence is useful when you need to separate build and execution, select targets, preserve output, or diagnose a failure.
This guide follows the Linux kernel’s current kselftest documentation and the patch submission checklist. It explains what the tests cover, how to run them, how to handle permissions and environment-dependent skips, and how to turn the results into a patch-specific validation plan.
What Linux kernel selftests are—and what they do not prove
Kernel selftests, usually called kselftest, are an in-tree collection under tools/testing/selftests/. Each test is intended to exercise a relatively small kernel code path. The tests themselves run as userspace programs, even though many exercise kernel interfaces and therefore depend on the kernel configuration, privileges, devices, or runtime environment.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11The official documentation generally describes the tests as something to run after building, installing, and booting a kernel. That does not mean every test requires a custom kernel: many tests can run against an existing kernel, while others need a particular option enabled, a newly built kernel booted, or access that only root has. A passing run demonstrates what was covered in the environment you supplied; it is not evidence that every architecture, Kconfig combination, or hardware path works.
#1 Best Overall
| Question | Documented answer |
|---|---|
| Where are the tests? | tools/testing/selftests/ in the kernel source tree. |
| How do they run? | As userspace processes launched by the kselftest make targets or the installed runner. |
| Is a custom test kernel always required? | No. Many tests do not need one, but tests tied to a patch’s configuration or boot-time behavior may. |
| What does a default run report? | Pass/fail results; some tests can also be skipped when their prerequisites are absent. |
For device-oriented work, consult the kernel’s device testing with kselftest guidance as well as the general documentation.
Choose the kernel and test environment before building
Start with the tree that contains your patch
Run the commands from the root of the kernel source tree containing the change. Target names and available tests come from that tree’s selftest Makefile, so do not assume that a target shown in an example exists in every kernel version. If you are testing a change that only exists in a branch or topic tree, use that same tree for the selftest build.
Decide whether the running kernel is sufficient
Use the existing running kernel when the selected tests do not depend on your change’s new Kconfig setting, syscall behavior, driver, or boot-time setup. Build, install, and boot a kernel containing the patch when the test needs those pieces. A test that cannot find its required kernel feature is not equivalent to a passing test; record the reason for a skip or failure instead of treating it as proof that the patch is correct.
Check privilege and resource requirements
Some tests require root. Run the unprivileged portion first if that is safer for your workflow, then repeat the relevant targets with the required privileges. Tests that manipulate CPUs, memory, devices, namespaces, tracing, or other system-wide resources can also need a specially prepared environment. Read the individual target’s documentation or source when a test reports that a prerequisite is missing.
Build and run the full suite
The explicit sequence below is the clearest way to see each phase. It is run from the kernel source root:
-
Prepare the headers used by the selftest build:
make headers -
Build the selftests in their source directory:
make -C tools/testing/selftests -
Run the built tests:
make -C tools/testing/selftests run_tests
The documented shortcut combines the build and run phases:
make kselftestUnless you request summary mode, the normal command reports pass/fail results as it runs. A test that needs root or a feature absent from the running kernel can report a failure or skip for environmental reasons; investigate that distinction before attributing it to the patch.
Use the make targets that fit your patch
Run one subsystem
Set TARGETS to the selftest collection you want. For example, to build and run the ptrace tests:
make -C tools/testing/selftests TARGETS=ptrace run_testsThis is useful when an edit is confined to one subsystem and you need a fast feedback loop before a broader run.
Run several collections
Pass a space-separated list to the top-level target:
make TARGETS='size timers' kselftestThe names must be supported by the Makefile in the kernel tree being tested. A name copied from another branch may be unknown or may select a different set of tests.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Exclude a collection from a selected run
Combine TARGETS with SKIP_TARGETS when a selected group cannot run in your environment:
make TARGETS='breakpoints size timers' SKIP_TARGETS=size kselftestKeep the exclusion in your test notes. Skipping a target changes what the command validates; it should not be reported as if the entire selected set ran.
Require every selected target to build
By default, the build can succeed when at least one target builds. Set FORCE_TARGETS=1 when a patch-specific run must fail if any selected target cannot be built:
make TARGETS='breakpoints size timers' FORCE_TARGETS=1 kselftestThis stricter setting is valuable when your patch touches several collections or when a successful partial build would otherwise hide a missing dependency.
Recommended Free Tools
Keep output separate and make results easier to review
Build outside the source tree
From the kernel source root, direct kselftest output to a separate directory with either of these forms:
O=/tmp/kselftest make kselftestKBUILD_OUTPUT=/tmp/kselftest make kselftestIf both variables are set, O= takes precedence. A separate output directory keeps generated files and logs out of the source checkout and makes it easier to compare two runs.
Request summarized output
Add summary=1 to the top-level command:
make summary=1 kselftestSummary mode provides an aggregate view, while individual results are written to per-test files. Preserve those files with your build artifacts when a patch failure needs to be explained or reproduced.
Rank #3
- Used Book in Good Condition
| Need | Command form | What it changes |
|---|---|---|
| Full build and run | make kselftest |
Builds and executes the suite through the top-level target. |
| Separate output | O=/tmp/kselftest make kselftest |
Places output in the specified directory; O= wins if both output variables are present. |
| Summary plus per-test files | make summary=1 kselftest |
Adds a summary view and stores individual results. |
| Strict selected-target build | make TARGETS='...' FORCE_TARGETS=1 kselftest |
Requires every selected target to build instead of accepting a partial build. |
Install the selftests and use the standalone runner
The selftest makefile has an install target. From the kernel source root, install the tests with:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →make -C tools/testing/selftests installBy default, the files are copied to tools/testing/selftests/kselftest_install. Set INSTALL_PATH when you want another destination:
make -C tools/testing/selftests install INSTALL_PATH=/path/to/kselftestThe installed directory contains run_kselftest.sh. The runner is useful when you want to inspect or execute tests without invoking the make target each time:
./run_kselftest.sh -llists the available tests../run_kselftest.sh -cruns a collection../run_kselftest.sh -truns named tests.
Run those commands from the installation directory, or use the corresponding path under your custom INSTALL_PATH. The same privilege and kernel-feature requirements still apply; installing the files does not remove them.
Handle timeouts, hotplug tests, and long-running cases
The documented default timeout is 45 seconds per test. That is an operational limit, not a benchmark of how long a test should take on every machine. Runtime varies with system load, virtualization, hardware, and the work a test performs. The installed runner supports an --override-timeout option when a legitimate run needs a different limit; use it deliberately and record the value with your results.
Free tools Windows power users keep installed
One-click scans. No signup required.
Hotplug tests deserve special care. Some can wait for a CPU or memory resource to become available, so the documentation provides dedicated hotplug targets. The normal hotplug mode is intentionally limited for safety. If your patch affects hotplug behavior, select the dedicated target appropriate to the resource rather than assuming that the ordinary run exercises every hotplug path.
Interpret failures and skips before blaming the patch
A kselftest result is meaningful only in the context of the kernel, configuration, privileges, and resources used for the run. Use this triage sequence:
-
Confirm what actually built. If a broad command succeeded unexpectedly, check whether one target built while another did not. Re-run with
FORCE_TARGETS=1when every selected target is required. -
Identify the exact test and collection. Use summary output or the per-test result files to locate the failing name, then run that target alone so unrelated output does not obscure the first error.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Check privilege. A test that requires root can fail or skip when run as an ordinary user. Repeat only the affected target with the required privilege and document that fact.
-
Check the running kernel and Kconfig. Verify that the feature exercised by the test is enabled and that you booted the kernel containing the patch when the test depends on it.
-
Check resources and timing. For a timeout, consider system load and the documented 45-second default before changing the limit. For CPU or memory hotplug behavior, use the dedicated target and ensure the requested resources can actually be brought online or offline.
-
Separate infrastructure errors from assertions. A missing tool, unavailable device, permission error, or unsupported configuration calls for an environment fix or an explicit skip; an assertion failure after prerequisites are satisfied is the result that most directly demands code investigation.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Do not silently delete a failing or skipped test from the report. Record the command, target, kernel build or boot state, configuration relevant to the test, privilege level, and any timeout override so another contributor can reproduce the observation.
Build a patch-specific pre-submission test plan
Running kselftest is one part of validation, not a promise that every relevant configuration has been exercised. The kernel’s submission checklist recommends varying related configuration options—disabling them and, where applicable, building them as modules with =m—and testing against the most recent linux-next tag to expose interactions with queued changes. The exact matrix depends on the patch; a small documentation-only change does not automatically justify the same breadth as a scheduler, memory-management, driver, or architecture change.
Use this decision framework
- Patch changes a selftest only: build the affected collection, run it directly, and run the top-level path when practical so the test remains compatible with the suite.
- Patch changes a kernel subsystem with existing selftests: run the matching
TARGETScollection against a kernel containing the patch, then expand to related collections if the code crosses subsystem boundaries. - Patch changes Kconfig, modular code, or initialization: include builds with the relevant option disabled and, where the option supports it, set to
=m; boot the configurations that the test requires. - Patch changes device or hotplug behavior: prepare the required hardware or virtual resources, use the device-testing guidance, and select the dedicated hotplug target when applicable.
- Patch is intended for the development tip: repeat the relevant tests on the latest available
linux-nexttag in addition to the base tree used for development.
Keep the scope proportional. The checklist calls for configurations and trees that are relevant to the change, not an indiscriminate claim that every patch must run every selftest on every architecture.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.If you are adding or changing a selftest
The kselftest documentation gives four practical rules that also help reviewers judge a new test:
- “Do as much as you can if you’re not root;”
- “Don’t take too long;”
- “Don’t break the build on any architecture, and”
- “Don’t cause the top-level ‘make run_tests’ to fail if your feature is unconfigured.”
Those rules mean a test should do useful work without unnecessary privilege, complete within a reasonable runtime, compile wherever the selftest build is expected to compile, and handle an unavailable feature without turning an otherwise valid top-level run into a false failure. The documentation also asks test output to follow TAP so continuous-integration systems can parse the results. When a feature is optional, make the test’s skip or not-applicable result explicit and distinguish it from an assertion failure.
A repeatable workflow for patch submission
-
From the patched kernel tree, run
make headersand build the selftests. -
Start with the collection most closely related to the change, using
TARGETSrather than waiting for the full suite. -
Run the tests against the appropriate kernel: an existing kernel for independent tests, or a built and booted kernel when the patch changes the exercised behavior or configuration.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Repeat as root only for tests that require it, and use the dedicated environment or hotplug target when the test’s prerequisites demand one.
-
Preserve a separate output directory or summary files when you need an auditable result set.
-
Expand the matrix to relevant disabled and modular configurations and to the latest
linux-nexttag when the submission checklist’s guidance applies. -
Record skips, timeouts, and infrastructure failures with their causes instead of presenting them as passes.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
That process gives reviewers a precise answer to “what was tested?”: which selftest collection ran, against which kernel and configuration, with what privileges and resources, and which results were genuinely covered.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
