To: <firstname.lastname@example.org>, <email@example.com>,
<firstname.lastname@example.org>, <email@example.com>, <firstname.lastname@example.org>
Cc: <email@example.com>, <firstname.lastname@example.org>,
Subject: RE: [PATCH v1 1/7] Documentation: KUnit: Rewrite main page
Date: Fri, 3 Dec 2021 17:32:38 +0000 [thread overview]
Message-ID: <BYAPR13MB2503D1D29303C11E2135ED44FD6A9@BYAPR13MB2503.namprd13.prod.outlook.com> (raw)
Here are some suggestions inline below.
> -----Original Message-----
> From: Harinder Singh <email@example.com>
> Sent: Thursday, December 2, 2021 9:25 PM
> To: firstname.lastname@example.org; email@example.com; firstname.lastname@example.org; email@example.com
> Cc: firstname.lastname@example.org; email@example.com; firstname.lastname@example.org; email@example.com; Harinder
> Singh <firstname.lastname@example.org>
> 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 <email@example.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:
> @@ -16,82 +17,84 @@ KUnit - Unit Testing for the Linux Kernel
> -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 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>`.
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
> - "... 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.
> +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.
> +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.
> +- Perform unit tests.
Perform -> Performs
> +- Run tests on any kernel architecture.
Run tests -> Runs tests
> +- Runs test in milliseconds.
Runs test -> Runs a test
> +- 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.
next prev parent reply other threads:[~2021-12-03 17:33 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-03 4:24 [PATCH v1 0/7] Documentation: KUnit: Rework KUnit documentation Harinder Singh
2021-12-03 4:24 ` [PATCH v1 1/7] Documentation: KUnit: Rewrite main page Harinder Singh
2021-12-03 17:32 ` Tim.Bird [this message]
2021-12-07 5:46 ` Harinder Singh
2021-12-03 4:24 ` [PATCH v1 2/7] Documentation: KUnit: Rewrite getting started Harinder Singh
2021-12-03 18:34 ` Tim.Bird
2021-12-07 5:53 ` Harinder Singh
2021-12-07 18:50 ` Tim.Bird
2021-12-03 4:24 ` [PATCH v1 3/7] Documentation: KUnit: Added KUnit Architecture Harinder Singh
2021-12-03 4:24 ` [PATCH v1 4/7] Documentation: kunit: Reorganize documentation related to running tests Harinder Singh
2021-12-03 4:24 ` [PATCH v1 5/7] Documentation: KUnit: Rework writing page to focus on writing tests Harinder Singh
2021-12-03 4:24 ` [PATCH v1 6/7] Documentation: KUnit: Restyle Test Style and Nomenclature page Harinder Singh
2021-12-03 4:24 ` [PATCH v1 7/7] Documentation: KUnit: Restyled Frequently Asked Questions Harinder Singh
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).