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 v2:
Link to v1 of this patch series: https://lore.kernel.org/all/20250729193647.3410634-1-marievic@google.com/
- 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 | 2 +- include/kunit/test.h | 95 ++++++- kernel/kcsan/kcsan_test.c | 2 +- lib/kunit/kunit-example-test.c | 222 +++++++++++++++ lib/kunit/test.c | 87 ++++-- rust/kernel/kunit.rs | 4 + 7 files changed, 726 insertions(+), 28 deletions(-)