KUnit documentation rewording
Subsystems (4)
cover KUnit documentation rewording
Hi everyone, sorry for quickly resending this patch series due to duplicated patch [7/7] sent as result of amending the corresponding commit.
The proses written in KUnit documentation are IMO incomprehensible (my brain has to process what the meaning of words used) and different from wordings that I normally read from technical writings. Thus, rewrite these using clearer words.
Anyway, it's great to see native English speakers help reviewing this series.
The first two patches are v3 of rewriting "Writing Your First Test" section of "Getting Started" patch [1], which was submitted about a month ago. The rest are actual documentation rewriting.
Note that this series only rewrites intro, test writing and running docs.
[1]: https://lore.kernel.org/lkml/[email protected]/
Bagas Sanjaya (7):
Documentation: kunit: rewrite "Writing Your First Test" section
Documentation: kunit: align instruction code blocks
Documentation: kunit: rewrite the rest of "Getting Started"
documentation
Documentation: kunit: move introduction to its own document
Documentation: kunit: rewrite "Running tests with kunit_tool"
Documentation: kunit: rewrite "Run Tests without kunit_tool"
Documentation: kunit: rewrite "Writing tests"
Documentation/admin-guide/README.rst | 2 + Documentation/dev-tools/kunit/index.rst | 93 +---- Documentation/dev-tools/kunit/intro.rst | 61 ++++ Documentation/dev-tools/kunit/run_manual.rst | 68 ++-- Documentation/dev-tools/kunit/run_wrapper.rst | 302 ++++++---------- Documentation/dev-tools/kunit/start.rst | 264 +++++++------- Documentation/dev-tools/kunit/usage.rst | 322 ++++++++++-------- 7 files changed, 483 insertions(+), 629 deletions(-) create mode 100644 Documentation/dev-tools/kunit/intro.rst
base-commit: de3ee3f63400a23954e7c1ad1cb8c20f29ab6fe3
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH RESEND 1/7 Documentation: kunit: rewrite "Writing Your First Test" section
The "Writing Your First Test" section in "Getting Started" documentation have wordings that need to be tweaked for clarity and reducing redundancy. Rewrite the section.
--- Documentation/dev-tools/kunit/start.rst | 34 +++++++++++++++---------- 1 file changed, 21 insertions(+), 13 deletions(-)
Documentation/dev-tools/kunit/start.rst +21 -13
@@ -179,15 +179,19 @@ are built-in. Otherwise the module will need to be loaded. Writing Your First Test ======================= -In your kernel repository, let's add some code that we can test. +In this tutorial, you will learn how to write and test a simple driver +which performs addition of two integers. -1. Create a file ``drivers/misc/example.h``, which includes: +1. First, write the driver implementation. Follow the below steps. + + a. Create a new header file ``drivers/misc/example.h`` and add the + prototype for ``misc_example_add()``: .. code-block:: c int misc_example_add(int left, int right); -2. Create a file ``drivers/misc/example.c``, which includes: + b. Write the function implementation in ``drivers/misc/example.c``: .. code-block:: c
@@ -200,22 +204,25 @@ In your kernel repository, let's add some code that we can test. return left + right; } -3. Add the following lines to ``drivers/misc/Kconfig``: + c. In order for the driver to be selected, add configuration entry to + ``drivers/misc/Kconfig``: .. code-block:: kconfig config MISC_EXAMPLE bool "My example" -4. Add the following lines to ``drivers/misc/Makefile``: + d. Last but not least, append the make goal to ``drivers/misc/Makefile`` + so that the driver can be built: .. code-block:: make obj-$(CONFIG_MISC_EXAMPLE) += example.o -Now we are ready to write the test cases. +2. Write the test suite that covers the driver functionality. Follow the + steps below: -1. Add the below test case in ``drivers/misc/example_test.c``: + a. Write the test in ``drivers/misc/example_test.c``: .. code-block:: c
@@ -250,7 +257,7 @@ Now we are ready to write the test cases. }; kunit_test_suite(misc_example_test_suite); -2. Add the following lines to ``drivers/misc/Kconfig``: + b. Add configuration entry for the test suite to ``drivers/misc/Kconfig``: .. code-block:: kconfig
@@ -259,26 +266,27 @@ Now we are ready to write the test cases. depends on MISC_EXAMPLE && KUNIT=y default KUNIT_ALL_TESTS -3. Add the following lines to ``drivers/misc/Makefile``: + c. Append make goal for the configuration to ``drivers/misc/Makefile``: .. code-block:: make obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o -4. Add the following lines to ``.kunit/.kunitconfig``: +3. In order to enable the driver and its test suite, append configuration + fragment to ``.kunit/.kunitconfig``: .. code-block:: none CONFIG_MISC_EXAMPLE=y CONFIG_MISC_EXAMPLE_TEST=y -5. Run the test: +4. Run the test: .. code-block:: bash ./tools/testing/kunit/kunit.py run -You should see the following failure: +You should see the following output: .. code-block:: none
@@ -289,7 +297,7 @@ You should see the following failure: [16:08:57] This test never passes. ... -Congrats! You just wrote your first KUnit test. +Congrats! You have just written your first KUnit test. Next Steps ==========
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH RESEND 2/7 Documentation: kunit: align instruction code blocks
In reply to Bagas SanjayaAlign code blocks in "Writing Your First Test" instructions list so that these blocks will be rendered at the same level as surrounding paragraphs in the list.
--- Documentation/dev-tools/kunit/start.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-)
Documentation/dev-tools/kunit/start.rst +10 -10
@@ -187,13 +187,13 @@ which performs addition of two integers. a. Create a new header file ``drivers/misc/example.h`` and add the prototype for ``misc_example_add()``: -.. code-block:: c + .. code-block:: c int misc_example_add(int left, int right); b. Write the function implementation in ``drivers/misc/example.c``: -.. code-block:: c + .. code-block:: c #include <linux/errno.h>
@@ -207,7 +207,7 @@ which performs addition of two integers. c. In order for the driver to be selected, add configuration entry to ``drivers/misc/Kconfig``: -.. code-block:: kconfig + .. code-block:: kconfig config MISC_EXAMPLE bool "My example"
@@ -215,7 +215,7 @@ which performs addition of two integers. d. Last but not least, append the make goal to ``drivers/misc/Makefile`` so that the driver can be built: -.. code-block:: make + .. code-block:: make obj-$(CONFIG_MISC_EXAMPLE) += example.o
@@ -224,7 +224,7 @@ which performs addition of two integers. a. Write the test in ``drivers/misc/example_test.c``: -.. code-block:: c + .. code-block:: c #include <kunit/test.h> #include "example.h"
@@ -259,7 +259,7 @@ which performs addition of two integers. b. Add configuration entry for the test suite to ``drivers/misc/Kconfig``: -.. code-block:: kconfig + .. code-block:: kconfig config MISC_EXAMPLE_TEST tristate "Test for my example" if !KUNIT_ALL_TESTS
@@ -268,27 +268,27 @@ which performs addition of two integers. c. Append make goal for the configuration to ``drivers/misc/Makefile``: -.. code-block:: make + .. code-block:: make obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o 3. In order to enable the driver and its test suite, append configuration fragment to ``.kunit/.kunitconfig``: -.. code-block:: none + .. code-block:: none CONFIG_MISC_EXAMPLE=y CONFIG_MISC_EXAMPLE_TEST=y 4. Run the test: -.. code-block:: bash + .. code-block:: bash ./tools/testing/kunit/kunit.py run You should see the following output: -.. code-block:: none + .. code-block:: none ... [16:08:57] [PASSED] misc-example:misc_example_add_test_basic
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH RESEND 3/7 Documentation: kunit: rewrite the rest of "Getting Started" documentation
In reply to Bagas SanjayaRewrite the rest of "Getting Started" documentation for clarity. Major points:
* link to "Build directory for the kernel" section of kernel README for the caveats.
* To change kernel configurations in .kunitconfig, use configuration interfaces just like configuring normal kernel.
* Remove "Next steps" section as it will be placed on the introduction page.
--- Documentation/admin-guide/README.rst | 2 + Documentation/dev-tools/kunit/start.rst | 210 ++++++++++-------------- 2 files changed, 93 insertions(+), 119 deletions(-)
Documentation/admin-guide/README.rst +2 -0
@@ -123,6 +123,8 @@ Software requirements you can just update packages when obvious problems arise during build or operation. +.. _kernel-build-directory: + Build directory for the kernel ------------------------------
Documentation/dev-tools/kunit/start.rst +91 -119
286 lines not on this page · raw message
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH RESEND 4/7 Documentation: kunit: move introduction to its own document
In reply to Bagas SanjayaMove KUnit introduction from table of contents index to its own page.
While at it, rewrite the intro.
--- 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
Documentation/dev-tools/kunit/index.rst +1 -92
@@ -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.
Documentation/dev-tools/kunit/intro.rst new file +61 -0
61 lines not on this page · raw message
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH RESEND 5/7 Documentation: kunit: rewrite "Running tests with kunit_tool"
In reply to Bagas SanjayaRewrite the documentation for clarity. Major points:
* Switch from first-person to second-person point of view
* The configuration step is now within "Kernel configuration" section
* Replace description of common options with pointer to running --help for commands of the wrapper script
--- Documentation/dev-tools/kunit/run_wrapper.rst | 302 ++++++------------ 1 file changed, 97 insertions(+), 205 deletions(-)
Documentation/dev-tools/kunit/run_wrapper.rst +97 -205
@@ -4,21 +4,20 @@ Running tests with kunit_tool ============================= -We can either run KUnit tests using kunit_tool or can run tests -manually, and then use kunit_tool to parse the results. To run tests -manually, see: Documentation/dev-tools/kunit/run_manual.rst. -As long as we can build the kernel, we can run KUnit. +This documentation describes running tests with kunit_tool script. +If you'd like to manually run tests, see +Documentation/dev-tools/kunit/run_manual.rst. kunit_tool is a Python script which configures and builds a kernel, runs tests, and formats the test results. -Run command: +To run the tests: .. code-block:: ./tools/testing/kunit/kunit.py run -We should see the following: +You should see the following output: .. code-block::
@@ -26,124 +25,112 @@ We should see the following: Building KUnit kernel... Starting KUnit kernel... -We may want to use the following options: +You can also specify options to the script when running the tests. For +example, to run tests utilizing all available CPUs within 30 seconds +time limit: .. code-block:: ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all` -- ``--timeout`` sets a maximum amount of time for tests to run. -- ``--jobs`` sets the number of threads to build the kernel. +For list of all options, see:: -kunit_tool will generate a ``.kunitconfig`` with a default -configuration, if no other ``.kunitconfig`` file exists -(in the build directory). In addition, it verifies that the -generated ``.config`` file contains the ``CONFIG`` options in the -``.kunitconfig``. -It is also possible to pass a separate ``.kunitconfig`` fragment to -kunit_tool. This is useful if we have several different groups of -tests we want to run independently, or if we want to use pre-defined -test configs for certain subsystems. + ./tools/testing/kunit/kunit.py run --help + +Kernel configuration +==================== + +kunit_tool will generate kernel configuration named ``.kunitconfig`` +if it doesn't exist in the build directory. For list of selected options by +default, see ``tools/testing/kunit/configs/default.config`` file. + +In addition, it verifies that the synchronized ``.config`` file +contains options enabled in ``.kunitconfig``. It will errored out if +you have not enabled option dependencies required by all selected options. + +It is also possible to specify different ``.kunitconfig`` to +kunit_tool. This is useful if you have several different groups of +tests that you want to run independently, or if you want to use pre-defined +configurations for certain subsystems. To use a different ``.kunitconfig`` file (such as one -provided to test a particular subsystem), pass it as an option: +provided to test a particular subsystem), specify ``--kunitconfig`` option. +For example, to run ext4 tests: .. code-block:: ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig -To view kunit_tool flags (optional command-line arguments), run: +Customizing configuration +------------------------- -.. code-block:: +A ``.kunitconfig`` is a configuration file generated by +``make savedefconfig``, used for running enabled set of tests. This file +contains configuration options with specific enabled tests. The file also +contains any other coptions required by the tests, for example +dependencies for features under tests, arch-specific configs and so on. - ./tools/testing/kunit/kunit.py run --help - -Creating a ``.kunitconfig`` file -================================ - -If we want to run a specific set of tests (rather than those listed -in the KUnit ``defconfig``), we can provide Kconfig options in the -``.kunitconfig`` file. For default .kunitconfig, see: -https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config. -A ``.kunitconfig`` is a ``minconfig`` (a .config -generated by running ``make savedefconfig``), used for running a -specific set of tests. This file contains the regular Kernel configs -with specific test targets. The ``.kunitconfig`` also -contains any other config options required by the tests (For example: -dependencies for features under tests, configs that enable/disable -certain code blocks, arch configs and so on). - -To create a ``.kunitconfig``, using the KUnit ``defconfig``: +To generate default ``.kunitconfig``: .. code-block:: cd $PATH_TO_LINUX_REPO cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig -We can then add any other Kconfig options. For example: +You can then customize the configuration. As with configuring regular kernels +for production deployment, it is recommended to use +:doc:`one of configuration interfaces </kbuild/kconfig>`. For example, +to configure through menuconfig:: -.. code-block:: + make O=.kunit KCONFIG_CONFIG=.kunit/.kunitconfig menuconfig - CONFIG_LIST_KUNIT_TEST=y +.. note:: + ``.config`` will only be resynchronized if it is the superset of + ``.kunitconfig``. Removing any options from the latter will not + resynchronize the former. In that case, you need to manually + update the former by:: -kunit_tool ensures that all config options in ``.kunitconfig`` are -set in the kernel ``.config`` before running the tests. It warns if we -have not included the options dependencies. + cp .kunitconfig .config -.. note:: Removing something from the ``.kunitconfig`` will - not rebuild the ``.config file``. The configuration is only - updated if the ``.kunitconfig`` is not a subset of ``.config``. - This means that we can use other tools - (For example: ``make menuconfig``) to adjust other config options. - The build dir needs to be set for ``make menuconfig`` to - work, therefore by default use ``make O=.kunit menuconfig``. +Step-by-step run +================ -Configuring, building, and running tests -======================================== +It is possible to sequentially run testing steps for finer-grained control. -If we want to make manual changes to the KUnit build process, we -can run part of the KUnit build process independently. -When running kunit_tool, from a ``.kunitconfig``, we can generate a -``.config`` by using the ``config`` argument: +First, synchronize ``.config`` from ``.kunitconfig`` that have been +configured before: .. code-block:: ./tools/testing/kunit/kunit.py config -To build a KUnit kernel from the current ``.config``, we can use the -``build`` argument: +Before the tests can be run, the kernel needs to be built first: .. code-block:: ./tools/testing/kunit/kunit.py build -If we already have built UML kernel with built-in KUnit tests, we -can run the kernel, and display the test results with the ``exec`` -argument: +The whole tests can now be executed: .. code-block:: ./tools/testing/kunit/kunit.py exec -The ``run`` command discussed in section: **Running tests with kunit_tool**, -is equivalent to running the above three commands in sequence. - Parsing test results ==================== -KUnit tests output displays results in TAP (Test Anything Protocol) -format. When running tests, kunit_tool parses this output and prints -a summary. To see the raw test results in TAP format, we can pass the -``--raw_output`` argument: +KUnit generates test results in TAP (Test Anything Protocol) format. When +the tests are running, kunit_tool parses the result and prints +the summary. To see the results in raw TAP format, you can pass +``--raw_output`` option: .. code-block:: ./tools/testing/kunit/kunit.py run --raw_output -If we have KUnit results in the raw TAP format, we can parse them and -print the human-readable summary with the ``parse`` command for -kunit_tool. This accepts a filename for an argument, or will read from -standard input. +Now you can parse the output and print the human-readable summary with the +``parse`` command. It accepts the filename argument. If none is given, it +will read from standard input. .. code-block:: bash
@@ -155,74 +142,63 @@ standard input. Filtering tests =============== -By passing a bash style glob filter to the ``exec`` or ``run`` -commands, we can run a subset of the tests built into a kernel . For -example: if we only want to run KUnit resource tests, use: +You can also specify tests using :manpage:`glob(7)` pattern. For example, +to run resource tests (which are prefixed by ``kunit-resource``): .. code-block:: ./tools/testing/kunit/kunit.py run 'kunit-resource*' -This uses the standard glob format with wildcard characters. - .. _kunit-on-qemu: Running tests on QEMU ===================== -kunit_tool supports running tests on qemu as well as -via UML. To run tests on qemu, by default it requires two flags: +Besides running tests with UML kernel, kunit_wrapper also supports +running tests on QEMU. Two options are required for this to work: -- ``--arch``: Selects a configs collection (Kconfig, qemu config options - and so on), that allow KUnit tests to be run on the specified - architecture in a minimal way. The architecture argument is same as - the option name passed to the ``ARCH`` variable used by Kbuild. - Not all architectures currently support this flag, but we can use - ``--qemu_config`` to handle it. If ``um`` is passed (or this flag - is ignored), the tests will run via UML. Non-UML architectures, - for example: i386, x86_64, arm and so on; run on qemu. +- ``--arch``: Run tests for the specified architecture. The value will be + passed to make as ``ARCH`` environment variable. + Not all architectures currently support this flag. For such architectures, + use ``--qemu_config`` instead (discussed later). If ``um`` is specifed (or + if this option is not given), the tests will run in UML kernel. Otherwise, + the tests run on QEMU. -- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the - same argument as passed to the ``CROSS_COMPILE`` variable used by - Kbuild. As a reminder, this will be the prefix for the toolchain - binaries such as GCC. For example: +- ``--cross_compile``: Specifies the cross-compiler toolchain prefix. + The value will be used for ``CROSS_COMPILE`` environment variable when + building the kernel. - - ``sparc64-linux-gnu`` if we have the sparc toolchain installed on - our system. +Examples: - - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`` - if we have downloaded the microblaze toolchain from the 0-day - website to a directory in our home directory called toolchains. + - To run tests for native x86_64 architecture: -This means that for most architectures, running under qemu is as simple as: - -.. code-block:: bash + .. code-block:: bash ./tools/testing/kunit/kunit.py run --arch=x86_64 -When cross-compiling, we'll likely need to specify a different toolchain, for -example: + - To cross-compile and test for s390: -.. code-block:: bash + .. code-block:: bash ./tools/testing/kunit/kunit.py run \ --arch=s390 \ --cross_compile=s390x-linux-gnu- -If we want to run KUnit tests on an architecture not supported by -the ``--arch`` flag, or want to run KUnit tests on qemu using a -non-default configuration; then we can write our own``QemuConfig``. -These ``QemuConfigs`` are written in Python. They have an import line -``from..qemu_config import QemuArchParams`` at the top of the file. -The file must contain a variable called ``QEMU_ARCH`` that has an -instance of ``QemuArchParams`` assigned to it. See example in: -``tools/testing/kunit/qemu_configs/x86_64.py``. +Custom QEMU configuration +------------------------- +If you want to test on an architecture unsupported by the ``--arch`` option, +or to customize QEMU invocation, you can write ``QemuConfig`` configuration, +which is written in Python. The file begins with +:code:`from..qemu_config import QemuArchParams` as import directive. +The file must contain an object called ``QEMU_ARCH`` which is +built from ``QemuArchParams`` class. -Once we have a ``QemuConfig``, we can pass it into kunit_tool, -using the ``--qemu_config`` flag. When used, this flag replaces the -``--arch`` flag. For example: using -``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear -as +Once ``QemuConfig`` have been configured, you can specify the file to +kunit_tool using the ``--qemu_config`` option. This overrides ``--arch`` +option. + +For example, to specify QEMU configuration for native x86_64 architecture +with 12 build jobs and 60 seconds timeout: .. code-block:: bash
@@ -231,93 +207,9 @@ as --jobs=12 \ --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py -Running command-line arguments -============================== +Command options +=============== -kunit_tool has a number of other command-line arguments which can -be useful for our test environment. Below are the most commonly used -command line arguments: +To see a list of options for a particular command (along with usage), see:: -- ``--help``: Lists all available options. To list common options, - place ``--help`` before the command. To list options specific to that - command, place ``--help`` after the command. - - .. note:: Different commands (``config``, ``build``, ``run``, etc) - have different supported options. -- ``--build_dir``: Specifies kunit_tool build directory. It includes - the ``.kunitconfig``, ``.config`` files and compiled kernel. - -- ``--make_options``: Specifies additional options to pass to make, when - compiling a kernel (using ``build`` or ``run`` commands). For example: - to enable compiler warnings, we can pass ``--make_options W=1``. - -- ``--alltests``: Enable a predefined set of options in order to build - as many tests as possible. - - .. note:: The list of enabled options can be found in - ``tools/testing/kunit/configs/all_tests.config``. - - If you only want to enable all tests with otherwise satisfied - dependencies, instead add ``CONFIG_KUNIT_ALL_TESTS=y`` to your - ``.kunitconfig``. - -- ``--kunitconfig``: Specifies the path or the directory of the ``.kunitconfig`` - file. For example: - - - ``lib/kunit/.kunitconfig`` can be the path of the file. - - - ``lib/kunit`` can be the directory in which the file is located. - - This file is used to build and run with a predefined set of tests - and their dependencies. For example, to run tests for a given subsystem. - -- ``--kconfig_add``: Specifies additional configuration options to be - appended to the ``.kunitconfig`` file. For example: - - .. code-block:: - - ./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y - -- ``--arch``: Runs tests on the specified architecture. The architecture - argument is same as the Kbuild ARCH environment variable. - For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu. - Default is `um`. - -- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the - same argument as passed to the ``CROSS_COMPILE`` variable used by - Kbuild. This will be the prefix for the toolchain - binaries such as GCC. For example: - - - ``sparc64-linux-gnu-`` if we have the sparc toolchain installed on - our system. - - - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`` - if we have downloaded the microblaze toolchain from the 0-day - website to a specified path in our home directory called toolchains. - -- ``--qemu_config``: Specifies the path to a file containing a - custom qemu architecture definition. This should be a python file - containing a `QemuArchParams` object. - -- ``--qemu_args``: Specifies additional qemu arguments, for example, ``-smp 8``. - -- ``--jobs``: Specifies the number of jobs (commands) to run simultaneously. - By default, this is set to the number of cores on your system. - -- ``--timeout``: Specifies the maximum number of seconds allowed for all tests to run. - This does not include the time taken to build the tests. - -- ``--kernel_args``: Specifies additional kernel command-line arguments. May be repeated. - -- ``--run_isolated``: If set, boots the kernel for each individual suite/test. - This is useful for debugging a non-hermetic test, one that - might pass/fail based on what ran before it. - -- ``--raw_output``: If set, generates unformatted output from kernel. Possible options are: - - - ``all``: To view the full kernel output, use ``--raw_output=all``. - - - ``kunit``: This is the default option and filters to KUnit output. Use ``--raw_output`` or ``--raw_output=kunit``. - -- ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or - saves to a file if a filename is specified. + ./tools/testing/kunit/kunit.py <command> --help
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH RESEND 6/7 Documentation: kunit: rewrite "Run Tests without kunit_tool"
In reply to Bagas SanjayaRewrite 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)
--- Documentation/dev-tools/kunit/run_manual.rst | 68 ++++++++------------ 1 file changed, 27 insertions(+), 41 deletions(-)
Documentation/dev-tools/kunit/run_manual.rst +27 -41
@@ -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``.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH RESEND 7/7 Documentation: kunit: rewrite "Writing tests"
In reply to Bagas SanjayaRewrite the documentation for clarity. Major points:
* Switch to third person point of view
* Briefly describe code examples before giving them out
* Use "base" and "derived" terminology on class inheritance
--- Documentation/dev-tools/kunit/usage.rst | 322 +++++++++++++----------- 1 file changed, 173 insertions(+), 149 deletions(-)
Documentation/dev-tools/kunit/usage.rst +173 -149
@@ -6,9 +6,11 @@ Writing Tests Test Cases ---------- -The fundamental unit in KUnit is the test case. A test case is a function with -the signature ``void (*)(struct kunit *test)``. It calls the function under test -and then sets *expectations* for what should happen. For example: +The fundamental unit in KUnit is the test case. A test case in KUnit is a +function with the signature ``void (*)(struct kunit *test)``. It calls the +function under test and then sets *expectations* for what should happen. + +Below are the simplest examples: .. code-block:: c
@@ -22,18 +24,17 @@ and then sets *expectations* for what should happen. For example: } In the above example, ``example_test_success`` always passes because it does -nothing; no expectations are set, and therefore all expectations pass. On the -other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``, -which is a special expectation that logs a message and causes the test case to -fail. +nothing (there are no expectations set). On the +other hand ``example_test_failure`` always fails because it calls +``KUNIT_FAIL``, which is a special function that logs the message string and +signal the test as failed. Expectations ~~~~~~~~~~~~ -An *expectation* specifies that we expect a piece of code to do something in a -test. An expectation is called like a function. A test is made by setting -expectations about the behavior of a piece of code under test. When one or more -expectations fail, the test case fails and information about the failure is -logged. For example: +An *expectation* specifies the expected behavior of tested function. It is +written as regular function call. A test is made by asserting one or more +expectations in the test case. When any of these is not satisfied, the test +case fails and information about the failure is logged. For example: .. code-block:: c
@@ -43,18 +44,16 @@ logged. For example: KUNIT_EXPECT_EQ(test, 2, add(1, 1)); } -In the above example, ``add_test_basic`` makes a number of assertions about the -behavior of a function called ``add``. The first parameter is always of type +In the above example, ``add_test_basic`` tests a function called ``add()``. +The first parameter to ``KUNIT_EXPECT_EQ`` is always of type ``struct kunit *``, which contains information about the current test context. -The second parameter, in this case, is what the value is expected to be. The -last value is what the value actually is. If ``add`` passes all of these -expectations, the test case, ``add_test_basic`` will pass; if any one of these -expectations fails, the test case will fail. +The second parameter is what the value is expected to be returned by the +function. The last is value returned by calling the tested function. -A test case *fails* when any expectation is violated; however, the test will -continue to run, and try other expectations until the test case ends or is -otherwise terminated. This is as opposed to *assertions* which are discussed -later. +Even though a single expectation is not satisfied, the test will +continue to run and try asserting the following expectations until either +the test case ends or is terminated. This is as opposed to *assertions* which +are discussed later. To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.
@@ -62,9 +61,8 @@ To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/te A single test case should be short, easy to understand, and focused on a single behavior. -For example, if we want to rigorously test the ``add`` function above, create -additional tests cases which would test each property that an ``add`` function -should have as shown below: +The example below extends ``add()`` tests with cases for negative values +and edge cases involving ``INT_MIN`` and ``INT_MAX`` constants: .. code-block:: c
@@ -93,8 +91,10 @@ should have as shown below: Assertions ~~~~~~~~~~ -An assertion is like an expectation, except that the assertion immediately -terminates the test case if the condition is not satisfied. For example: +An assertion is like an expectation, except that it immediately +terminates the test case if the condition is false. + +The following example demonstrate testing ``sort()`` function: .. code-block:: c
@@ -112,21 +112,22 @@ terminates the test case if the condition is not satisfied. For example: KUNIT_EXPECT_LE(test, a[i], a[i + 1]); } -In this example, the method under test should return pointer to a value. If the -pointer returns null or an errno, we want to stop the test since the following -expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us -to bail out of the test case if the appropriate conditions are not satisfied to -complete the test. +In this example, the method under test should return pointer to a value. If +it instead returns null pointer or errno, the test case should be bailed out +with ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` since the following expectation that +asserts the array order could crash it. Test Suites ~~~~~~~~~~~ -We need many test cases covering all the unit's behaviors. It is common to have -many similar tests. In order to reduce duplication in these closely related -tests, most unit testing frameworks (including KUnit) provide the concept of a -*test suite*. A test suite is a collection of test cases for a unit of code -with optional setup and teardown functions that run before/after the whole -suite and/or every test case. For example: +It is common to have many similar tests cases in order to test the code +behavior. In order to reduce duplication in these closely related +tests, most unit testing frameworks (including KUnit) provide the *test suite* +concept. A test suite is a collection of test cases for a particularcode +with optional setup and cleanup functions that run before/after the whole +suite and/or every test case. + +Below is an example of writing a test suite: .. code-block:: c
@@ -147,21 +148,21 @@ suite and/or every test case. For example: }; kunit_test_suite(example_test_suite); -In the above example, the test suite ``example_test_suite`` would first run -``example_suite_init``, then run the test cases ``example_test_foo``, -``example_test_bar``, and ``example_test_baz``. Each would have -``example_test_init`` called immediately before it and ``example_test_exit`` -called immediately after it. Finally, ``example_suite_exit`` would be called -after everything else. ``kunit_test_suite(example_test_suite)`` registers the -test suite with the KUnit test framework. +In the above example, running ``example_test_suite`` will initialize the +suite with ``example_suite_init``, then run three cases ``example_test_foo``, +``example_test_bar``, and ``example_test_baz``. Each case will be initialized +with ``example_test_init`` and ``example_test_exit`` will take care of +case-specific cleanup after the case have been finished. Finally, +``example_suite_exit`` will do suite-wide cleanup, then finish the suite. +``kunit_test_suite(example_test_suite)`` registers the test suite with KUnit. .. note:: A test case will only run if it is associated with a test suite. -``kunit_test_suite(...)`` is a macro which tells the linker to put the -specified test suite in a special linker section so that it can be run by KUnit -either after ``late_init``, or when the test module is loaded (if the test was -built as a module). +``kunit_test_suite()`` is a macro which tells the linker to put the specified +test suite in a special linker section so that it can be run either after +``late_init``, or when the test module is loaded (if the test was built as +module). For more information, see Documentation/dev-tools/kunit/api/test.rst.
@@ -170,25 +171,23 @@ For more information, see Documentation/dev-tools/kunit/api/test.rst. Writing Tests For Other Architectures ------------------------------------- -It is better to write tests that run on UML to tests that only run under a -particular architecture. It is better to write tests that run under QEMU or -another easy to obtain (and monetarily free) software environment to a specific -piece of hardware. +In many cases, it is better to write tests that can be run on UML or QEMU +without requiring any specific architecture or hardware, since these can +be practically run by any machine that is capable of cross-compiling. -Nevertheless, there are still valid reasons to write a test that is architecture -or hardware specific. For example, we might want to test code that really -belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does -not depend on physical hardware. Some of our test cases may not need hardware, -only few tests actually require the hardware to test it. When hardware is not -available, instead of disabling tests, we can skip them. +Nevertheless, there are still valid reasons to write architecture-specific +or hardware-specific tests. For example, you might want to test codes that +are in ``arch/some-arch/*``. Even so, try to write tests so that it does +not require specific hardware to run them. A test suite may contain +hardware-specific cases. These can be skipped if the hardware is not +available. -Now that we have narrowed down exactly what bits are hardware specific, the -actual procedure for writing and running the tests is same as writing normal -KUnit tests. +Writing architecture-specific and hardware-specific tests is the same as +writing any other tests. .. important:: - We may have to reset hardware state. If this is not possible, we may only - be able to run one test case per invocation. + In some cases you need to reset hardware state after each test case, + otherwise only one case can be run per test suite. .. TODO([email protected]): Add an actual example of an architecture- dependent KUnit test.
@@ -200,38 +199,41 @@ Isolating Behavior ------------------ Unit testing limits the amount of code under test to a single unit. It controls -what code gets run when the unit under test calls a function. Where a function -is exposed as part of an API such that the definition of that function can be +what code gets run when the unit under test calls a function. When a function +is exposed as part of an API, the function definition can be changed without affecting the rest of the code base. In the kernel, this comes from two constructs: classes, which are structs that contain function pointers -provided by the implementer, and architecture-specific functions, which have -definitions selected at compile time. +provided by the implementer; and architecture-specific functions, which have +definitions determined at compile time. Classes ~~~~~~~ -Classes are not a construct that is built into the C programming language; -however, it is an easily derived concept. Accordingly, in most cases, every -project that does not use a standardized object oriented library (like GNOME's -GObject) has their own slightly different way of doing object oriented -programming; the Linux kernel is no exception. +The C programming language does not have the formal notion of class-based +object-oriented programming, hovewer the paradigm can be applied within +procedural framework. Accordingly, every project has their own slightly +different way of doing object oriented programming (such as GNOME's GObject); +the Linux kernel is no exception. The central concept in kernel object oriented programming is the class. In the kernel, a *class* is a struct that contains function pointers. This creates a contract between *implementers* and *users* since it forces them to use the -same function signature without having to call the function directly. To be a -class, the function pointers must specify that a pointer to the class, known as -a *class handle*, be one of the parameters. Thus the member functions (also -known as *methods*) have access to member variables (also known as *fields*) -allowing the same implementation to have multiple *instances*. +same function signature without having to call the function directly. In order +to be a class, the function pointers must specify that a pointer to the class +(known as a *class handle*) be one of the parameters; thus the member functions +(also known as *methods*) have access to member variables (also known as +*fields*), allowing the same implementation to have multiple *instances*. -A class can be *overridden* by *child classes* by embedding the *parent class* -in the child class. Then when the child class *method* is called, the child -implementation knows that the pointer passed to it is of a parent contained -within the child. Thus, the child can compute the pointer to itself because the -pointer to the parent is always a fixed offset from the pointer to the child. -This offset is the offset of the parent contained in the child struct. For -example: +A class can be *overridden* by *derived classes* by embedding the *base class* +in the derived class. Then when the dervied class *method* is called, the +derived class implementation knows that the pointer passed to it is of a base +class contained within the derived class. Thus, the child can compute the +pointer to itself because the pointer to the base class is always a fixed +offset from the pointer to the derived class. This offset is the offset of the +base class contained in the struct of derived class. + +The example below defines a base class ``shape`` and derived class +``rectangle`` along with class implementations: .. code-block:: c
@@ -259,8 +261,8 @@ example: self->width = width; } -In this example, computing the pointer to the child from the pointer to the -parent is done by ``container_of``. +In this example, computing the pointer to ``rectangle`` from the pointer to +the ``shape`` is taken care of by ``container_of`` method. Faking Classes ~~~~~~~~~~~~~~
@@ -269,11 +271,13 @@ In order to unit test a piece of code that calls a method in a class, the behavior of the method must be controllable, otherwise the test ceases to be a unit test and becomes an integration test. -A fake class implements a piece of code that is different than what runs in a -production instance, but behaves identical from the standpoint of the callers. -This is done to replace a dependency that is hard to deal with, or is slow. For -example, implementing a fake EEPROM that stores the "contents" in an -internal buffer. Assume we have a class that represents an EEPROM: +A fake class implements a piece of code that interfaces to actual code +used in production. This is done to replace code dependencies that is hard to +deal with (expensive or impossible to duplicate), or is slow. + +The examples below shows how to test fake EEPROM implementation that stores +its contents in an internal buffer. Assume that there is ``eeprom`` class, +which is defined as: .. code-block:: c
@@ -282,7 +286,8 @@ internal buffer. Assume we have a class that represents an EEPROM: ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count); }; -And we want to test code that buffers writes to the EEPROM: +Supposes that you want to test ``eeprom_buffer`` class, which writes the +contents to actual EEPROM: .. code-block:: c
@@ -295,7 +300,8 @@ And we want to test code that buffers writes to the EEPROM: struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom); void destroy_eeprom_buffer(struct eeprom *eeprom); -We can test this code by *faking out* the underlying EEPROM: +In order to test ``eeprom_buffer``, you need *faking out* the underlying +EEPROM with ``fake_eeprom``, which is derived from ``eeprom``: .. code-block:: c
@@ -331,7 +337,7 @@ We can test this code by *faking out* the underlying EEPROM: memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE); } -We can now use it to test ``struct eeprom_buffer``: +You can now use it to test ``eeprom_buffer``: .. code-block:: c
@@ -425,11 +431,12 @@ We can now use it to test ``struct eeprom_buffer``: Testing Against Multiple Inputs ------------------------------- -Testing just a few inputs is not enough to ensure that the code works correctly, -for example: testing a hash function. +Sometimes in order to correctly test the code, many inputs are required. In +such cases, you can write a helper macro or function. The helper can be +called for each test input. -We can write a helper macro or function. The function is called for each input. -For example, to test ``sha1sum(1)``, we can write: +The following example defines ``TEST_SHA1`` helper macro for testing +:manpage:`sha1sum(1)`. The macro is called on 2 test cases: .. code-block:: c
@@ -444,12 +451,15 @@ For example, to test ``sha1sum(1)``, we can write: Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more detailed error and make the assertions clearer within the helper macros. -The ``_MSG`` variants are useful when the same expectation is called multiple -times (in a loop or helper function) and thus the line number is not enough to -identify what failed, as shown below. +The ``_MSG`` variants are useful when the same expectation is asserted +multiple times (in a loop or helper function), since the line number alone is +not enough to identify the failure, as shown below. -In complicated cases, we recommend using a *table-driven test* compared to the -helper macro variation, for example: +In complicated cases, it is recommended to use *table-driven test* pattern +instead. + +The following example does the same test as above, but the test cases are +defined in an array of struct: .. code-block:: c
@@ -478,18 +488,14 @@ helper macro variation, for example: } -There is more boilerplate code involved, but it can: +There are advantages of *table-driven tests*: -* be more readable when there are multiple inputs/outputs (due to field names). - - * For example, see ``fs/ext4/inode-test.c``. - -* reduce duplication if test cases are shared across multiple tests. - - * For example: if we want to test ``sha256sum``, we could add a ``sha256`` - field and reuse ``cases``. - -* be converted to a "parameterized test". +* The test is more readable when there are many inputs and expected outputs. + See ``fs/ext4/inode-test.c`` for example. +* It can reduce duplication if test cases are shared across multiple tests. + For example, if you want to also test :manpage:`sha256sum(1)`, you can + simply add ``sha256`` field to ``cases``. +* The test can be turned into "parameterized test", see below subsection. Parameterized Testing ~~~~~~~~~~~~~~~~~~~~~
@@ -497,8 +503,8 @@ Parameterized Testing The table-driven testing pattern is common enough that KUnit has special support for it. -By reusing the same ``cases`` array from above, we can write the test as a -"parameterized test" with the following. +The following example does the same :manpage:`sha1sum(1)` test as above, +but is written using parameterized testing facilities: .. code-block:: c
@@ -526,7 +532,7 @@ By reusing the same ``cases`` array from above, we can write the test as a // Creates `sha1_gen_params()` to iterate over `cases`. KUNIT_ARRAY_PARAM(sha1, cases, case_to_desc); - // Looks no different from a normal test. + // Looks no different from other tests. static void sha1_test(struct kunit *test) { // This function can just contain the body of the for-loop.
@@ -539,7 +545,7 @@ By reusing the same ``cases`` array from above, we can write the test as a "sha1sum(%s)", test_param->str); } - // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the + // Instead of KUNIT_CASE, use KUNIT_CASE_PARAM and pass in the // function declared by KUNIT_ARRAY_PARAM. static struct kunit_case sha1_test_cases[] = { KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
@@ -549,9 +555,13 @@ By reusing the same ``cases`` array from above, we can write the test as a Exiting Early on Failed Expectations ------------------------------------ -We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue -execution. In some cases, it is unsafe to continue. We can use the -``KUNIT_ASSERT`` variant to exit on failure. +All the tests until now uses ``KUNIT_EXPECT`` macros to assert expectations. +In case of any of these are failed, the test continues. However, in some +cases, continuing tests is not possible or is unsafe. For these cases, +you can use ``KUNIT_ASSERT`` variant to exit early on failure. + +The example below tests allocating objects then play with them. Only if +the allocation succeed, these objects can be played with: .. code-block:: c
@@ -567,12 +577,15 @@ execution. In some cases, it is unsafe to continue. We can use the Allocating Memory ----------------- -Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit -will then ensure that the memory is freed once the test completes. +When ``kzalloc`` may be used to allocate memory, you can instead use +``kunit_kzalloc`` as KUnit will then ensure that the memory is freed once +the test completes. -This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit -early from a test without having to worry about remembering to call ``kfree``. -For example: +This is useful because it lets you to use ``KUNIT_ASSERT_EQ`` macros to exit +early from a test without having to worry about remembering to freeing +memory with ``kfree``. + +The following example tests allocating buffer memory: .. code-block:: c
@@ -589,9 +602,11 @@ For example: Testing Static Functions ------------------------ -If we do not want to expose functions or variables for testing, one option is to -conditionally ``#include`` the test file at the end of your .c file. For -example: +If you do not want to expose testing functions or variables unconditionally, +you can ``#include`` the test file inside ``#ifdef`` guard. + +In the example below, the test code in ``my_kunit_test.c`` is included and +compiled only if ``CONFIG_MY_KUNIT_TEST`` is enabled: .. code-block:: c
@@ -606,7 +621,11 @@ example: Injecting Test-Only Code ------------------------ -Similar to as shown above, we can add test-specific logic. For example: +You can also add test-only logic inside the guard. + +In the following example, prototype of ``test_only_hook()`` is defined with +``CONFIG_MY_KUNIT_TEST`` both enabled and disabled. In case the configuration +is disabled, the hook is defined as empty function: .. code-block:: c
@@ -619,19 +638,21 @@ Similar to as shown above, we can add test-specific logic. For example: void test_only_hook(void) { } #endif -This test-only code can be made more useful by accessing the current ``kunit_test`` -as shown in next section: *Accessing The Current Test*. +This can be made more useful by accessing the current ``kunit_test`` +as shown in next section below. Accessing The Current Test -------------------------- -In some cases, we need to call test-only code from outside the test file. -For example, see example in section *Injecting Test-Only Code* or if -we are providing a fake implementation of an ops struct. Using -``kunit_test`` field in ``task_struct``, we can access it via -``current->kunit_test``. +In some cases, it is desired to call test-only code from outside the test +file. See example from previous section for how this can be done by +including the test file. -The example below includes how to implement "mocking": +Another way is to provide the fake implementation of an ops struct. For +example, given ``kunit_test`` field in ``task_struct``, the field can be +accessed via ``current->kunit_test``. + +The example below shows how to implement "mocking" pattern: .. code-block:: c
@@ -665,25 +686,28 @@ The example below includes how to implement "mocking": KUNIT_EXPECT_EQ(test, fake_foo(1), 42); } -In this example, we are using the ``priv`` member of ``struct kunit`` as a way +In this example, ``kunit->priv`` is used as a way of passing data to the test from the init function. In general ``priv`` is pointer that can be used for any user data. This is preferred over static variables, as it avoids concurrency issues. -Had we wanted something more flexible, we could have used a named ``kunit_resource``. -Each test can have multiple resources which have string names providing the same -flexibility as a ``priv`` member, but also, for example, allowing helper +In cases where you want something more flexible, ``kunit_resource`` can be +used instead. Each test can have multiple resources which have names providing +the same flexibility as ``priv``, but also, for example, allowing helper functions to create resources without conflicting with each other. It is also -possible to define a clean up function for each resource, making it easy to -avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst. +possible to define clean up routines for each resource, making it easy to +avoid leaking. For more information, see +Documentation/dev-tools/kunit/api/test.rst. Failing The Current Test ------------------------ -If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)`` -which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``. -For example, we have an option to enable some extra debug checks on some data -structures as shown below: +If you want to fail the current test with a meaningful reason, you can use +``kunit_fail_current_test()``, which is defined in ``<kunit/test-bug.h>``. +It does not require pulling in ``<kunit/test.h>``. + +The following example have the extra validation over ``data`` struct, which +is only done when ``CONFIG_EXTRA_DEBUG_CHECKS`` is enabled: .. code-block:: c
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Quoted 12 lines · Bagas Sanjaya
Hi everyone, sorry for quickly resending this patch series due to duplicated patch [7/7] sent as result of amending the corresponding commit.
The proses written in KUnit documentation are IMO incomprehensible (my brain has to process what the meaning of words used) and different from wordings that I normally read from technical writings. Thus, rewrite these using clearer words.
Anyway, it's great to see native English speakers help reviewing this series.
Quoted 8 lines
The first two patches are v3 of rewriting "Writing Your First Test" section of "Getting Started" patch [1], which was submitted about a month ago. The rest are actual documentation rewriting.
Note that this series only rewrites intro, test writing and running docs.
ping