diff options
Diffstat (limited to 'include/kunit/test.h')
| -rw-r--r-- | include/kunit/test.h | 231 |
1 files changed, 214 insertions, 17 deletions
diff --git a/include/kunit/test.h b/include/kunit/test.h index 58dbab60f853..e52452e58305 100644 --- a/include/kunit/test.h +++ b/include/kunit/test.h @@ -67,7 +67,7 @@ enum kunit_status { /* * Speed Attribute is stored as an enum and separated into categories of - * speed: very_slowm, slow, and normal. These speeds are relative to + * speed: very_slow, slow, and normal. These speeds are relative to * other KUnit tests. * * Note: unset speed attribute acts as default of KUNIT_SPEED_NORMAL. @@ -92,6 +92,8 @@ struct kunit_attributes { * @name: the name of the test case. * @generate_params: the generator function for parameterized tests. * @attr: the attributes associated with the test + * @param_init: The init function to run before a parameterized test. + * @param_exit: The exit function to run after a parameterized test. * * A test case is a function with the signature, * ``void (*)(struct kunit *)`` @@ -126,8 +128,11 @@ struct kunit_attributes { struct kunit_case { void (*run_case)(struct kunit *test); const char *name; - const void* (*generate_params)(const void *prev, char *desc); + const void* (*generate_params)(struct kunit *test, + const void *prev, char *desc); struct kunit_attributes attr; + int (*param_init)(struct kunit *test); + void (*param_exit)(struct kunit *test); /* private: internal use only. */ enum kunit_status status; @@ -219,6 +224,31 @@ static inline char *kunit_status_to_ok_not_ok(enum kunit_status status) .attr = attributes, .module_name = KBUILD_MODNAME} /** + * KUNIT_CASE_PARAM_WITH_INIT - Define a parameterized KUnit test case with custom + * param_init() and param_exit() functions. + * @test_name: The function implementing the test case. + * @gen_params: The function to generate parameters for the test case. + * @init: A reference to the param_init() function to run before a parameterized test. + * @exit: A reference to the param_exit() function to run after a parameterized test. + * + * Provides the option to register param_init() and param_exit() functions. + * param_init/exit will be passed the parameterized test context and run once + * before and once after the parameterized test. The init function can be used + * to add resources to share between parameter runs, pass parameter arrays, + * and any other setup logic. The exit function can be used to clean up resources + * that were not managed by the parameterized test, and any other teardown logic. + * + * Note: If you are registering a parameter array in param_init() with + * kunit_register_param_array() then you need to pass kunit_array_gen_params() + * to this as the generator function. + */ +#define KUNIT_CASE_PARAM_WITH_INIT(test_name, gen_params, init, exit) \ + { .run_case = test_name, .name = #test_name, \ + .generate_params = gen_params, \ + .param_init = init, .param_exit = exit, \ + .module_name = KBUILD_MODNAME} + +/** * struct kunit_suite - describes a related collection of &struct kunit_case * * @name: the name of the test. Purely informational. @@ -263,19 +293,39 @@ struct kunit_suite_set { struct kunit_suite * const *end; }; +/* Stores the pointer to the parameter array and its metadata. */ +struct kunit_params { + /* + * Reference to the parameter array for a parameterized test. This + * is NULL if a parameter array wasn't directly passed to the + * parameterized test context struct kunit via kunit_register_params_array(). + */ + const void *params; + /* Reference to a function that gets the description of a parameter. */ + void (*get_description)(struct kunit *test, const void *param, char *desc); + size_t num_params; + size_t elem_size; +}; + /** * struct kunit - represents a running instance of a test. * * @priv: for user to store arbitrary data. Commonly used to pass data * created in the init function (see &struct kunit_suite). + * @parent: reference to the parent context of type struct kunit that can + * be used for storing shared resources. + * @params_array: for storing the parameter array. * * Used to store information about the current context under which the test * is running. Most of this data is private and should only be accessed - * indirectly via public functions; the one exception is @priv which can be - * used by the test writer to store arbitrary data. + * indirectly via public functions; the exceptions are @priv, @parent and + * @params_array which can be used by the test writer to store arbitrary data, + * access the parent context, and to store the parameter array, respectively. */ struct kunit { void *priv; + struct kunit *parent; + struct kunit_params params_array; /* private: internal use only. */ const char *name; /* Read only after initialization! */ @@ -346,6 +396,8 @@ void kunit_exec_list_tests(struct kunit_suite_set *suite_set, bool include_attr) struct kunit_suite_set kunit_merge_suite_sets(struct kunit_suite_set init_suite_set, struct kunit_suite_set suite_set); +const void *kunit_array_gen_params(struct kunit *test, const void *prev, char *desc); + #if IS_BUILTIN(CONFIG_KUNIT) int kunit_run_all_tests(void); #else @@ -532,6 +584,18 @@ static inline char *kunit_kstrdup(struct kunit *test, const char *str, gfp_t gfp const char *kunit_kstrdup_const(struct kunit *test, const char *str, gfp_t gfp); /** + * kunit_attach_mm() - Create and attach a new mm if it doesn't already exist. + * + * Allocates a &struct mm_struct and attaches it to @current. In most cases, call + * kunit_vm_mmap() without calling kunit_attach_mm() directly. Only necessary when + * code under test accesses the mm before executing the mmap (e.g., to perform + * additional initialization beforehand). + * + * Return: 0 on success, -errno on failure. + */ +int kunit_attach_mm(void); + +/** * kunit_vm_mmap() - Allocate KUnit-tracked vm_mmap() area * @test: The test context object. * @file: struct file pointer to map from, if any @@ -549,13 +613,14 @@ unsigned long kunit_vm_mmap(struct kunit *test, struct file *file, unsigned long offset); void kunit_cleanup(struct kunit *test); +void kunit_free_boot_suites(void); void __printf(2, 3) kunit_log_append(struct string_stream *log, const char *fmt, ...); /** - * kunit_mark_skipped() - Marks @test_or_suite as skipped + * kunit_mark_skipped() - Marks @test as skipped * - * @test_or_suite: The test context object. + * @test: The test context object. * @fmt: A printk() style format string. * * Marks the test as skipped. @fmt is given output as the test status @@ -563,18 +628,18 @@ void __printf(2, 3) kunit_log_append(struct string_stream *log, const char *fmt, * * Test execution continues after kunit_mark_skipped() is called. */ -#define kunit_mark_skipped(test_or_suite, fmt, ...) \ +#define kunit_mark_skipped(test, fmt, ...) \ do { \ - WRITE_ONCE((test_or_suite)->status, KUNIT_SKIPPED); \ - scnprintf((test_or_suite)->status_comment, \ + WRITE_ONCE((test)->status, KUNIT_SKIPPED); \ + scnprintf((test)->status_comment, \ KUNIT_STATUS_COMMENT_SIZE, \ fmt, ##__VA_ARGS__); \ } while (0) /** - * kunit_skip() - Marks @test_or_suite as skipped + * kunit_skip() - Marks @test as skipped * - * @test_or_suite: The test context object. + * @test: The test context object. * @fmt: A printk() style format string. * * Skips the test. @fmt is given output as the test status @@ -582,10 +647,10 @@ void __printf(2, 3) kunit_log_append(struct string_stream *log, const char *fmt, * * Test execution is halted after kunit_skip() is called. */ -#define kunit_skip(test_or_suite, fmt, ...) \ +#define kunit_skip(test, fmt, ...) \ do { \ - kunit_mark_skipped((test_or_suite), fmt, ##__VA_ARGS__);\ - kunit_try_catch_throw(&((test_or_suite)->try_catch)); \ + kunit_mark_skipped((test), fmt, ##__VA_ARGS__); \ + kunit_try_catch_throw(&((test)->try_catch)); \ } while (0) /* @@ -842,7 +907,8 @@ do { \ }; \ \ _KUNIT_SAVE_LOC(test); \ - if (likely((__left) && (__right) && (strcmp(__left, __right) op 0))) \ + if (likely(!IS_ERR_OR_NULL(__left) && !IS_ERR_OR_NULL(__right) && \ + (strcmp(__left, __right) op 0))) \ break; \ \ \ @@ -1662,9 +1728,12 @@ do { \ * Define function @name_gen_params which uses @array to generate parameters. */ #define KUNIT_ARRAY_PARAM(name, array, get_desc) \ - static const void *name##_gen_params(const void *prev, char *desc) \ + static const void *name##_gen_params(struct kunit *test, \ + const void *prev, char *desc) \ { \ typeof((array)[0]) *__next = prev ? ((typeof(__next)) prev) + 1 : (array); \ + if (!prev) \ + kunit_register_params_array(test, array, ARRAY_SIZE(array), NULL); \ if (__next - (array) < ARRAY_SIZE((array))) { \ void (*__get_desc)(typeof(__next), char *) = get_desc; \ if (__get_desc) \ @@ -1683,9 +1752,12 @@ do { \ * Define function @name_gen_params which uses @array to generate parameters. */ #define KUNIT_ARRAY_PARAM_DESC(name, array, desc_member) \ - static const void *name##_gen_params(const void *prev, char *desc) \ + static const void *name##_gen_params(struct kunit *test, \ + const void *prev, char *desc) \ { \ typeof((array)[0]) *__next = prev ? ((typeof(__next)) prev) + 1 : (array); \ + if (!prev) \ + kunit_register_params_array(test, array, ARRAY_SIZE(array), NULL); \ if (__next - (array) < ARRAY_SIZE((array))) { \ strscpy(desc, __next->desc_member, KUNIT_PARAM_DESC_SIZE); \ return __next; \ @@ -1693,8 +1765,133 @@ do { \ return NULL; \ } +/** + * kunit_register_params_array() - Register parameter array for a KUnit test. + * @test: The KUnit test structure to which parameters will be added. + * @array: An array of test parameters. + * @param_count: Number of parameters. + * @get_desc: Function that generates a string description for a given parameter + * element. + * + * This macro initializes the @test's parameter array data, storing information + * including the parameter array, its count, the element size, and the parameter + * description function within `test->params_array`. + * + * Note: If using this macro in param_init(), kunit_array_gen_params() + * will then need to be manually provided as the parameter generator function to + * KUNIT_CASE_PARAM_WITH_INIT(). kunit_array_gen_params() is a KUnit + * function that uses the registered array to generate parameters + */ +#define kunit_register_params_array(test, array, param_count, get_desc) \ + do { \ + struct kunit *_test = (test); \ + const typeof((array)[0]) * _params_ptr = &(array)[0]; \ + _test->params_array.params = _params_ptr; \ + _test->params_array.num_params = (param_count); \ + _test->params_array.elem_size = sizeof(*_params_ptr); \ + _test->params_array.get_description = (get_desc); \ + } while (0) + // TODO(dlatypov@google.com): consider eventually migrating users to explicitly // include resource.h themselves if they need it. #include <kunit/resource.h> +/* + * Warning backtrace suppression API. + * + * Suppresses WARN*() backtraces on the current task while active. Two forms + * are provided: + * + * - Scoped: kunit_warning_suppress(test) { ... } + * Suppression is active for the duration of the block. On normal exit, + * the for-loop increment deactivates suppression. On early exit (break, + * return, goto), the __cleanup attribute fires. On kthread_exit() (e.g., + * a failed KUnit assertion), kunit_add_action() cleans up at test + * teardown. The suppression handle is only accessible inside the block, + * so warning counts must be checked before the block exits. + * + * - Direct: kunit_start_suppress_warning() / kunit_end_suppress_warning() + * The underlying functions, returning an explicit handle pointer. Use + * when the handle needs to be retained (e.g., for post-suppression + * count checks) or passed across helper functions. + */ +struct kunit_suppressed_warning; + +struct kunit_suppressed_warning * +kunit_start_suppress_warning(struct kunit *test); +void kunit_end_suppress_warning(struct kunit *test, + struct kunit_suppressed_warning *w); +int kunit_suppressed_warning_count(struct kunit_suppressed_warning *w); +void __kunit_suppress_auto_cleanup(struct kunit_suppressed_warning **wp); +bool kunit_has_active_suppress_warning(void); + +/** + * kunit_warning_suppress() - Suppress WARN*() backtraces for the duration + * of a block. + * @test: The test context object. + * + * Scoped form of the suppression API. Suppression starts when the block is + * entered and ends automatically when the block exits through any path. See + * the section comment above for the cleanup guarantees on each exit path. + * Fails the test if suppression is already active; nesting is not supported. + * + * The warning count can be checked inside the block via + * KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(). The handle is not accessible + * after the block exits. + * + * Example:: + * + * kunit_warning_suppress(test) { + * trigger_warning(); + * KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(test, 1); + * } + */ +#define kunit_warning_suppress(test) \ + for (struct kunit_suppressed_warning *__kunit_suppress \ + __cleanup(__kunit_suppress_auto_cleanup) = \ + kunit_start_suppress_warning(test); \ + __kunit_suppress; \ + kunit_end_suppress_warning(test, __kunit_suppress), \ + __kunit_suppress = NULL) + +/** + * KUNIT_SUPPRESSED_WARNING_COUNT() - Returns the suppressed warning count. + * + * Returns the number of WARN*() calls suppressed since the current + * suppression block started, or 0 if the handle is NULL. Usable inside a + * kunit_warning_suppress() block. + */ +#define KUNIT_SUPPRESSED_WARNING_COUNT() \ + kunit_suppressed_warning_count(__kunit_suppress) + +/** + * KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT() - Sets an expectation that the + * suppressed warning count equals + * @expected. + * @test: The test context object. + * @expected: an expression that evaluates to the expected warning count. + * + * Sets an expectation that the number of suppressed WARN*() calls equals + * @expected. This is semantically equivalent to + * KUNIT_EXPECT_EQ(@test, KUNIT_SUPPRESSED_WARNING_COUNT(), @expected). + * See KUNIT_EXPECT_EQ() for more information. + */ +#define KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(test, expected) \ + KUNIT_EXPECT_EQ(test, KUNIT_SUPPRESSED_WARNING_COUNT(), expected) + +/** + * KUNIT_ASSERT_SUPPRESSED_WARNING_COUNT() - Sets an assertion that the + * suppressed warning count equals + * @expected. + * @test: The test context object. + * @expected: an expression that evaluates to the expected warning count. + * + * Sets an assertion that the number of suppressed WARN*() calls equals + * @expected. This is the same as KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(), + * except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the + * assertion is not met. + */ +#define KUNIT_ASSERT_SUPPRESSED_WARNING_COUNT(test, expected) \ + KUNIT_ASSERT_EQ(test, KUNIT_SUPPRESSED_WARNING_COUNT(), expected) + #endif /* _KUNIT_TEST_H */ |