Message-Id: <20221023125414.60961-5-bagasdotme@gmail.com>
Date:   Sun, 23 Oct 2022 19:54:11 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        linux-kselftest@...r.kernel.org, kunit-dev@...glegroups.com
Cc:     Jonathan Corbet <corbet@....net>,
        Brendan Higgins <brendan.higgins@...ux.dev>,
        David Gow <davidgow@...gle.com>,
        Lukas Bulwahn <lukas.bulwahn@...il.com>,
        Khalid Masum <khalid.masum.92@...il.com>,
        Sadiya Kazi <sadiyakazi@...gle.com>,
        Bagas Sanjaya <bagasdotme@...il.com>
Subject: [PATCH 4/7] Documentation: kunit: move introduction to its own document

Move KUnit introduction from table of contents index to its own page.

While at it, rewrite the intro.

Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
---
 Documentation/dev-tools/kunit/index.rst | 93 +------------------------
 Documentation/dev-tools/kunit/intro.rst | 61 ++++++++++++++++
 2 files changed, 62 insertions(+), 92 deletions(-)
 create mode 100644 Documentation/dev-tools/kunit/intro.rst

diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
index f5d13f1d37be1d..ad972602d91ad8 100644
--- a/Documentation/dev-tools/kunit/index.rst
+++ b/Documentation/dev-tools/kunit/index.rst
@@ -8,6 +8,7 @@ KUnit - Linux Kernel Unit Testing
 	:maxdepth: 2
 	:caption: Contents:
 
+	intro
 	start
 	architecture
 	run_wrapper
@@ -19,95 +20,3 @@ KUnit - Linux Kernel Unit Testing
 	tips
 	running_tips
 
-This section details the kernel unit testing framework.
-
-Introduction
-============
-
-KUnit (Kernel unit testing framework) provides a common framework for
-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
-:doc:`KTAP (Kernel - Test Anything Protocol) format</dev-tools/ktap>`.
-It is inspired by JUnit, Python’s 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 any kernel component, for example: file system, system
-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.
-
-In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
-that configures the Linux kernel, runs KUnit tests under QEMU or UML
-(:doc:`User Mode Linux </virt/uml/user_mode_linux_howto_v2>`),
-parses the test results and
-displays them in a user friendly manner.
-
-Features
---------
-
-- Provides a framework for writing unit tests.
-- Runs tests on any kernel architecture.
-- Runs a test in milliseconds.
-
-Prerequisites
--------------
-
-- Any Linux kernel compatible hardware.
-- For Kernel under test, Linux kernel version 5.5 or greater.
-
-Unit Testing
-============
-
-A unit test tests a single unit of code in isolation. A unit test is the finest
-granularity of testing and allows all possible code paths to be tested in the
-code under test. This is possible if the code under test is small and does not
-have any external dependencies outside of the test's control like hardware.
-
-
-Write Unit Tests
-----------------
-
-To write good unit tests, there is a simple but powerful pattern:
-Arrange-Act-Assert. This is a great way to structure test cases and
-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 that the result (or resulting state) is as
-  expected.
-
-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.
-
-Read also :ref:`kinds-of-tests`.
-
-How do I use it?
-================
-
-*   Documentation/dev-tools/kunit/start.rst - for KUnit new users.
-*   Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
-*   Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
-*   Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
-*   Documentation/dev-tools/kunit/usage.rst - write tests.
-*   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/faq.rst - KUnit common questions and
-    answers.
diff --git a/Documentation/dev-tools/kunit/intro.rst b/Documentation/dev-tools/kunit/intro.rst
new file mode 100644
index 00000000000000..6061aaa0e905ab
--- /dev/null
+++ b/Documentation/dev-tools/kunit/intro.rst
@@ -0,0 +1,61 @@
+Introduction to KUnit
+=====================
+
+KUnit (Kernel unit testing framework) provides a common framework for
+unit tests within the Linux kernel. Using KUnit, you can write test
+suites for your kernel code. As with other kernel features, the
+tests can be either built into the kernel image or as loadable modules.
+It automatically flags and reports
+failed test cases in the kernel log. The test results appear in
+:doc:`KTAP (Kernel - Test Anything Protocol) format</dev-tools/ktap>`.
+It is inspired by JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock
+(C++ unit testing framework).
+
+KUnit tests are kernel code, written in the C, that tests particular kernel
+functionality. KUnit can run around
+100 tests in less than 10 seconds.
+KUnit can test any kernel component, such as file system, system
+calls, memory management, device drivers and so on.
+
+KUnit follows the white-box testing approach. The test has access to
+kernel internal. It runs in kernel space and thus not restricted to things
+exposed to user-space.
+
+In addition, KUnit has a script (``tools/testing/kunit/kunit.py``)
+that configures the kernel, runs the tests under QEMU or UML
+(:doc:`User Mode Linux </virt/uml/user_mode_linux_howto_v2>`),
+parses the test results and displays them in a user friendly manner.
+The rest of KUnit documentation will refer to this script as kunit_tool.
+
+Features
+--------
+
+- Provides a framework for writing unit tests.
+- Runs tests on any kernel architecture.
+- Runs a test in milliseconds.
+
+Prerequisites
+-------------
+
+- Linux kernel 5.5 or later is required to test using KUnit.
+
+Unit testing
+------------
+
+A unit test tests a particular code in isolation. It is the finest
+granularity of testing and allows all possible code paths to be tested in the
+code under test. This is possible if the code under test is small and does not
+depend on external factors (like hardware).
+
+Next steps
+----------
+
+If you haven't write the test before, see
+Documentation/dev-tools/kunit/start.rst for tutorial on writing your first
+test. An in-depth explanation of writing test is described in
+Documentation/dev-tools/kunit/usage.rst. For information on running tests,
+see Documentation/dev-tools/kunit/run_wrapper.rst and
+Documentation/dev-tools/kunit/run_manual.rst.
+
+The KUnit infrastructure is explained in
+Documentation/dev-tools/kunit/architecture.rst.
-- 
An old man doll... just what I always wanted! - Clara

Powered by blists - more mailing lists