Skip to contentSkip to conversation

Documentation: KUnit: Update filename best practices

PATCH Applied Kees Cook 3 participants 4 messages Jul 24, 2024 – Aug 27, 2024

Subsystems (4)
lore
Share & tools
lore

Kees Cook

author
#0 lore raw

PATCH v3 1/1 Documentation: KUnit: Update filename best practices

Based on feedback from Linus[1] and follow-up discussions, change the suggested file naming for KUnit tests.

---
v3: additional clarification
v2: https://lore.kernel.org/all/[email protected]/
Cc: David Gow <[email protected]>
Cc: Brendan Higgins <[email protected]>
Cc: Rae Moar <[email protected]>
Cc: John Hubbard <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: Linus Torvalds <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]

---
 Documentation/dev-tools/kunit/style.rst | 29 +++++++++++++++++--------
 1 file changed, 20 insertions(+), 9 deletions(-)
Documentation/dev-tools/kunit/style.rst +20 -9
index b6d0d7359f00..eac81a714a29 100644
@@ -188,15 +188,26 @@ For example, a Kconfig entry might look like:
 Test File and Module Names
 ==========================
 
-KUnit tests can often be compiled as a module. These modules should be named
-after the test suite, followed by ``_test``. If this is likely to conflict with
-non-KUnit tests, the suffix ``_kunit`` can also be used.
+KUnit tests are often compiled as a separate module. To avoid conflicting
+with regular modules, KUnit modules should be named after the test suite,
+followed by ``_kunit`` (e.g. if "foobar" is the core module, then
+"foobar_kunit" is the KUnit test module).
 
-The easiest way of achieving this is to name the file containing the test suite
-``<suite>_test.c`` (or, as above, ``<suite>_kunit.c``). This file should be
-placed next to the code under test.
+Test source files, whether compiled as a separate module or an
+``#include`` in another source file, are best kept in a ``tests/``
+subdirectory to not conflict with other source files (e.g. for
+tab-completion).
+
+Note that the ``_test`` suffix has also been used in some existing
+tests. The ``_kunit`` suffix is preferred, as it makes the distinction
+between KUnit and non-KUnit tests clearer.
+
+So for the common case, name the file containing the test suite
+``tests/<suite>_kunit.c``. The ``tests`` directory should be placed at
+the same level as the code under test. For example, tests for
+``lib/string.c`` live in ``lib/tests/string_kunit.c``.
 
 If the suite name contains some or all of the name of the test's parent
-directory, it may make sense to modify the source filename to reduce redundancy.
-For example, a ``foo_firmware`` suite could be in the ``foo/firmware_test.c``
-file.
+directory, it may make sense to modify the source filename to reduce
+redundancy. For example, a ``foo_firmware`` suite could be in the
+``foo/tests/firmware_kunit.c`` file.
Signature · 1 line
2.34.1
Reviewed-by on v3 1/1
#1 lore raw
Quoted 8 lines · Kees Cook

Based on feedback from Linus[1] and follow-up discussions, change the suggested file naming for KUnit tests.

---

Looks good to me. (And it seems like sphinx is okay with it, too, which is always nice.)

We normally take these changes in via the kunit tree, but if you want to try to push it through along with the naming changes, that's fine by me.

Thanks,
-- David

author
#2 lore raw
Quoted 10 lines · David Gow
Quoted 8 lines · Kees Cook

Based on feedback from Linus[1] and follow-up discussions, change the suggested file naming for KUnit tests.

---

Quoted 8 lines

Looks good to me. (And it seems like sphinx is okay with it, too, which is always nice.)

We normally take these changes in via the kunit tree, but if you want to try to push it through along with the naming changes, that's fine by me.

Hi! Just a quick check: I haven't seen this land in -next yet. Are you still planning to take this?

Signature · 1 line
Kees Cook
maintainer Applied
#3 lore raw
Quoted 14 lines · Kees Cook
Quoted 13 lines · David Gow
Quoted 8 lines · Kees Cook

Based on feedback from Linus[1] and follow-up discussions, change the suggested file naming for KUnit tests.

---

Looks good to me. (And it seems like sphinx is okay with it, too, which is always nice.)

Quoted 9 lines
Quoted 5 lines

We normally take these changes in via the kunit tree, but if you want to try to push it through along with the naming changes, that's fine by me.

Hi! Just a quick check: I haven't seen this land in -next yet. Are you still planning to take this?

I applied it yesterday to kunit next.

thanks,
-- Shuah