[PATCH v2] Documentation: kunit: Clarify test filter format

[PATCH v2] Documentation: kunit: Clarify test filter format

[Brendan Jackman]

It seems obvious once you know, but at first I didn't realise that the
suite name is part of this format. Document it and add some examples.

Signed-off-by: Brendan Jackman <jackmanb@google.com>
---
v1->v2: Expanded to clarify that suite_glob and test_glob are two separate
	patterns. Also made some other trivial changes to formatting etc.

 Documentation/dev-tools/kunit/run_wrapper.rst | 33 +++++++++++++++++--
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
index 19ddf5e07013..b07252d3fa9d 100644
--- a/Documentation/dev-tools/kunit/run_wrapper.rst
+++ b/Documentation/dev-tools/kunit/run_wrapper.rst
@@ -156,12 +156,39 @@ Filtering tests
 ===============
 
 By passing a bash style glob filter to the ``exec`` or ``run``
-commands, we can run a subset of the tests built into a kernel . For
-example: if we only want to run KUnit resource tests, use:
+commands, we can run a subset of the tests built into a kernel,
+identified by a string like ``<suite_glob>[.<test_glob>]``.
+
+For example, to run the ``kunit-resource-test`` suite:
+
+.. code-block::
+
+	./tools/testing/kunit/kunit.py run kunit-resource-test
+
+To run a specific test from that suite:
+
+.. code-block::
+
+	./tools/testing/kunit/kunit.py run kunit-resource-test.kunit_resource_test
+
+To run all tests from suites whose names start with ``kunit``:
+
+.. code-block::
+
+	./tools/testing/kunit/kunit.py run 'kunit*'
+
+To run all tests whose name ends with ``remove_resource``:
+
+.. code-block::
+
+	./tools/testing/kunit/kunit.py run '*.*remove_resource'
+
+To run all tests whose name ends with ``remove_resource``, from suites whose
+names start with ``kunit``:
 
 .. code-block::
 
-	./tools/testing/kunit/kunit.py run 'kunit-resource*'
+	./tools/testing/kunit/kunit.py run 'kunit*.*remove_resource'
 
 This uses the standard glob format with wildcard characters.
 
-- 
2.44.0.478.gd926399ef9-goog

Re: [PATCH v2] Documentation: kunit: Clarify test filter format

[Daniel Latypov]

On Tue, Apr 2, 2024 at 5:51 AM Brendan Jackman <jackmanb@google.com> wrote:
>
> It seems obvious once you know, but at first I didn't realise that the
> suite name is part of this format. Document it and add some examples.
>
> Signed-off-by: Brendan Jackman <jackmanb@google.com>

Reviewed-by: Daniel Latypov <dlatypov@google.com>

Thanks!

I agree with your comment on v1, I think the extra verbosity is fine.
It's still easy to read and this should hopefully eliminate the
ambiguity for most readers.

> ---
> v1->v2: Expanded to clarify that suite_glob and test_glob are two separate
>         patterns. Also made some other trivial changes to formatting etc.

<snip>

Re: [PATCH v2] Documentation: kunit: Clarify test filter format

[Brendan Jackman]

On Wed, Apr 03, 2024 at 02:59:43PM -0700, Daniel Latypov wrote:
> Reviewed-by: Daniel Latypov <dlatypov@google.com>

Hi Jonathan, I think this is ready to be applied?

Thanks,
Brendan

Re: [PATCH v2] Documentation: kunit: Clarify test filter format

[Jonathan Corbet]

Brendan Jackman <jackmanb@google.com> writes:

> On Wed, Apr 03, 2024 at 02:59:43PM -0700, Daniel Latypov wrote:
>> Reviewed-by: Daniel Latypov <dlatypov@google.com>
>
> Hi Jonathan, I think this is ready to be applied?

I'm happy to take this, but normally these patches go through the kunit
tree, so I've not been paying much attention.  Let me know please if I
should pick it up.

Thanks,

jon