include/kunit/test.h

1 /* SPDX-License-Identifier: GPL-2.0 */
13 #include <kunit/try-catch.h>
38 /* Maximum size of parameter description string. */
46  * sub-subtest.  See the "Subtests" section in
47  * https://node-tap.org/tap-protocol/
54  * enum kunit_status - Type of result for a test or test suite
88  * struct kunit_case - represents an individual test case.
108  * .. code-block:: c
114  *		KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
116  *		KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
150  * KUNIT_CASE - A helper for creating a &struct kunit_case
163  * KUNIT_CASE_ATTR - A helper for creating a &struct kunit_case
175  * KUNIT_CASE_SLOW - A helper for creating a &struct kunit_case
186  * KUNIT_CASE_PARAM - A helper for creation a parameterized &struct kunit_case
189  * @gen_params: a reference to a parameter generator function.
200  * describing the parameter.
207  * KUNIT_CASE_PARAM_ATTR - A helper for creating a parameterized &struct
211  * @gen_params: a reference to a parameter generator function.
221  * struct kunit_suite - describes a related collection of &struct kunit_case
266  * struct kunit - represents a running instance of a test.
283 	/* param_value is the current parameter value for a test case. */
285 	/* param_index stores the index of the parameter in parameterized tests. */
308 	WRITE_ONCE(test->status, KUNIT_FAILURE);  in kunit_set_failure()
359  * kunit_test_suites() - used to register one or more &struct kunit_suite
384  * kunit_test_init_section_suites() - used to register one or more &struct
411 	for (test_case = suite->test_cases; test_case->run_case; test_case++)
416  * kunit_kmalloc_array() - Like kmalloc_array() except the allocation is *test managed*.
432  * kunit_kmalloc() - Like kmalloc() except the allocation is *test managed*.
448  * kunit_kfree() - Like kfree except for allocations managed by KUnit.
455  * kunit_kzalloc() - Just like kunit_kmalloc(), but zeroes the allocation.
468  * kunit_kcalloc() - Just like kunit_kmalloc_array(), but zeroes the allocation.
486  * kunit_mark_skipped() - Marks @test_or_suite as skipped
498 		WRITE_ONCE((test_or_suite)->status, KUNIT_SKIPPED);	\
499 		scnprintf((test_or_suite)->status_comment,		\
505  * kunit_skip() - Marks @test_or_suite as skipped
518 		kunit_try_catch_throw(&((test_or_suite)->try_catch));	\
522  * printk and log to per-test or per-suite log buffer.  Logging only done
528 		kunit_log_append((test_or_suite)->log,	fmt,		\
534 		  (test)->name,	##__VA_ARGS__)
537  * kunit_info() - Prints an INFO level message associated with @test.
549  * kunit_warn() - Prints a WARN level message associated with @test.
560  * kunit_err() - Prints an ERROR level message associated with @test.
571  * KUNIT_SUCCEED() - A no-op expectation. Only exists for code clarity.
614  * KUNIT_FAIL() - Always causes a test to fail when evaluated.
831  * KUNIT_EXPECT_TRUE() - Causes a test failure when the expression is not true.
852  * KUNIT_EXPECT_FALSE() - Makes a test failure when the expression is not false.
871  * KUNIT_EXPECT_EQ() - Sets an expectation that @left and @right are equal.
892  * KUNIT_EXPECT_PTR_EQ() - Expects that pointers @left and @right are equal.
913  * KUNIT_EXPECT_NE() - An expectation that @left and @right are not equal.
934  * KUNIT_EXPECT_PTR_NE() - Expects that pointers @left and @right are not equal.
955  * KUNIT_EXPECT_LT() - An expectation that @left is less than @right.
960  * Sets an expectation that the value that @left evaluates to is less than the
976  * KUNIT_EXPECT_LE() - Expects that @left is less than or equal to @right.
981  * Sets an expectation that the value that @left evaluates to is less than or
997  * KUNIT_EXPECT_GT() - An expectation that @left is greater than @right.
1018  * KUNIT_EXPECT_GE() - Expects that @left is greater than or equal to @right.
1039  * KUNIT_EXPECT_STREQ() - Expects that strings @left and @right are equal.
1060  * KUNIT_EXPECT_STRNEQ() - Expects that strings @left and @right are not equal.
1081  * KUNIT_EXPECT_MEMEQ() - Expects that the first @size bytes of @left and @right are equal.
1108  * KUNIT_EXPECT_MEMNEQ() - Expects that the first @size bytes of @left and @right are not equal.
1135  * KUNIT_EXPECT_NULL() - Expects that @ptr is null.
1156  * KUNIT_EXPECT_NOT_NULL() - Expects that @ptr is not null.
1177  * KUNIT_EXPECT_NOT_ERR_OR_NULL() - Expects that @ptr is not null and not err.
1200  * KUNIT_ASSERT_TRUE() - Sets an assertion that @condition is true.
1221  * KUNIT_ASSERT_FALSE() - Sets an assertion that @condition is false.
1240  * KUNIT_ASSERT_EQ() - Sets an assertion that @left and @right are equal.
1260  * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal.
1280  * KUNIT_ASSERT_NE() - An assertion that @left and @right are not equal.
1300  * KUNIT_ASSERT_PTR_NE() - Asserts that pointers @left and @right are not equal.
1301  * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal.
1320  * KUNIT_ASSERT_LT() - An assertion that @left is less than @right.
1325  * Sets an assertion that the value that @left evaluates to is less than the
1340  * KUNIT_ASSERT_LE() - An assertion that @left is less than or equal to @right.
1345  * Sets an assertion that the value that @left evaluates to is less than or
1361  * KUNIT_ASSERT_GT() - An assertion that @left is greater than @right.
1382  * KUNIT_ASSERT_GE() - Assertion that @left is greater than or equal to @right.
1403  * KUNIT_ASSERT_STREQ() - An assertion that strings @left and @right are equal.
1423  * KUNIT_ASSERT_STRNEQ() - Expects that strings @left and @right are not equal.
1444  * KUNIT_ASSERT_NULL() - Asserts that pointers @ptr is null.
1465  * KUNIT_ASSERT_NOT_NULL() - Asserts that pointers @ptr is not null.
1486  * KUNIT_ASSERT_NOT_ERR_OR_NULL() - Assertion that @ptr is not null and not err.
1506  * KUNIT_ARRAY_PARAM() - Define test parameter generator from an array.
1507  * @name:  prefix for the test parameter generator function.
1517 		if (__next - (array) < ARRAY_SIZE((array))) {					\
1527  * KUNIT_ARRAY_PARAM_DESC() - Define test parameter generator from an array.
1528  * @name:  prefix for the test parameter generator function.
1538 		if (__next - (array) < ARRAY_SIZE((array))) {					\
1539 			strscpy(desc, __next->desc_member, KUNIT_PARAM_DESC_SIZE);		\