[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.

Signed-off-by: Bagas Sanjaya bagasdotme@gmail.com --- Documentation/dev-tools/kunit/start.rst | 34 +++++++++++++++---------- 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index f4f504f1fb154f..590e25166efb0d 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -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 ==========