Skip to content

kunit: Refactor and extend KUnit's parameterized testing framework

David Gow dri-devel intel-xe linux-kselftest lkml 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v4 Latest7 patches 2 repliesIn review

Patches in v4 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/7kunit: Add parent kunit for parameterized test contextinclude/kunit/test.h lib/kunit/test.c+26 -160 replies
2/7kunit: Introduce param_init/exit for parameterized test context managementinclude/kunit/test.h lib/kunit/test.c rust/kernel/kunit.rs+55 -10 replies
3/7kunit: Pass parameterized test context to generate_params()drivers/gpu/drm/xe/tests/xe_pci.c drivers/gpu/drm/xe/tests/xe_pci_test.h include/kunit/test.h +2 more+22 -171 reply
4/7kunit: Enable direct registration of parameter arrays to a KUnit testinclude/kunit/test.h lib/kunit/test.c+91 -60 replies
5/7kunit: Add example parameterized test with shared resource management using the Resource APIlib/kunit/kunit-example-test.c+113 -00 replies
6/7kunit: Add example parameterized test with direct dynamic parameter array setuplib/kunit/kunit-example-test.c+104 -00 replies
7/7Documentation: kunit: Document new parameterized test featuresDocumentation/dev-tools/kunit/usage.rst+337 -50 replies

Reviews trailers per patch

All 7 patches have a Reviewed-by or Acked-by of their own; the series has one for all of them.

PatchDavid GowRae MoarMarco ElverRodrigo ViviMark RutlandLucas De Marchi
SeriesA-b
1/7R-b R-b
2/7R-b R-b
3/7R-b R-b A-b A-b A-b
4/7R-b R-b
5/7R-b R-b
6/7R-b R-b
7/7R-b R-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes. Scroll the table sideways for all 6 reviewers.

Read the v4 thread

Cover letter [PATCH v4 0/7] kunit: Refactor and extend KUnit's parameterized testing framework

Hi all,

This is a new version of Marie's patch series, with a couple of extra fixes squashed in, notably:
- drm/xe/tests: Fix some additional gen_params signatures
https://lore.kernel.org/linux-kselftest/[email protected]/
- kunit: Only output a test plan if we're using kunit_array_gen_params
https://lore.kernel.org/linux-kselftest/[email protected]/

These should fix the issues found in linux-next here:
https://lore.kernel.org/linux-next/[email protected]/

These changes only affect patches 3 and 4 of the series, the others are unchanged from v3.

Thanks, everyone, and sorry for the inconvenience!

Cheers,
-- David

---

Hello!

KUnit offers a parameterized testing framework, where tests can be run multiple times with different inputs. However, the current implementation uses the same struct kunit for each parameter run. After each run, the test context gets cleaned up, which creates the following limitations:

a. There is no way to store resources that are accessible across
the individual parameter runs.
b. It's not possible to pass additional context, besides the previous
parameter (and potentially anything else that is stored in the current test context), to the parameter generator function.
c. Test users are restricted to using pre-defined static arrays
of parameter objects or generate_params() to define their parameters. There is no flexibility to make a custom dynamic array without using generate_params(), which can be complex if generating the next parameter depends on more than just the single previous parameter.

This patch series resolves these limitations by:

1. [P 1] Giving each parameterized run its own struct kunit. It will remove the need to manage state, such as resetting the test->priv field or the test->status_comment after every parameter run.

2. [P 1] Introducing parameterized test context available to all parameter runs through the parent pointer of type struct kunit. This context won't be used to execute any test logic, but will instead be used for storing shared resources. Each parameter run context will have a reference to that parent instance and thus, have access to those resources.

3. [P 2] Introducing param_init() and param_exit() functions that can initialize and exit the parameterized test context. They will run once before and after the parameterized test. param_init() can be used to add resources to share between parameter runs, pass parameter arrays, and any other setup logic. While param_exit() can be used to clean up resources that were not managed by the parameterized test, and any other teardown logic.

