[1/7] Documentation: kunit: rewrite "Writing Your First Test" section

Commit Message

Bagas Sanjaya Oct. 23, 2022, 12:54 p.m. UTC

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 <[e-mail]>
---
 Documentation/dev-tools/kunit/start.rst | 34 +++++++++++++++----------
 1 file changed, 21 insertions(+), 13 deletions(-)

Patch

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
 ==========