mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-22 08:49:45 +00:00
a48ad6e7a3
This KUnit update for Linux 5.14-rc1 consists of fixes and features: -- add support for skipped tests -- introduce kunit_kmalloc_array/kunit_kcalloc() helpers -- add gnu_printf specifiers -- add kunit_shutdown -- add unit test for filtering suites by names -- convert lib/test_list_sort.c to use KUnit -- code organization moving default config to tools/testing/kunit -- refactor of internal parser input handling -- cleanups and updates to documentation -- code cleanup related to casts -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEEPZKym/RZuOCGeA/kCwJExA0NQxwFAmDfNHgACgkQCwJExA0N QxzU5g/+ORbcbE5jhumo82xYUCGTScgIqPllNO000Vk9xydMqwx6tpY5puV0ig2z 5X7pxKEQTnype58yzY5mS1p336ryIx3q+AwEownxTW3YurXo2naQ59ZPjEvlAV+E h+DMYLzEjrxzcyJATw02uC9YLUZ3w6FPJfiXViIv93YYrtcnM0u6JpwG0yfBlI4v 4KKB2Xu4K7T90C9/ADFYFKX3mjXQl5fQwvIdtA7wS90Cgq52LKp2mvg1XEiZE5d+ 0dkTZ4Zo8TxxHt665o7vfnUjQQNmh45iGlW65wONxfAPb8BPoneGjVKWQTnN0Hor W+93ZPbMuFMSSKJuoHY9U7sP5VySKvaiIYaGdi6prnZZu0zUabKnLZ6FOy7kEdfs v09ulCBTVLslixVgNcp/kD9T+G/SXwCF5YBMAiMDQ0GNfUqlFtBkEA3gd44KwMI0 KwCcOgUSiaCkqyzOz/VeQsu/nhA5jdMO0KjiAs7Z3e7r7O/qKFs/ll7hZgDNCWSC q8eIrcBkSL0EGgXR1iZ4AtGm8op6KKd4ACBM8NdtTyoGFl1npZOgZnHoIsy35G9K 9mhc7eXSoaDGqy9dONL1Tc8Neg7qLTXQNp2radqsnAAgNPUrJuC7+8YC+DdIsjBH W7OyMjpfbwPws5rP4CS+JdwL+nQprKXZvFIhWGYhkDK44MbOngw= =5QAv -----END PGP SIGNATURE----- Merge tag 'linux-kselftest-kunit-fixes-5.14-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest Pull KUnit update from Shuah Khan: "Fixes and features: - add support for skipped tests - introduce kunit_kmalloc_array/kunit_kcalloc() helpers - add gnu_printf specifiers - add kunit_shutdown - add unit test for filtering suites by names - convert lib/test_list_sort.c to use KUnit - code organization moving default config to tools/testing/kunit - refactor of internal parser input handling - cleanups and updates to documentation - code cleanup related to casts" * tag 'linux-kselftest-kunit-fixes-5.14-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest: (29 commits) kunit: add unit test for filtering suites by names kasan: test: make use of kunit_skip() kunit: test: Add example tests which are always skipped kunit: tool: Support skipped tests in kunit_tool kunit: Support skipped tests thunderbolt: test: Reinstate a few casts of bitfields kunit: tool: internal refactor of parser input handling lib/test: convert lib/test_list_sort.c to use KUnit kunit: introduce kunit_kmalloc_array/kunit_kcalloc() helpers kunit: Remove the unused all_tests.config kunit: Move default config from arch/um -> tools/testing/kunit kunit: arch/um/configs: Enable KUNIT_ALL_TESTS by default kunit: Add gnu_printf specifiers lib/cmdline_kunit: Remove a cast which are no-longer required kernel/sysctl-test: Remove some casts which are no-longer required thunderbolt: test: Remove some casts which are no longer required mmc: sdhci-of-aspeed: Remove some unnecessary casts from KUnit tests iio: Remove a cast in iio-test-format which is no longer required device property: Remove some casts in property-entry-test Documentation: kunit: Clean up some string casts in examples ...
97 lines
4.4 KiB
ReStructuredText
97 lines
4.4 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
=========================================
|
|
KUnit - Unit Testing for the Linux Kernel
|
|
=========================================
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
start
|
|
usage
|
|
kunit-tool
|
|
api/index
|
|
style
|
|
faq
|
|
tips
|
|
running_tips
|
|
|
|
What is KUnit?
|
|
==============
|
|
|
|
KUnit is a lightweight unit testing and mocking framework for the Linux kernel.
|
|
|
|
KUnit is heavily inspired by JUnit, Python's unittest.mock, and
|
|
Googletest/Googlemock for C++. KUnit provides facilities for defining unit test
|
|
cases, grouping related test cases into test suites, providing common
|
|
infrastructure for running tests, and much more.
|
|
|
|
KUnit consists of a kernel component, which provides a set of macros for easily
|
|
writing unit tests. Tests written against KUnit will run on kernel boot if
|
|
built-in, or when loaded if built as a module. These tests write out results to
|
|
the kernel log in `TAP <https://testanything.org/>`_ format.
|
|
|
|
To make running these tests (and reading the results) easier, KUnit offers
|
|
:doc:`kunit_tool <kunit-tool>`, which builds a `User Mode Linux
|
|
<http://user-mode-linux.sourceforge.net>`_ kernel, runs it, and parses the test
|
|
results. This provides a quick way of running KUnit tests during development,
|
|
without requiring a virtual machine or separate hardware.
|
|
|
|
Get started now: Documentation/dev-tools/kunit/start.rst
|
|
|
|
Why KUnit?
|
|
==========
|
|
|
|
A unit test is supposed to test a single unit of code in isolation, hence the
|
|
name. A unit test should be the finest granularity of testing and as such should
|
|
allow all possible code paths to be tested in the code under test; this is only
|
|
possible if the code under test is very small and does not have any external
|
|
dependencies outside of the test's control like hardware.
|
|
|
|
KUnit provides a common framework for unit tests within the kernel.
|
|
|
|
KUnit tests can be run on most architectures, and most tests are architecture
|
|
independent. All built-in KUnit tests run on kernel startup. Alternatively,
|
|
KUnit and KUnit tests can be built as modules and tests will run when the test
|
|
module is loaded.
|
|
|
|
.. note::
|
|
|
|
KUnit can also run tests without needing a virtual machine or actual
|
|
hardware under User Mode Linux. User Mode Linux is a Linux architecture,
|
|
like ARM or x86, which compiles the kernel as a Linux executable. KUnit
|
|
can be used with UML either by building with ``ARCH=um`` (like any other
|
|
architecture), or by using :doc:`kunit_tool <kunit-tool>`.
|
|
|
|
KUnit is fast. Excluding build time, from invocation to completion KUnit can run
|
|
several dozen tests in only 10 to 20 seconds; this might not sound like a big
|
|
deal to some people, but having such fast and easy to run tests fundamentally
|
|
changes the way you go about testing and even writing code in the first place.
|
|
Linus himself said in his `git talk at Google
|
|
<https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_:
|
|
|
|
"... a lot of people seem to think that performance is about doing the
|
|
same thing, just doing it faster, and that is not true. That is not what
|
|
performance is all about. If you can do something really fast, really
|
|
well, people will start using it differently."
|
|
|
|
In this context Linus was talking about branching and merging,
|
|
but this point also applies to testing. If your tests are slow, unreliable, are
|
|
difficult to write, and require a special setup or special hardware to run,
|
|
then you wait a lot longer to write tests, and you wait a lot longer to run
|
|
tests; this means that tests are likely to break, unlikely to test a lot of
|
|
things, and are unlikely to be rerun once they pass. If your tests are really
|
|
fast, you run them all the time, every time you make a change, and every time
|
|
someone sends you some code. Why trust that someone ran all their tests
|
|
correctly on every change when you can just run them yourself in less time than
|
|
it takes to read their test log?
|
|
|
|
How do I use it?
|
|
================
|
|
|
|
* Documentation/dev-tools/kunit/start.rst - for new users of KUnit
|
|
* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices
|
|
* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features
|
|
* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing
|
|
* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script
|
|
* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit
|