Here are some suggestions inline below.
-----Original Message----- From: Harinder Singh sharinder@google.com Sent: Thursday, December 2, 2021 9:25 PM To: davidgow@google.com; brendanhiggins@google.com; shuah@kernel.org; corbet@lwn.net Cc: linux-kselftest@vger.kernel.org; kunit-dev@googlegroups.com; linux-doc@vger.kernel.org; linux-kernel@vger.kernel.org; Harinder Singh sharinder@google.com Subject: [PATCH v1 1/7] Documentation: KUnit: Rewrite main page
Add a section on advantages of unit testing, how to write unit tests, KUnit features and Prerequisites.
Signed-off-by: Harinder Singh sharinder@google.com
Documentation/dev-tools/kunit/index.rst | 159 ++++++++++++------------ 1 file changed, 81 insertions(+), 78 deletions(-)
diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index cacb35ec658d..2ddd01d62406 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -1,11 +1,12 @@ .. SPDX-License-Identifier: GPL-2.0
-=========================================
-KUnit - Unit Testing for the Linux Kernel
+================================= +KUnit - Linux Kernel Unit Testing +=================================
.. toctree:: :maxdepth: 2
:caption: Contents:
start usage
@@ -16,82 +17,84 @@ KUnit - Unit Testing for the Linux Kernel 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.
This introduction to kunit_tool it not present elsewhere in this patch. Are you sure we want to drop this?
-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.
The patch just drops these ideas. I don't think It should.
-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 actualhardware under User Mode Linux. User Mode Linux is a Linux architecture,like ARM or x86, which compiles the kernel as a Linux executable. KUnitcan be used with UML either by building with ``ARCH=um`` (like any otherarchitecture), or by using :doc:`kunit_tool <kunit-tool>`.
You don't replace this note about using kunit with UML with anything. Why? Is using UML deprecated or something? Is this note incorrect or misleading?
-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?
This whole section about speed changing the nature of the activity is dropped. Is that intentional?
+This section details the kernel unit testing framework.
+Introduction +============
+KUnit (Kernel unit testing framework) prvoides a common framework for
prvoides -> provides
+unit tests within the Linux kernel. Using KUnit, you can define groups +of test cases called test suites. The tests either run on kernel boot +if built-in, or load as a module. KUnit automatically flags and reports +failed test cases in the kernel log. The test results appear in TAP +(Test Anything Protocol) format. It is inspired by JUnit, Python’s
You lost the link to the TAP website here. You should have something like this link in here somewhere. `TAP https://testanything.org/`_
+unittest.mock, and GoogleTest/GoogleMock (C++ unit testing framework).
+KUnit tests are part of the kernel, written in the C (programming) +language, and test parts of the Kernel implementation (example: a C +language function). Excluding build time, from invocation to +completion, KUnit can run around 100 tests in less than 10 seconds. +KUnit can test all kernel components, example: file system, system
all kernel components, example -> any kernel component, for example
+calls, memory management, device drivers and so on.
+KUnit follows the white-box testing approach. The test has access to +internal system functionality. KUnit runs in kernel space and is not +restricted to things exposed to user-space.
+Features +--------
+- Perform unit tests.
Perform -> Performs
+- Run tests on any kernel architecture.
Run tests -> Runs tests
+- Runs test in milliseconds.
Runs test -> Runs a test
+Prerequisites +-------------
+- Any Linux kernel compatible hardware. +- For Kernel under test, Linux kernel version 5.5 or greater.
+Unit Testing +============
+A unit test verifies a single code unit. For example: a function or
code unit. For example: a function -> code unit - for example a function
+codepath. The test executes a single test method multiple times with
The test executes -> The test commonly executes
+different parameters. It is recommended to run unit test +independently of any other unit test or code.
It is recommended to run unit test -> It is recommended to structure a unit test so that it can run
+Write Unit Tests +----------------
+To write good unit tests, there is a simple but powerful pattern: +Arrange-Act-Asert. This is a great way to structure test cases and
Asert -> Assert
+defines an order of operations.
+- Arrange inputs and targets: At the start of the test, arrange the data
- that allows a function to work. Example: initialize a statement or
- object.
+- Act on the target behavior: Call your function/code under test. +- Assert expected outcome: Verify the initial state and result as
- expected or not.
I don't know what "Verify the initial state" means.
Verify the initial state and result as expected or not -> Verify whether the result (or resulting state) is as expected or not.
+Unit Testing Advantages +-----------------------
+- Increases testing speed and development in the long run. +- Detects bugs at initial stage and therefore decreases bug fix cost
- compared to acceptance testing.
+- Improves code quality. +- Encourages writing testable code.
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 +* Documentation/dev-tools/kunit/start.rst - for KUnit new users. +* Documentation/dev-tools/kunit/usage.rst - KUnit features. +* Documentation/dev-tools/kunit/tips.rst - best practices with
- examples.
+* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
- used for testing.
+* Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
- script.
+* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
- answers.
-- 2.34.0.384.gca35af8252-goog