1 /* SPDX-License-Identifier: GPL-2.0 */
13 #include <kunit/try-catch.h>
48  * sub-subtest.  See the "Subtests" section in
49  * https://node-tap.org/tap-protocol/
56  * enum kunit_status - Type of result for a test or test suite
90  * struct kunit_case - represents an individual test case.
110  * .. code-block:: c
116  *		KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
118  *		KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
152  * KUNIT_CASE - A helper for creating a &struct kunit_case
165  * KUNIT_CASE_ATTR - A helper for creating a &struct kunit_case
177  * KUNIT_CASE_SLOW - A helper for creating a &struct kunit_case
188  * KUNIT_CASE_PARAM - A helper for creation a parameterized &struct kunit_case
209  * KUNIT_CASE_PARAM_ATTR - A helper for creating a parameterized &struct
223  * struct kunit_suite - describes a related collection of &struct kunit_case
267  * struct kunit - represents a running instance of a test.
309 	WRITE_ONCE(test->status, KUNIT_FAILURE);  in kunit_set_failure()
357  * kunit_test_suites() - used to register one or more &struct kunit_suite
377  * kunit_test_init_section_suites() - used to register one or more &struct
404 	for (test_case = suite->test_cases; test_case->run_case; test_case++)
409  * kunit_kmalloc_array() - Like kmalloc_array() except the allocation is *test managed*.
425  * kunit_kmalloc() - Like kmalloc() except the allocation is *test managed*.
441  * kunit_kfree() - Like kfree except for allocations managed by KUnit.
448  * kunit_kzalloc() - Just like kunit_kmalloc(), but zeroes the allocation.
461  * kunit_kcalloc() - Just like kunit_kmalloc_array(), but zeroes the allocation.
479  * kunit_mark_skipped() - Marks @test_or_suite as skipped
491 		WRITE_ONCE((test_or_suite)->status, KUNIT_SKIPPED);	\
492 		scnprintf((test_or_suite)->status_comment,		\
498  * kunit_skip() - Marks @test_or_suite as skipped
511 		kunit_try_catch_throw(&((test_or_suite)->try_catch));	\
515  * printk and log to per-test or per-suite log buffer.  Logging only done
521 		kunit_log_append((test_or_suite)->log,	fmt,		\
527 		  (test)->name,	##__VA_ARGS__)
530  * kunit_info() - Prints an INFO level message associated with @test.
542  * kunit_warn() - Prints a WARN level message associated with @test.
553  * kunit_err() - Prints an ERROR level message associated with @test.
564  * KUNIT_SUCCEED() - A no-op expectation. Only exists for code clarity.
607  * KUNIT_FAIL() - Always causes a test to fail when evaluated.
680 				    left,				       \  argument
686 	const typeof(left) __left = (left);				       \
690 		.left_text = #left,					       \
710 				   left,				       \  argument
719 				    left, op, right,			       \
725 				   left,				       \  argument
734 				    left, op, right,			       \
740 				   left,				       \  argument
746 	const char *__left = (left);					       \
750 		.left_text = #left,					       \
771 			    left,					       \  argument
778 	const void *__left = (left);					       \
783 		.left_text = #left,					       \
824  * KUNIT_EXPECT_TRUE() - Causes a test failure when the expression is not true.
845  * KUNIT_EXPECT_FALSE() - Makes a test failure when the expression is not false.
864  * KUNIT_EXPECT_EQ() - Sets an expectation that @left and @right are equal.
866  * @left: an arbitrary expression that evaluates to a primitive C type.
869  * Sets an expectation that the values that @left and @right evaluate to are
871  * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for
874 #define KUNIT_EXPECT_EQ(test, left, right) \  argument
875 	KUNIT_EXPECT_EQ_MSG(test, left, right, NULL)
877 #define KUNIT_EXPECT_EQ_MSG(test, left, right, fmt, ...)		       \  argument
880 				   left, ==, right,			       \
885  * KUNIT_EXPECT_PTR_EQ() - Expects that pointers @left and @right are equal.
887  * @left: an arbitrary expression that evaluates to a pointer.
890  * Sets an expectation that the values that @left and @right evaluate to are
892  * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for
895 #define KUNIT_EXPECT_PTR_EQ(test, left, right)				       \  argument
896 	KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, NULL)
898 #define KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, fmt, ...)		       \  argument
901 				   left, ==, right,			       \
906  * KUNIT_EXPECT_NE() - An expectation that @left and @right are not equal.
908  * @left: an arbitrary expression that evaluates to a primitive C type.
911  * Sets an expectation that the values that @left and @right evaluate to are not
913  * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for
916 #define KUNIT_EXPECT_NE(test, left, right) \  argument
917 	KUNIT_EXPECT_NE_MSG(test, left, right, NULL)
919 #define KUNIT_EXPECT_NE_MSG(test, left, right, fmt, ...)		       \  argument
922 				   left, !=, right,			       \
927  * KUNIT_EXPECT_PTR_NE() - Expects that pointers @left and @right are not equal.
929  * @left: an arbitrary expression that evaluates to a pointer.
932  * Sets an expectation that the values that @left and @right evaluate to are not
934  * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for
937 #define KUNIT_EXPECT_PTR_NE(test, left, right)				       \  argument
938 	KUNIT_EXPECT_PTR_NE_MSG(test, left, right, NULL)
940 #define KUNIT_EXPECT_PTR_NE_MSG(test, left, right, fmt, ...)		       \  argument
943 				   left, !=, right,			       \
948  * KUNIT_EXPECT_LT() - An expectation that @left is less than @right.
950  * @left: an arbitrary expression that evaluates to a primitive C type.
953  * Sets an expectation that the value that @left evaluates to is less than the
955  * KUNIT_EXPECT_TRUE(@test, (@left) < (@right)). See KUNIT_EXPECT_TRUE() for
958 #define KUNIT_EXPECT_LT(test, left, right) \  argument
959 	KUNIT_EXPECT_LT_MSG(test, left, right, NULL)
961 #define KUNIT_EXPECT_LT_MSG(test, left, right, fmt, ...)		       \  argument
964 				   left, <, right,			       \
969  * KUNIT_EXPECT_LE() - Expects that @left is less than or equal to @right.
971  * @left: an arbitrary expression that evaluates to a primitive C type.
974  * Sets an expectation that the value that @left evaluates to is less than or
976  * to KUNIT_EXPECT_TRUE(@test, (@left) <= (@right)). See KUNIT_EXPECT_TRUE() for
979 #define KUNIT_EXPECT_LE(test, left, right) \  argument
980 	KUNIT_EXPECT_LE_MSG(test, left, right, NULL)
982 #define KUNIT_EXPECT_LE_MSG(test, left, right, fmt, ...)		       \  argument
985 				   left, <=, right,			       \
990  * KUNIT_EXPECT_GT() - An expectation that @left is greater than @right.
992  * @left: an arbitrary expression that evaluates to a primitive C type.
995  * Sets an expectation that the value that @left evaluates to is greater than
997  * KUNIT_EXPECT_TRUE(@test, (@left) > (@right)). See KUNIT_EXPECT_TRUE() for
1000 #define KUNIT_EXPECT_GT(test, left, right) \  argument
1001 	KUNIT_EXPECT_GT_MSG(test, left, right, NULL)
1003 #define KUNIT_EXPECT_GT_MSG(test, left, right, fmt, ...)		       \  argument
1006 				   left, >, right,			       \
1011  * KUNIT_EXPECT_GE() - Expects that @left is greater than or equal to @right.
1013  * @left: an arbitrary expression that evaluates to a primitive C type.
1016  * Sets an expectation that the value that @left evaluates to is greater than
1018  * KUNIT_EXPECT_TRUE(@test, (@left) >= (@right)). See KUNIT_EXPECT_TRUE() for
1021 #define KUNIT_EXPECT_GE(test, left, right) \  argument
1022 	KUNIT_EXPECT_GE_MSG(test, left, right, NULL)
1024 #define KUNIT_EXPECT_GE_MSG(test, left, right, fmt, ...)		       \  argument
1027 				   left, >=, right,			       \
1032  * KUNIT_EXPECT_STREQ() - Expects that strings @left and @right are equal.
1034  * @left: an arbitrary expression that evaluates to a null terminated string.
1037  * Sets an expectation that the values that @left and @right evaluate to are
1039  * KUNIT_EXPECT_TRUE(@test, !strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE()
1042 #define KUNIT_EXPECT_STREQ(test, left, right) \  argument
1043 	KUNIT_EXPECT_STREQ_MSG(test, left, right, NULL)
1045 #define KUNIT_EXPECT_STREQ_MSG(test, left, right, fmt, ...)		       \  argument
1048 				   left, ==, right,			       \
1053  * KUNIT_EXPECT_STRNEQ() - Expects that strings @left and @right are not equal.
1055  * @left: an arbitrary expression that evaluates to a null terminated string.
1058  * Sets an expectation that the values that @left and @right evaluate to are
1060  * KUNIT_EXPECT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE()
1063 #define KUNIT_EXPECT_STRNEQ(test, left, right) \  argument
1064 	KUNIT_EXPECT_STRNEQ_MSG(test, left, right, NULL)
1066 #define KUNIT_EXPECT_STRNEQ_MSG(test, left, right, fmt, ...)		       \  argument
1069 				   left, !=, right,			       \
1074  * KUNIT_EXPECT_MEMEQ() - Expects that the first @size bytes of @left and @right are equal.
1076  * @left: An arbitrary expression that evaluates to the specified size.
1080  * Sets an expectation that the values that @left and @right evaluate to are
1082  * KUNIT_EXPECT_TRUE(@test, !memcmp((@left), (@right), (@size))). See
1089 #define KUNIT_EXPECT_MEMEQ(test, left, right, size) \  argument
1090 	KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, NULL)
1092 #define KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, fmt, ...)	       \  argument
1095 			    left, ==, right,				       \
1101  * KUNIT_EXPECT_MEMNEQ() - Expects that the first @size bytes of @left and @right are not equal.
1103  * @left: An arbitrary expression that evaluates to the specified size.
1107  * Sets an expectation that the values that @left and @right evaluate to are
1109  * KUNIT_EXPECT_TRUE(@test, memcmp((@left), (@right), (@size))). See
1116 #define KUNIT_EXPECT_MEMNEQ(test, left, right, size) \  argument
1117 	KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, NULL)
1119 #define KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, fmt, ...)	       \  argument
1122 			    left, !=, right,				       \
1128  * KUNIT_EXPECT_NULL() - Expects that @ptr is null.
1149  * KUNIT_EXPECT_NOT_NULL() - Expects that @ptr is not null.
1170  * KUNIT_EXPECT_NOT_ERR_OR_NULL() - Expects that @ptr is not null and not err.
1193  * KUNIT_ASSERT_TRUE() - Sets an assertion that @condition is true.
1214  * KUNIT_ASSERT_FALSE() - Sets an assertion that @condition is false.
1233  * KUNIT_ASSERT_EQ() - Sets an assertion that @left and @right are equal.
1235  * @left: an arbitrary expression that evaluates to a primitive C type.
1238  * Sets an assertion that the values that @left and @right evaluate to are
1242 #define KUNIT_ASSERT_EQ(test, left, right) \  argument
1243 	KUNIT_ASSERT_EQ_MSG(test, left, right, NULL)
1245 #define KUNIT_ASSERT_EQ_MSG(test, left, right, fmt, ...)		       \  argument
1248 				   left, ==, right,			       \
1253  * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal.
1255  * @left: an arbitrary expression that evaluates to a pointer.
1258  * Sets an assertion that the values that @left and @right evaluate to are
1262 #define KUNIT_ASSERT_PTR_EQ(test, left, right) \  argument
1263 	KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, NULL)
1265 #define KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, fmt, ...)		       \  argument
1268 				   left, ==, right,			       \
1273  * KUNIT_ASSERT_NE() - An assertion that @left and @right are not equal.
1275  * @left: an arbitrary expression that evaluates to a primitive C type.
1278  * Sets an assertion that the values that @left and @right evaluate to are not
1282 #define KUNIT_ASSERT_NE(test, left, right) \  argument
1283 	KUNIT_ASSERT_NE_MSG(test, left, right, NULL)
1285 #define KUNIT_ASSERT_NE_MSG(test, left, right, fmt, ...)		       \  argument
1288 				   left, !=, right,			       \
1293  * KUNIT_ASSERT_PTR_NE() - Asserts that pointers @left and @right are not equal.
1294  * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal.
1296  * @left: an arbitrary expression that evaluates to a pointer.
1299  * Sets an assertion that the values that @left and @right evaluate to are not
1303 #define KUNIT_ASSERT_PTR_NE(test, left, right) \  argument
1304 	KUNIT_ASSERT_PTR_NE_MSG(test, left, right, NULL)
1306 #define KUNIT_ASSERT_PTR_NE_MSG(test, left, right, fmt, ...)		       \  argument
1309 				   left, !=, right,			       \
1313  * KUNIT_ASSERT_LT() - An assertion that @left is less than @right.
1315  * @left: an arbitrary expression that evaluates to a primitive C type.
1318  * Sets an assertion that the value that @left evaluates to is less than the
1323 #define KUNIT_ASSERT_LT(test, left, right) \  argument
1324 	KUNIT_ASSERT_LT_MSG(test, left, right, NULL)
1326 #define KUNIT_ASSERT_LT_MSG(test, left, right, fmt, ...)		       \  argument
1329 				   left, <, right,			       \
1333  * KUNIT_ASSERT_LE() - An assertion that @left is less than or equal to @right.
1335  * @left: an arbitrary expression that evaluates to a primitive C type.
1338  * Sets an assertion that the value that @left evaluates to is less than or
1343 #define KUNIT_ASSERT_LE(test, left, right) \  argument
1344 	KUNIT_ASSERT_LE_MSG(test, left, right, NULL)
1346 #define KUNIT_ASSERT_LE_MSG(test, left, right, fmt, ...)		       \  argument
1349 				   left, <=, right,			       \
1354  * KUNIT_ASSERT_GT() - An assertion that @left is greater than @right.
1356  * @left: an arbitrary expression that evaluates to a primitive C type.
1359  * Sets an assertion that the value that @left evaluates to is greater than the
1364 #define KUNIT_ASSERT_GT(test, left, right) \  argument
1365 	KUNIT_ASSERT_GT_MSG(test, left, right, NULL)
1367 #define KUNIT_ASSERT_GT_MSG(test, left, right, fmt, ...)		       \  argument
1370 				   left, >, right,			       \
1375  * KUNIT_ASSERT_GE() - Assertion that @left is greater than or equal to @right.
1377  * @left: an arbitrary expression that evaluates to a primitive C type.
1380  * Sets an assertion that the value that @left evaluates to is greater than the
1385 #define KUNIT_ASSERT_GE(test, left, right) \  argument
1386 	KUNIT_ASSERT_GE_MSG(test, left, right, NULL)
1388 #define KUNIT_ASSERT_GE_MSG(test, left, right, fmt, ...)		       \  argument
1391 				   left, >=, right,			       \
1396  * KUNIT_ASSERT_STREQ() - An assertion that strings @left and @right are equal.
1398  * @left: an arbitrary expression that evaluates to a null terminated string.
1401  * Sets an assertion that the values that @left and @right evaluate to are
1405 #define KUNIT_ASSERT_STREQ(test, left, right) \  argument
1406 	KUNIT_ASSERT_STREQ_MSG(test, left, right, NULL)
1408 #define KUNIT_ASSERT_STREQ_MSG(test, left, right, fmt, ...)		       \  argument
1411 				   left, ==, right,			       \
1416  * KUNIT_ASSERT_STRNEQ() - Expects that strings @left and @right are not equal.
1418  * @left: an arbitrary expression that evaluates to a null terminated string.
1421  * Sets an expectation that the values that @left and @right evaluate to are
1423  * KUNIT_ASSERT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_ASSERT_TRUE()
1426 #define KUNIT_ASSERT_STRNEQ(test, left, right) \  argument
1427 	KUNIT_ASSERT_STRNEQ_MSG(test, left, right, NULL)
1429 #define KUNIT_ASSERT_STRNEQ_MSG(test, left, right, fmt, ...)		       \  argument
1432 				   left, !=, right,			       \
1437  * KUNIT_ASSERT_NULL() - Asserts that pointers @ptr is null.
1458  * KUNIT_ASSERT_NOT_NULL() - Asserts that pointers @ptr is not null.
1479  * KUNIT_ASSERT_NOT_ERR_OR_NULL() - Assertion that @ptr is not null and not err.
1499  * KUNIT_ARRAY_PARAM() - Define test parameter generator from an array.
1510 		if (__next - (array) < ARRAY_SIZE((array))) {					\