include/kunit/test.h

1 /* SPDX-License-Identifier: GPL-2.0 */
13 #include <kunit/try-catch.h>
39 /* Maximum size of parameter description string. */
47  * sub-subtest.  See the "Subtests" section in
48  * https://node-tap.org/tap-protocol/
55  * enum kunit_status - Type of result for a test or test suite
89  * struct kunit_case - represents an individual test case.
109  * .. code-block:: c
115  *		KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
117  *		KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
151  * KUNIT_CASE - A helper for creating a &struct kunit_case
164  * KUNIT_CASE_ATTR - A helper for creating a &struct kunit_case
176  * KUNIT_CASE_SLOW - A helper for creating a &struct kunit_case
187  * KUNIT_CASE_PARAM - A helper for creation a parameterized &struct kunit_case
190  * @gen_params: a reference to a parameter generator function.
201  * describing the parameter.
208  * KUNIT_CASE_PARAM_ATTR - A helper for creating a parameterized &struct
212  * @gen_params: a reference to a parameter generator function.
222  * struct kunit_suite - describes a related collection of &struct kunit_case
267  * struct kunit - represents a running instance of a test.
284 	/* param_value is the current parameter value for a test case. */
286 	/* param_index stores the index of the parameter in parameterized tests. */
311 	WRITE_ONCE(test->status, KUNIT_FAILURE);  in kunit_set_failure()
362  * kunit_test_suites() - used to register one or more &struct kunit_suite
387  * kunit_test_init_section_suites() - used to register one or more &struct
414 	for (test_case = suite->test_cases; test_case->run_case; test_case++)
419  * kunit_kmalloc_array() - Like kmalloc_array() except the allocation is *test managed*.
435  * kunit_kmalloc() - Like kmalloc() except the allocation is *test managed*.
451  * kunit_kfree() - Like kfree except for allocations managed by KUnit.
458  * kunit_kzalloc() - Just like kunit_kmalloc(), but zeroes the allocation.
471  * kunit_kcalloc() - Just like kunit_kmalloc_array(), but zeroes the allocation.
486  * kunit_kfree_const() - conditionally free test managed memory
496  * kunit_kstrdup() - Duplicates a string into a test managed allocation.
499  * @str: The NULL-terminated string to duplicate.
520  * kunit_kstrdup_const() - Conditionally duplicates a string into a test managed allocation.
523  * @str: The NULL-terminated string to duplicate.
527  * kunit_kfree_const() -- not kunit_kfree().
533  * kunit_vm_mmap() - Allocate KUnit-tracked vm_mmap() area
554  * kunit_mark_skipped() - Marks @test_or_suite as skipped
566 		WRITE_ONCE((test_or_suite)->status, KUNIT_SKIPPED);	\
567 		scnprintf((test_or_suite)->status_comment,		\
573  * kunit_skip() - Marks @test_or_suite as skipped
586 		kunit_try_catch_throw(&((test_or_suite)->try_catch));	\
590  * printk and log to per-test or per-suite log buffer.  Logging only done
596 		kunit_log_append((test_or_suite)->log,	fmt,		\
602 		  (test)->name,	##__VA_ARGS__)
605  * kunit_info() - Prints an INFO level message associated with @test.
617  * kunit_warn() - Prints a WARN level message associated with @test.
628  * kunit_err() - Prints an ERROR level message associated with @test.
643 	WRITE_ONCE(test->last_seen.file, __FILE__);			       \
644 	WRITE_ONCE(test->last_seen.line, __LINE__);			       \
648  * KUNIT_SUCCEED() - A no-op expectation. Only exists for code clarity.
693  * KUNIT_FAIL() - Always causes a test to fail when evaluated.
915  * KUNIT_EXPECT_TRUE() - Causes a test failure when the expression is not true.
936  * KUNIT_EXPECT_FALSE() - Makes a test failure when the expression is not false.
955  * KUNIT_EXPECT_EQ() - Sets an expectation that @left and @right are equal.
976  * KUNIT_EXPECT_PTR_EQ() - Expects that pointers @left and @right are equal.
997  * KUNIT_EXPECT_NE() - An expectation that @left and @right are not equal.
1018  * KUNIT_EXPECT_PTR_NE() - Expects that pointers @left and @right are not equal.
1039  * KUNIT_EXPECT_LT() - An expectation that @left is less than @right.
1044  * Sets an expectation that the value that @left evaluates to is less than the
1060  * KUNIT_EXPECT_LE() - Expects that @left is less than or equal to @right.
1065  * Sets an expectation that the value that @left evaluates to is less than or
1081  * KUNIT_EXPECT_GT() - An expectation that @left is greater than @right.
1102  * KUNIT_EXPECT_GE() - Expects that @left is greater than or equal to @right.
1123  * KUNIT_EXPECT_STREQ() - Expects that strings @left and @right are equal.
1144  * KUNIT_EXPECT_STRNEQ() - Expects that strings @left and @right are not equal.
1165  * KUNIT_EXPECT_MEMEQ() - Expects that the first @size bytes of @left and @right are equal.
1192  * KUNIT_EXPECT_MEMNEQ() - Expects that the first @size bytes of @left and @right are not equal.
1219  * KUNIT_EXPECT_NULL() - Expects that @ptr is null.
1240  * KUNIT_EXPECT_NOT_NULL() - Expects that @ptr is not null.
1261  * KUNIT_EXPECT_NOT_ERR_OR_NULL() - Expects that @ptr is not null and not err.
1281  * KUNIT_FAIL_AND_ABORT() - Always causes a test to fail and abort when evaluated.
1295  * KUNIT_ASSERT_TRUE() - Sets an assertion that @condition is true.
1316  * KUNIT_ASSERT_FALSE() - Sets an assertion that @condition is false.
1335  * KUNIT_ASSERT_EQ() - Sets an assertion that @left and @right are equal.
1355  * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal.
1375  * KUNIT_ASSERT_NE() - An assertion that @left and @right are not equal.
1395  * KUNIT_ASSERT_PTR_NE() - Asserts that pointers @left and @right are not equal.
1396  * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal.
1415  * KUNIT_ASSERT_LT() - An assertion that @left is less than @right.
1420  * Sets an assertion that the value that @left evaluates to is less than the
1435  * KUNIT_ASSERT_LE() - An assertion that @left is less than or equal to @right.
1440  * Sets an assertion that the value that @left evaluates to is less than or
1456  * KUNIT_ASSERT_GT() - An assertion that @left is greater than @right.
1477  * KUNIT_ASSERT_GE() - Assertion that @left is greater than or equal to @right.
1498  * KUNIT_ASSERT_STREQ() - An assertion that strings @left and @right are equal.
1518  * KUNIT_ASSERT_STRNEQ() - An assertion that strings @left and @right are not equal.
1539  * KUNIT_ASSERT_MEMEQ() - Asserts that the first @size bytes of @left and @right are equal.
1566  * KUNIT_ASSERT_MEMNEQ() - Asserts that the first @size bytes of @left and @right are not equal.
1593  * KUNIT_ASSERT_NULL() - Asserts that pointers @ptr is null.
1614  * KUNIT_ASSERT_NOT_NULL() - Asserts that pointers @ptr is not null.
1635  * KUNIT_ASSERT_NOT_ERR_OR_NULL() - Assertion that @ptr is not null and not err.
1655  * KUNIT_ARRAY_PARAM() - Define test parameter generator from an array.
1656  * @name:  prefix for the test parameter generator function.
1666 		if (__next - (array) < ARRAY_SIZE((array))) {					\
1676  * KUNIT_ARRAY_PARAM_DESC() - Define test parameter generator from an array.
1677  * @name:  prefix for the test parameter generator function.
1687 		if (__next - (array) < ARRAY_SIZE((array))) {					\
1688 			strscpy(desc, __next->desc_member, KUNIT_PARAM_DESC_SIZE);		\