3  * Base unit test (KUnit) API.
54  * enum kunit_status - Type of result for a test or test suite
55  * @KUNIT_SUCCESS: Denotes the test suite has not failed nor been skipped
56  * @KUNIT_FAILURE: Denotes the test has failed.
57  * @KUNIT_SKIPPED: Denotes the test has been skipped.
82 /* Holds attributes for each test case and suite */
88  * struct kunit_case - represents an individual test case.
90  * @run_case: the function representing the actual test case.
91  * @name:     the name of the test case.
93  * @attr:     the attributes associated with the test
95  * A test case is a function with the signature,
98  * KUNIT_ASSERT_TRUE()) about code under test. Each test case is associated
102  * A test case should be static and should only be created with the
103  * KUNIT_CASE() macro; additionally, every array of test cases should be
104  * terminated with an empty test case.
110  *	void add_test_basic(struct kunit *test)
112  *		KUNIT_EXPECT_EQ(test, 1, add(1, 0));
113  *		KUNIT_EXPECT_EQ(test, 2, add(1, 1));
114  *		KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
115  *		KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
116  *		KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
126 	void (*run_case)(struct kunit *test);
152  * @test_name: a reference to a test case function.
154  * Takes a symbol for a function representing a test case and creates a
166  * @test_name: a reference to a test case function.
168  * test attributes
178  * @test_name: a reference to a test case function.
188  * @test_name: a reference to a test case function.
210  * @test_name: a reference to a test case function.
213  * test attributes
223  * @name:	the name of the test. Purely informational.
224  * @suite_init:	called once per test suite before the test cases.
225  * @suite_exit:	called once per test suite after all test cases.
226  * @init:	called before every test case.
227  * @exit:	called after every test case.
228  * @test_cases:	a null terminated array of test cases.
229  * @attr:	the attributes associated with the test suite
232  * @init is called before every test case and @exit is called after every
233  * test case, similar to the notion of a *test fixture* or a *test class*
246 	int (*init)(struct kunit *test);
247 	void (*exit)(struct kunit *test);
266  * struct kunit - represents a running instance of a test.
271  * Used to store information about the current context under which the test
274  * used by the test writer to store arbitrary data.
283 	/* param_value is the current parameter value for a test case. */
289 	 * test case; thus, it is safe to update this across multiple
291 	 * be read after the test case finishes once all threads associated
292 	 * with the test case have terminated.
294 	spinlock_t lock; /* Guards all mutable test state. */
298 	 * new resources) from any thread associated with a test case, we must
306 static inline void kunit_set_failure(struct kunit *test)  in kunit_set_failure()  argument
308 	WRITE_ONCE(test->status, KUNIT_FAILURE);  in kunit_set_failure()
317 void kunit_init_test(struct kunit *test, const char *name, struct string_stream *log);
364  * Registers @suites with the test framework.
400  * Also, do not mark the suite or test case structs with __initdata because
416  * kunit_kmalloc_array() - Like kmalloc_array() except the allocation is *test managed*.
417  * @test: The test context object.
422  * Just like `kmalloc_array(...)`, except the allocation is managed by the test case
423  * and is automatically cleaned up after the test case concludes. See kunit_add_action()
429 void *kunit_kmalloc_array(struct kunit *test, size_t n, size_t size, gfp_t gfp);
432  * kunit_kmalloc() - Like kmalloc() except the allocation is *test managed*.
433  * @test: The test context object.
442 static inline void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp)  in kunit_kmalloc()  argument
444 	return kunit_kmalloc_array(test, 1, size, gfp);  in kunit_kmalloc()
449  * @test: The test case to which the resource belongs.
452 void kunit_kfree(struct kunit *test, const void *ptr);
456  * @test: The test context object.
462 static inline void *kunit_kzalloc(struct kunit *test, size_t size, gfp_t gfp)  in kunit_kzalloc()  argument
464 	return kunit_kmalloc(test, size, gfp | __GFP_ZERO);  in kunit_kzalloc()
469  * @test: The test context object.
476 static inline void *kunit_kcalloc(struct kunit *test, size_t n, size_t size, gfp_t gfp)  in kunit_kcalloc()  argument
478 	return kunit_kmalloc_array(test, n, size, gfp | __GFP_ZERO);  in kunit_kcalloc()
481 void kunit_cleanup(struct kunit *test);
488  * @test_or_suite: The test context object.
491  * Marks the test as skipped. @fmt is given output as the test status
492  * comment, typically the reason the test was skipped.
494  * Test execution continues after kunit_mark_skipped() is called.
507  * @test_or_suite: The test context object.
510  * Skips the test. @fmt is given output as the test status
511  * comment, typically the reason the test was skipped.
513  * Test execution is halted after kunit_skip() is called.
522  * printk and log to per-test or per-suite log buffer.  Logging only done
532 #define kunit_printk(lvl, test, fmt, ...)				\  argument
533 	kunit_log(lvl, test, KUNIT_SUBTEST_INDENT "# %s: " fmt,		\
534 		  (test)->name,	##__VA_ARGS__)
537  * kunit_info() - Prints an INFO level message associated with @test.
539  * @test: The test context object.
542  * Prints an info level message associated with the test suite being run.
545 #define kunit_info(test, fmt, ...) \  argument
546 	kunit_printk(KERN_INFO, test, fmt, ##__VA_ARGS__)
549  * kunit_warn() - Prints a WARN level message associated with @test.
551  * @test: The test context object.
556 #define kunit_warn(test, fmt, ...) \  argument
557 	kunit_printk(KERN_WARNING, test, fmt, ##__VA_ARGS__)
560  * kunit_err() - Prints an ERROR level message associated with @test.
562  * @test: The test context object.
567 #define kunit_err(test, fmt, ...) \  argument
568 	kunit_printk(KERN_ERR, test, fmt, ##__VA_ARGS__)
572  * @test: The test context object.
578 #define KUNIT_SUCCEED(test) do {} while (0)  argument
580 void __noreturn __kunit_abort(struct kunit *test);
582 void __kunit_do_failed_assertion(struct kunit *test,
589 #define _KUNIT_FAILED(test, assert_type, assert_class, assert_format, INITIALIZER, fmt, ...) do { \  argument
592 	__kunit_do_failed_assertion(test,				       \
600 		__kunit_abort(test);					       \
604 #define KUNIT_FAIL_ASSERTION(test, assert_type, fmt, ...)		       \  argument
605 	_KUNIT_FAILED(test,						       \
614  * KUNIT_FAIL() - Always causes a test to fail when evaluated.
615  * @test: The test context object.
621  * always causes the test case to fail when evaluated. See KUNIT_EXPECT_TRUE()
624 #define KUNIT_FAIL(test, fmt, ...)					       \  argument
625 	KUNIT_FAIL_ASSERTION(test,					       \
633 #define KUNIT_UNARY_ASSERTION(test,					       \  argument
643 	_KUNIT_FAILED(test,						       \
653 #define KUNIT_TRUE_MSG_ASSERTION(test, assert_type, condition, fmt, ...)       \  argument
654 	KUNIT_UNARY_ASSERTION(test,					       \
661 #define KUNIT_FALSE_MSG_ASSERTION(test, assert_type, condition, fmt, ...)      \  argument
662 	KUNIT_UNARY_ASSERTION(test,					       \
683 #define KUNIT_BASE_BINARY_ASSERTION(test,				       \  argument
704 	_KUNIT_FAILED(test,						       \
715 #define KUNIT_BINARY_INT_ASSERTION(test,				       \  argument
722 	KUNIT_BASE_BINARY_ASSERTION(test,				       \
730 #define KUNIT_BINARY_PTR_ASSERTION(test,				       \  argument
737 	KUNIT_BASE_BINARY_ASSERTION(test,				       \
745 #define KUNIT_BINARY_STR_ASSERTION(test,				       \  argument
765 	_KUNIT_FAILED(test,						       \
776 #define KUNIT_MEM_ASSERTION(test,					       \  argument
798 	_KUNIT_FAILED(test,						       \
810 #define KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test,			       \  argument
821 	_KUNIT_FAILED(test,						       \
831  * KUNIT_EXPECT_TRUE() - Causes a test failure when the expression is not true.
832  * @test: The test context object.
833  * @condition: an arbitrary boolean expression. The test fails when this does
836  * This and expectations of the form `KUNIT_EXPECT_*` will cause the test case
838  * the test case from continuing to run; this is otherwise known as an
841 #define KUNIT_EXPECT_TRUE(test, condition) \  argument
842 	KUNIT_EXPECT_TRUE_MSG(test, condition, NULL)
844 #define KUNIT_EXPECT_TRUE_MSG(test, condition, fmt, ...)		       \  argument
845 	KUNIT_TRUE_MSG_ASSERTION(test,					       \
852  * KUNIT_EXPECT_FALSE() - Makes a test failure when the expression is not false.
853  * @test: The test context object.
854  * @condition: an arbitrary boolean expression. The test fails when this does
860 #define KUNIT_EXPECT_FALSE(test, condition) \  argument
861 	KUNIT_EXPECT_FALSE_MSG(test, condition, NULL)
863 #define KUNIT_EXPECT_FALSE_MSG(test, condition, fmt, ...)		       \  argument
864 	KUNIT_FALSE_MSG_ASSERTION(test,					       \
872  * @test: The test context object.
878  * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for
881 #define KUNIT_EXPECT_EQ(test, left, right) \  argument
882 	KUNIT_EXPECT_EQ_MSG(test, left, right, NULL)
884 #define KUNIT_EXPECT_EQ_MSG(test, left, right, fmt, ...)		       \  argument
885 	KUNIT_BINARY_INT_ASSERTION(test,				       \
893  * @test: The test context object.
899  * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for
902 #define KUNIT_EXPECT_PTR_EQ(test, left, right)				       \  argument
903 	KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, NULL)
905 #define KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, fmt, ...)		       \  argument
906 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
914  * @test: The test context object.
920  * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for
923 #define KUNIT_EXPECT_NE(test, left, right) \  argument
924 	KUNIT_EXPECT_NE_MSG(test, left, right, NULL)
926 #define KUNIT_EXPECT_NE_MSG(test, left, right, fmt, ...)		       \  argument
927 	KUNIT_BINARY_INT_ASSERTION(test,				       \
935  * @test: The test context object.
941  * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for
944 #define KUNIT_EXPECT_PTR_NE(test, left, right)				       \  argument
945 	KUNIT_EXPECT_PTR_NE_MSG(test, left, right, NULL)
947 #define KUNIT_EXPECT_PTR_NE_MSG(test, left, right, fmt, ...)		       \  argument
948 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
956  * @test: The test context object.
962  * KUNIT_EXPECT_TRUE(@test, (@left) < (@right)). See KUNIT_EXPECT_TRUE() for
965 #define KUNIT_EXPECT_LT(test, left, right) \  argument
966 	KUNIT_EXPECT_LT_MSG(test, left, right, NULL)
968 #define KUNIT_EXPECT_LT_MSG(test, left, right, fmt, ...)		       \  argument
969 	KUNIT_BINARY_INT_ASSERTION(test,				       \
977  * @test: The test context object.
983  * to KUNIT_EXPECT_TRUE(@test, (@left) <= (@right)). See KUNIT_EXPECT_TRUE() for
986 #define KUNIT_EXPECT_LE(test, left, right) \  argument
987 	KUNIT_EXPECT_LE_MSG(test, left, right, NULL)
989 #define KUNIT_EXPECT_LE_MSG(test, left, right, fmt, ...)		       \  argument
990 	KUNIT_BINARY_INT_ASSERTION(test,				       \
998  * @test: The test context object.
1004  * KUNIT_EXPECT_TRUE(@test, (@left) > (@right)). See KUNIT_EXPECT_TRUE() for
1007 #define KUNIT_EXPECT_GT(test, left, right) \  argument
1008 	KUNIT_EXPECT_GT_MSG(test, left, right, NULL)
1010 #define KUNIT_EXPECT_GT_MSG(test, left, right, fmt, ...)		       \  argument
1011 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1019  * @test: The test context object.
1025  * KUNIT_EXPECT_TRUE(@test, (@left) >= (@right)). See KUNIT_EXPECT_TRUE() for
1028 #define KUNIT_EXPECT_GE(test, left, right) \  argument
1029 	KUNIT_EXPECT_GE_MSG(test, left, right, NULL)
1031 #define KUNIT_EXPECT_GE_MSG(test, left, right, fmt, ...)		       \  argument
1032 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1040  * @test: The test context object.
1046  * KUNIT_EXPECT_TRUE(@test, !strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE()
1049 #define KUNIT_EXPECT_STREQ(test, left, right) \  argument
1050 	KUNIT_EXPECT_STREQ_MSG(test, left, right, NULL)
1052 #define KUNIT_EXPECT_STREQ_MSG(test, left, right, fmt, ...)		       \  argument
1053 	KUNIT_BINARY_STR_ASSERTION(test,				       \
1061  * @test: The test context object.
1067  * KUNIT_EXPECT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE()
1070 #define KUNIT_EXPECT_STRNEQ(test, left, right) \  argument
1071 	KUNIT_EXPECT_STRNEQ_MSG(test, left, right, NULL)
1073 #define KUNIT_EXPECT_STRNEQ_MSG(test, left, right, fmt, ...)		       \  argument
1074 	KUNIT_BINARY_STR_ASSERTION(test,				       \
1082  * @test: The test context object.
1089  * KUNIT_EXPECT_TRUE(@test, !memcmp((@left), (@right), (@size))). See
1096 #define KUNIT_EXPECT_MEMEQ(test, left, right, size) \  argument
1097 	KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, NULL)
1099 #define KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, fmt, ...)	       \  argument
1100 	KUNIT_MEM_ASSERTION(test,					       \
1109  * @test: The test context object.
1116  * KUNIT_EXPECT_TRUE(@test, memcmp((@left), (@right), (@size))). See
1123 #define KUNIT_EXPECT_MEMNEQ(test, left, right, size) \  argument
1124 	KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, NULL)
1126 #define KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, fmt, ...)	       \  argument
1127 	KUNIT_MEM_ASSERTION(test,					       \
1136  * @test: The test context object.
1140  * semantically equivalent to KUNIT_EXPECT_PTR_EQ(@test, ptr, NULL).
1143 #define KUNIT_EXPECT_NULL(test, ptr)				               \  argument
1144 	KUNIT_EXPECT_NULL_MSG(test,					       \
1148 #define KUNIT_EXPECT_NULL_MSG(test, ptr, fmt, ...)	                       \  argument
1149 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
1157  * @test: The test context object.
1161  * is semantically equivalent to KUNIT_EXPECT_PTR_NE(@test, ptr, NULL).
1164 #define KUNIT_EXPECT_NOT_NULL(test, ptr)			               \  argument
1165 	KUNIT_EXPECT_NOT_NULL_MSG(test,					       \
1169 #define KUNIT_EXPECT_NOT_NULL_MSG(test, ptr, fmt, ...)	                       \  argument
1170 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
1178  * @test: The test context object.
1183  * KUNIT_EXPECT_TRUE(@test, !IS_ERR_OR_NULL(@ptr)). See KUNIT_EXPECT_TRUE() for
1186 #define KUNIT_EXPECT_NOT_ERR_OR_NULL(test, ptr) \  argument
1187 	KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL)
1189 #define KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...)		       \  argument
1190 	KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test,			       \
1196 #define KUNIT_ASSERT_FAILURE(test, fmt, ...) \  argument
1197 	KUNIT_FAIL_ASSERTION(test, KUNIT_ASSERTION, fmt, ##__VA_ARGS__)
1201  * @test: The test context object.
1202  * @condition: an arbitrary boolean expression. The test fails and aborts when
1205  * This and assertions of the form `KUNIT_ASSERT_*` will cause the test case to
1207  * an expectation failure, it will prevent the test case from continuing to run;
1210 #define KUNIT_ASSERT_TRUE(test, condition) \  argument
1211 	KUNIT_ASSERT_TRUE_MSG(test, condition, NULL)
1213 #define KUNIT_ASSERT_TRUE_MSG(test, condition, fmt, ...)		       \  argument
1214 	KUNIT_TRUE_MSG_ASSERTION(test,					       \
1222  * @test: The test context object.
1229 #define KUNIT_ASSERT_FALSE(test, condition) \  argument
1230 	KUNIT_ASSERT_FALSE_MSG(test, condition, NULL)
1232 #define KUNIT_ASSERT_FALSE_MSG(test, condition, fmt, ...)		       \  argument
1233 	KUNIT_FALSE_MSG_ASSERTION(test,					       \
1241  * @test: The test context object.
1249 #define KUNIT_ASSERT_EQ(test, left, right) \  argument
1250 	KUNIT_ASSERT_EQ_MSG(test, left, right, NULL)
1252 #define KUNIT_ASSERT_EQ_MSG(test, left, right, fmt, ...)		       \  argument
1253 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1261  * @test: The test context object.
1269 #define KUNIT_ASSERT_PTR_EQ(test, left, right) \  argument
1270 	KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, NULL)
1272 #define KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, fmt, ...)		       \  argument
1273 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
1281  * @test: The test context object.
1289 #define KUNIT_ASSERT_NE(test, left, right) \  argument
1290 	KUNIT_ASSERT_NE_MSG(test, left, right, NULL)
1292 #define KUNIT_ASSERT_NE_MSG(test, left, right, fmt, ...)		       \  argument
1293 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1302  * @test: The test context object.
1310 #define KUNIT_ASSERT_PTR_NE(test, left, right) \  argument
1311 	KUNIT_ASSERT_PTR_NE_MSG(test, left, right, NULL)
1313 #define KUNIT_ASSERT_PTR_NE_MSG(test, left, right, fmt, ...)		       \  argument
1314 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
1321  * @test: The test context object.
1330 #define KUNIT_ASSERT_LT(test, left, right) \  argument
1331 	KUNIT_ASSERT_LT_MSG(test, left, right, NULL)
1333 #define KUNIT_ASSERT_LT_MSG(test, left, right, fmt, ...)		       \  argument
1334 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1341  * @test: The test context object.
1350 #define KUNIT_ASSERT_LE(test, left, right) \  argument
1351 	KUNIT_ASSERT_LE_MSG(test, left, right, NULL)
1353 #define KUNIT_ASSERT_LE_MSG(test, left, right, fmt, ...)		       \  argument
1354 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1362  * @test: The test context object.
1371 #define KUNIT_ASSERT_GT(test, left, right) \  argument
1372 	KUNIT_ASSERT_GT_MSG(test, left, right, NULL)
1374 #define KUNIT_ASSERT_GT_MSG(test, left, right, fmt, ...)		       \  argument
1375 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1383  * @test: The test context object.
1392 #define KUNIT_ASSERT_GE(test, left, right) \  argument
1393 	KUNIT_ASSERT_GE_MSG(test, left, right, NULL)
1395 #define KUNIT_ASSERT_GE_MSG(test, left, right, fmt, ...)		       \  argument
1396 	KUNIT_BINARY_INT_ASSERTION(test,				       \
1404  * @test: The test context object.
1412 #define KUNIT_ASSERT_STREQ(test, left, right) \  argument
1413 	KUNIT_ASSERT_STREQ_MSG(test, left, right, NULL)
1415 #define KUNIT_ASSERT_STREQ_MSG(test, left, right, fmt, ...)		       \  argument
1416 	KUNIT_BINARY_STR_ASSERTION(test,				       \
1424  * @test: The test context object.
1430  * KUNIT_ASSERT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_ASSERT_TRUE()
1433 #define KUNIT_ASSERT_STRNEQ(test, left, right) \  argument
1434 	KUNIT_ASSERT_STRNEQ_MSG(test, left, right, NULL)
1436 #define KUNIT_ASSERT_STRNEQ_MSG(test, left, right, fmt, ...)		       \  argument
1437 	KUNIT_BINARY_STR_ASSERTION(test,				       \
1445  * @test: The test context object.
1452 #define KUNIT_ASSERT_NULL(test, ptr) \  argument
1453 	KUNIT_ASSERT_NULL_MSG(test,					       \
1457 #define KUNIT_ASSERT_NULL_MSG(test, ptr, fmt, ...) \  argument
1458 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
1466  * @test: The test context object.
1473 #define KUNIT_ASSERT_NOT_NULL(test, ptr) \  argument
1474 	KUNIT_ASSERT_NOT_NULL_MSG(test,					       \
1478 #define KUNIT_ASSERT_NOT_NULL_MSG(test, ptr, fmt, ...) \  argument
1479 	KUNIT_BINARY_PTR_ASSERTION(test,				       \
1487  * @test: The test context object.
1495 #define KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ptr) \  argument
1496 	KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL)
1498 #define KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...)		       \  argument
1499 	KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test,			       \
1506  * KUNIT_ARRAY_PARAM() - Define test parameter generator from an array.
1507  * @name:  prefix for the test parameter generator function.
1508  * @array: array of test parameters.
1527  * KUNIT_ARRAY_PARAM_DESC() - Define test parameter generator from an array.
1528  * @name:  prefix for the test parameter generator function.
1529  * @array: array of test parameters.