[PATCH RESEND 6/7] Documentation: kunit: rewrite "Run Tests without kunit_tool"

From: Bagas Sanjaya
Date: Sun Oct 23 2022 - 09:11:06 EST


Rewrite the documentation for clarity. Major points:

* Use second-person point of view
* Align and format the first note like other note blocks
* Remove unnecessary lists and trivial modprobe code block (every
developer should have known how to load modules)

Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
---
Documentation/dev-tools/kunit/run_manual.rst | 68 ++++++++------------
1 file changed, 27 insertions(+), 41 deletions(-)

diff --git a/Documentation/dev-tools/kunit/run_manual.rst b/Documentation/dev-tools/kunit/run_manual.rst
index e7b46421f247e1..28c6a1caa0fed0 100644
--- a/Documentation/dev-tools/kunit/run_manual.rst
+++ b/Documentation/dev-tools/kunit/run_manual.rst
@@ -4,54 +4,40 @@
Run Tests without kunit_tool
============================

-If we do not want to use kunit_tool (For example: we want to integrate
-with other systems, or run tests on real hardware), we can
-include KUnit in any kernel, read out results, and parse manually.
+If you do not want to use kunit_tool (e.g. integrating
+with other testing framework or running tests on real hardware), you
+can run KUnit-enabled kernel manually. The test results can be parsed with
+your existing tools.

-.. note:: KUnit is not designed for use in a production system. It is
- possible that tests may reduce the stability or security of
- the system.
+.. note::

-Configure the Kernel
+ Using KUnit is not recommended in production system, since
+ stability and security issues may occur if it is enabled.
+
+Kernel configuration
====================

-KUnit tests can run without kunit_tool. This can be useful, if:
+To enable KUnit, configure the kernel with ``CONFIG_KUNIT`` enabled.
+Individual tests can then be selected. KUnit tests usually (but don't always)
+have configuration name suffixed with ``_KUNIT_TEST``. As with other kernel
+configurations, most tests can be enabled either builtin or as module.

-- We have an existing kernel configuration to test.
-- Need to run on real hardware (or using an emulator/VM kunit_tool
- does not support).
-- Wish to integrate with some existing testing systems.
+.. note::

-KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
-tests can also be built by enabling their config options in our
-``.config``. KUnit tests usually (but don't always) have config options
-ending in ``_KUNIT_TEST``. Most tests can either be built as a module,
-or be built into the kernel.
+ You can enable ``KUNIT_ALL_TESTS``, which automatically enable all
+ tests for which their dependencies can be satisfied. This is a good
+ way of quickly testing everything applicable to the current
+ configuration.

-.. note ::
+Once the kernel have been built and installed, it is simple to run
+the tests just by booting the kernel. If these are builtin, they will run
+automatically. If these are built as modules, they will need to be loaded
+first in order to run them.

- We can enable the ``KUNIT_ALL_TESTS`` config option to
- automatically enable all tests with satisfied dependencies. This is
- a good way of quickly testing everything applicable to the current
- config.
+The test results will be logged in TAP format in ``dmesg``.

-Once we have built our kernel (and/or modules), it is simple to run
-the tests. If the tests are built-in, they will run automatically on the
-kernel boot. The results will be written to the kernel log (``dmesg``)
-in TAP format.
+.. note::

-If the tests are built as modules, they will run when the module is
-loaded.
-
-.. code-block :: bash
-
- # modprobe example-test
-
-The results will appear in TAP format in ``dmesg``.
-
-.. note ::
-
- If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will
- be accessible from the ``debugfs`` filesystem (if mounted).
- They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in
- TAP format.
+ If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the test results can
+ be accessed from debugfs (if mounted). Results for each test suite
+ will be in ``/sys/kernel/debug/kunit/<test_suite>/results``.
--
An old man doll... just what I always wanted! - Clara