cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

index.rst (3863B)


      1.. SPDX-License-Identifier: GPL-2.0
      2
      3=================================
      4KUnit - Linux Kernel Unit Testing
      5=================================
      6
      7.. toctree::
      8	:maxdepth: 2
      9	:caption: Contents:
     10
     11	start
     12	architecture
     13	run_wrapper
     14	run_manual
     15	usage
     16	kunit-tool
     17	api/index
     18	style
     19	faq
     20	tips
     21	running_tips
     22
     23This section details the kernel unit testing framework.
     24
     25Introduction
     26============
     27
     28KUnit (Kernel unit testing framework) provides a common framework for
     29unit tests within the Linux kernel. Using KUnit, you can define groups
     30of test cases called test suites. The tests either run on kernel boot
     31if built-in, or load as a module. KUnit automatically flags and reports
     32failed test cases in the kernel log. The test results appear in `TAP
     33(Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by
     34JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing
     35framework).
     36
     37KUnit tests are part of the kernel, written in the C (programming)
     38language, and test parts of the Kernel implementation (example: a C
     39language function). Excluding build time, from invocation to
     40completion, KUnit can run around 100 tests in less than 10 seconds.
     41KUnit can test any kernel component, for example: file system, system
     42calls, memory management, device drivers and so on.
     43
     44KUnit follows the white-box testing approach. The test has access to
     45internal system functionality. KUnit runs in kernel space and is not
     46restricted to things exposed to user-space.
     47
     48In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
     49that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode
     50Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and
     51displays them in a user friendly manner.
     52
     53Features
     54--------
     55
     56- Provides a framework for writing unit tests.
     57- Runs tests on any kernel architecture.
     58- Runs a test in milliseconds.
     59
     60Prerequisites
     61-------------
     62
     63- Any Linux kernel compatible hardware.
     64- For Kernel under test, Linux kernel version 5.5 or greater.
     65
     66Unit Testing
     67============
     68
     69A unit test tests a single unit of code in isolation. A unit test is the finest
     70granularity of testing and allows all possible code paths to be tested in the
     71code under test. This is possible if the code under test is small and does not
     72have any external dependencies outside of the test's control like hardware.
     73
     74
     75Write Unit Tests
     76----------------
     77
     78To write good unit tests, there is a simple but powerful pattern:
     79Arrange-Act-Assert. This is a great way to structure test cases and
     80defines an order of operations.
     81
     82- Arrange inputs and targets: At the start of the test, arrange the data
     83  that allows a function to work. Example: initialize a statement or
     84  object.
     85- Act on the target behavior: Call your function/code under test.
     86- Assert expected outcome: Verify that the result (or resulting state) is as
     87  expected.
     88
     89Unit Testing Advantages
     90-----------------------
     91
     92- Increases testing speed and development in the long run.
     93- Detects bugs at initial stage and therefore decreases bug fix cost
     94  compared to acceptance testing.
     95- Improves code quality.
     96- Encourages writing testable code.
     97
     98How do I use it?
     99================
    100
    101*   Documentation/dev-tools/kunit/start.rst - for KUnit new users.
    102*   Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
    103*   Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
    104*   Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
    105*   Documentation/dev-tools/kunit/usage.rst - write tests.
    106*   Documentation/dev-tools/kunit/tips.rst - best practices with
    107    examples.
    108*   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
    109    used for testing.
    110*   Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
    111    script.
    112*   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
    113    answers.