[v1] Documentation: kunit: improve example on testing static functions

[PATCH] Documentation: kunit: improve example on testing static functions

Posted by Rae Moar 7 months ago

The documentation on testing static functions using the KUnit macros
VISIBLE_IF_KUNIT and EXPORT_SYMBOL_IF_KUNIT is lacking clarity and
missing key steps in the example. This has caused bugs and confusion
among developers.

Improve wording of description and add missing steps to the example.
This entails adding the "#include <kunit/visibility.h>" line and the
"MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING);" line. Both of which were
missing from the original example and key to exposing static functions.

Signed-off-by: Rae Moar <rmoar@google.com>
---
 Documentation/dev-tools/kunit/usage.rst | 38 +++++++++++++++++++------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst
index 22955d56b379..038f480074fd 100644
--- a/Documentation/dev-tools/kunit/usage.rst
+++ b/Documentation/dev-tools/kunit/usage.rst
@@ -670,28 +670,50 @@ with ``kunit_remove_action``.
 Testing Static Functions
 ------------------------
 
-If we do not want to expose functions or variables for testing, one option is to
-conditionally export the used symbol. For example:
+If you want to test static functions without exposing those functions outside of
+testing, one option is conditionally export the symbol. When KUnit is enabled,
+the symbol is exposed but remains static otherwise. To use this method, follow
+the template below.
 
 .. code-block:: c
 
-	/* In my_file.c */
+	/* In the file containing functions to test "my_file.c" */
 
-	VISIBLE_IF_KUNIT int do_interesting_thing();
+	#include <kunit/visibility.h>
+	#include <my_file.h>
+	...
+	VISIBLE_IF_KUNIT int do_interesting_thing()
+	{
+	...
+	}
 	EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);
 
-	/* In my_file.h */
+	/* In the header file "my_file.h" */
 
 	#if IS_ENABLED(CONFIG_KUNIT)
 		int do_interesting_thing(void);
 	#endif
 
-Alternatively, you could conditionally ``#include`` the test file at the end of
-your .c file. For example:
+	/* In the KUnit test file "my_file_test.c" */
+
+	#include <kunit/visibility.h>
+	#include <my_file.h>
+	...
+	MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING);
+	...
+	// Use do_interesting_thing() in tests
+
+For a full example, see this `patch <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>`_
+where a test is modified to conditionally expose static functions for testing
+using the macros above.
+
+As an **alternative** to the method above, you could conditionally ``#include``
+the test file at the end of your .c file. This is not recommended but works
+if needed. For example:
 
 .. code-block:: c
 
-	/* In my_file.c */
+	/* In "my_file.c" */
 
 	static int do_interesting_thing();
 

base-commit: c2493384e8110d5a4792fff4b9d46e47b78ea10a
-- 
2.49.0.1101.gccaa498523-goog

Re: [PATCH] Documentation: kunit: improve example on testing static functions

Posted by Thomas Weißschuh 7 months ago

On 2025-05-16 19:06:31+0000, Rae Moar wrote:

<snip>

> -Alternatively, you could conditionally ``#include`` the test file at the end of
> -your .c file. For example:
> +	/* In the KUnit test file "my_file_test.c" */
> +
> +	#include <kunit/visibility.h>
> +	#include <my_file.h>
> +	...
> +	MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING);

This should to be MODULE_IMPORT_NS("EXPORTED_FOR_KUNIT_TESTING").
See commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal")

Can this still be fixed up?

> +	...
> +	// Use do_interesting_thing() in tests

<snip>

Re: [PATCH] Documentation: kunit: improve example on testing static functions

Posted by David Gow 7 months ago

On Sat, 17 May 2025 at 03:06, Rae Moar <rmoar@google.com> wrote:
>
> The documentation on testing static functions using the KUnit macros
> VISIBLE_IF_KUNIT and EXPORT_SYMBOL_IF_KUNIT is lacking clarity and
> missing key steps in the example. This has caused bugs and confusion
> among developers.
>
> Improve wording of description and add missing steps to the example.
> This entails adding the "#include <kunit/visibility.h>" line and the
> "MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING);" line. Both of which were
> missing from the original example and key to exposing static functions.
>
> Signed-off-by: Rae Moar <rmoar@google.com>
> ---

It's always great to have better documentation!

Reviewed-by: David Gow <davidgow@google.com>

Thanks,
-- David

>  Documentation/dev-tools/kunit/usage.rst | 38 +++++++++++++++++++------
>  1 file changed, 30 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst
> index 22955d56b379..038f480074fd 100644
> --- a/Documentation/dev-tools/kunit/usage.rst
> +++ b/Documentation/dev-tools/kunit/usage.rst
> @@ -670,28 +670,50 @@ with ``kunit_remove_action``.
>  Testing Static Functions
>  ------------------------
>
> -If we do not want to expose functions or variables for testing, one option is to
> -conditionally export the used symbol. For example:
> +If you want to test static functions without exposing those functions outside of
> +testing, one option is conditionally export the symbol. When KUnit is enabled,
> +the symbol is exposed but remains static otherwise. To use this method, follow
> +the template below.
>
>  .. code-block:: c
>
> -       /* In my_file.c */
> +       /* In the file containing functions to test "my_file.c" */
>
> -       VISIBLE_IF_KUNIT int do_interesting_thing();
> +       #include <kunit/visibility.h>
> +       #include <my_file.h>
> +       ...
> +       VISIBLE_IF_KUNIT int do_interesting_thing()
> +       {
> +       ...
> +       }
>         EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);
>
> -       /* In my_file.h */
> +       /* In the header file "my_file.h" */
>
>         #if IS_ENABLED(CONFIG_KUNIT)
>                 int do_interesting_thing(void);
>         #endif
>
> -Alternatively, you could conditionally ``#include`` the test file at the end of
> -your .c file. For example:
> +       /* In the KUnit test file "my_file_test.c" */
> +
> +       #include <kunit/visibility.h>
> +       #include <my_file.h>
> +       ...
> +       MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING);
> +       ...
> +       // Use do_interesting_thing() in tests
> +
> +For a full example, see this `patch <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>`_
> +where a test is modified to conditionally expose static functions for testing
> +using the macros above.
> +
> +As an **alternative** to the method above, you could conditionally ``#include``
> +the test file at the end of your .c file. This is not recommended but works
> +if needed. For example:
>
>  .. code-block:: c
>
> -       /* In my_file.c */
> +       /* In "my_file.c" */
>
>         static int do_interesting_thing();
>
>
> base-commit: c2493384e8110d5a4792fff4b9d46e47b78ea10a
> --
> 2.49.0.1101.gccaa498523-goog
>