Move KUnit introduction from table of contents index to its own page. While at it, rewrite the intro. Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx> --- 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