4. [P 3] Passing the parameterized test context as an additional argument to generate_params(). This provides generate_params() with more context, making parameter generation much more flexible. The generate_params() implementations in the KCSAN and drm/xe tests have been adapted to match the new function pointer signature.

5. [P 4] Introducing a params_array field in struct kunit. This will allow the parameterized test context to have direct storage of the parameter array, enabling features like using dynamic parameter arrays or using context beyond just the previous parameter. This will also enable outputting the KTAP test plan for a parameterized test when the parameter count is available.

Patches 5 and 6 add examples tests to lib/kunit/kunit-example-test.c to showcase the new features and patch 7 updates the KUnit documentation to reflect all the framework changes.

Thank you!
-Marie

---

Changes in v4:

Link to v3 of this patch series:
https://lore.kernel.org/linux-kselftest/[email protected]/

- Fixup the signatures of some more gen_params functions in the drm/xe driver.
- Only print a KTAP test plan if a parameterised test is using the built-in kunit_array_gen_params generating function, fixing the issues with generator functions which skip array elements.

Changes in v3:

Link to v2 of this patch series:
https://lore.kernel.org/all/[email protected]/

- Added logic for skipping the parameter runs and updating the test statistics when parameterized test initialization fails.
- Minor changes to the documentation.
- Commit message formatting.

Changes in v2:

Link to v1 of this patch series:
https://lore.kernel.org/all/[email protected]/

- Establish parameterized testing terminology:
- "parameterized test" will refer to the group of all runs of a single test function with different parameters.
- "parameter run" will refer to the execution of the test case function with a single parameter.
- "parameterized test context" is the struct kunit that holds the context for the entire parameterized test.
- "parameter run context" is the struct kunit that holds the context of the individual parameter run.
- A test is defined to be a parameterized tests if it was registered with a generator function.
- Make comment edits to reflect the established terminology.
- Require users to manually pass kunit_array_gen_params() to KUNIT_CASE_PARAM_WITH_INIT() as the generator function, unless they want to provide their own generator function, if the parameter array was registered in param_init(). This is to be consistent with the definition of a parameterized test, i.e. generate_params() is never NULL if it's a parameterized test.
- Change name of kunit_get_next_param_and_desc() to kunit_array_gen_params().
- Other minor function name changes such as removing the "__" prefix in front of internal functions.
- Change signature of get_description() in struct params_array to accept the parameterized test context, as well.
- Output the KTAP test plan for a parameterized test when the parameter count is available.
- Cover letter was made more concise.
- Edits to the example tests.
- Fix bug of parameterized test init/exit logic being done outside of the parameterized test check.
- Fix bugs identified by the kernel test robot.

---

Marie Zhussupova (7):
kunit: Add parent kunit for parameterized test context
kunit: Introduce param_init/exit for parameterized test context
management
kunit: Pass parameterized test context to generate_params()
kunit: Enable direct registration of parameter arrays to a KUnit test
kunit: Add example parameterized test with shared resource management
using the Resource API
kunit: Add example parameterized test with direct dynamic parameter
array setup
Documentation: kunit: Document new parameterized test features

 Documentation/dev-tools/kunit/usage.rst | 342 +++++++++++++++++++++++-
 drivers/gpu/drm/xe/tests/xe_pci.c       |  14 +-
 drivers/gpu/drm/xe/tests/xe_pci_test.h  |   9 +-
 include/kunit/test.h                    |  95 ++++++-
 kernel/kcsan/kcsan_test.c               |   2 +-
 lib/kunit/kunit-example-test.c          | 217 +++++++++++++++
 lib/kunit/test.c                        |  94 +++++--
 rust/kernel/kunit.rs                    |   4 +
 8 files changed, 740 insertions(+), 37 deletions(-)
Signature · 1 line
2.51.0.261.g7ce5a0a67e-goog