Documentation: kunit: Make the KUnit documentation less UML-specific
Subsystems (4)
PATCH v3 1/1 Documentation: kunit: Make the KUnit documentation less UML-specific
Remove some of the outmoded "Why KUnit" rationale, and move some UML-specific information to the kunit_tool page. Also update the Getting Started guide to mention running tests without the kunit_tool wrapper.
---
Thanks: I've added a note to the "Why KUnit" section which I think better reflects both the UML is optional, and that it can be used both with and without kunit_tool.
Changelog:
v3:
- Added a note that KUnit can be used with UML, both with and without kunit_tool to replace the section moved to kunit_tool.
v2:
https://lore.kernel.org/linux-kselftest/[email protected]/T/
- Reinstated the "Why Kunit?" section, minus the comparison with other testing frameworks (covered in the FAQ), and the description of UML.
- Moved the description of UML into to kunit_tool page.
- Tidied up the wording around how KUnit is built and run to make it work
without the UML description.
v1:
https://lore.kernel.org/linux-kselftest/[email protected]/T/
- Initial patch
Documentation/dev-tools/kunit/index.rst | 41 ++++++---- Documentation/dev-tools/kunit/kunit-tool.rst | 7 ++ Documentation/dev-tools/kunit/start.rst | 80 ++++++++++++++++---- 3 files changed, 100 insertions(+), 28 deletions(-)
Documentation/dev-tools/kunit/index.rst +26 -15
@@ -17,14 +17,23 @@ What is KUnit? ============== KUnit is a lightweight unit testing and mocking framework for the Linux kernel. -These tests are able to be run locally on a developer's workstation without a VM -or special hardware. 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 offsers +: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: :doc:`start` Why KUnit?
@@ -36,22 +45,21 @@ 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. -Outside of KUnit, there are no testing frameworks currently -available for the kernel that do not require installing the kernel on a test -machine or in a VM and all require tests to be written in userspace running on -the kernel; this is true for Autotest, and kselftest, disqualifying -any of them from being considered unit testing frameworks. - -KUnit addresses the problem of being able to run tests without needing a virtual -machine or actual hardware with User Mode Linux. User Mode Linux is a Linux -architecture, like ARM or x86; however, unlike other architectures it compiles -to a standalone program that can be run like any other program directly inside -of a host operating system; to be clear, it does not require any virtualization -support; it is just a regular program. +KUnit provides a common framework for unit tests within the kernel. -Alternatively, kunit and kunit tests can be built as modules and tests will +KUnit tests can be run on most kernel configurations, 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
@@ -75,9 +83,12 @@ 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? ================ * :doc:`start` - for new users of KUnit * :doc:`usage` - for a more detailed explanation of KUnit features * :doc:`api/index` - for the list of KUnit APIs used for testing +* :doc:`kunit-tool` - for more information on the kunit_tool helper script +* :doc:`faq` - for answers to some common questions about KUnit
Documentation/dev-tools/kunit/kunit-tool.rst +7 -0
@@ -12,6 +12,13 @@ the Linux kernel as UML (`User Mode Linux <http://user-mode-linux.sourceforge.net/>`_), running KUnit tests, parsing the test results and displaying them in a user friendly manner. +kunit_tool addresses the problem of being able to run tests without needing a +virtual machine or actual hardware with User Mode Linux. User Mode Linux is a +Linux architecture, like ARM or x86; however, unlike other architectures it +compiles the kernel as a standalone Linux executable that can be run like any +other program directly inside of a host operating system. To be clear, it does +not require any virtualization support: it is just a regular program. + What is a kunitconfig? ======================
Documentation/dev-tools/kunit/start.rst +67 -13
106 lines not on this page · raw message
Signature · 1 line
2.25.0.265.gbab2e86ba0-goog
Hi,
On Fri, Feb 14, 2020 at 03:57:23PM -0800, David Gow wrote:
[...]
Quoted 1 line
+To make running these tests (and reading the results) easier, KUnit offsers
There's a typo here: s/offsers/offers/
Thanks,
Jonathan Neuschäfer