linux-kernel - [PATCH RESEND 1/7] Documentation: kunit: rewrite "Writing Your First Test" section

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20221023130846.63296-2-bagasdotme@gmail.com>
Date:   Sun, 23 Oct 2022 20:08:41 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        linux-kselftest@...r.kernel.org, kunit-dev@...glegroups.com
Cc:     Jonathan Corbet <corbet@....net>,
        Brendan Higgins <brendan.higgins@...ux.dev>,
        David Gow <davidgow@...gle.com>,
        Lukas Bulwahn <lukas.bulwahn@...il.com>,
        Khalid Masum <khalid.masum.92@...il.com>,
        Sadiya Kazi <sadiyakazi@...gle.com>,
        Bagas Sanjaya <bagasdotme@...il.com>
Subject: [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@...il.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
 ==========
-- 
An old man doll... just what I always wanted! - Clara