1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Base unit test (KUnit) API. 4 * 5 * Copyright (C) 2019, Google LLC. 6 * Author: Brendan Higgins <brendanhiggins@google.com> 7 */ 8 9 #ifndef _KUNIT_TEST_H 10 #define _KUNIT_TEST_H 11 12 #include <kunit/assert.h> 13 #include <kunit/try-catch.h> 14 15 #include <linux/args.h> 16 #include <linux/compiler.h> 17 #include <linux/container_of.h> 18 #include <linux/err.h> 19 #include <linux/init.h> 20 #include <linux/jump_label.h> 21 #include <linux/kconfig.h> 22 #include <linux/kref.h> 23 #include <linux/list.h> 24 #include <linux/module.h> 25 #include <linux/slab.h> 26 #include <linux/spinlock.h> 27 #include <linux/string.h> 28 #include <linux/types.h> 29 30 #include <asm/rwonce.h> 31 32 /* Static key: true if any KUnit tests are currently running */ 33 DECLARE_STATIC_KEY_FALSE(kunit_running); 34 35 struct kunit; 36 struct string_stream; 37 38 /* Maximum size of parameter description string. */ 39 #define KUNIT_PARAM_DESC_SIZE 128 40 41 /* Maximum size of a status comment. */ 42 #define KUNIT_STATUS_COMMENT_SIZE 256 43 44 /* 45 * TAP specifies subtest stream indentation of 4 spaces, 8 spaces for a 46 * sub-subtest. See the "Subtests" section in 47 * https://node-tap.org/tap-protocol/ 48 */ 49 #define KUNIT_INDENT_LEN 4 50 #define KUNIT_SUBTEST_INDENT " " 51 #define KUNIT_SUBSUBTEST_INDENT " " 52 53 /** 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. 58 */ 59 enum kunit_status { 60 KUNIT_SUCCESS, 61 KUNIT_FAILURE, 62 KUNIT_SKIPPED, 63 }; 64 65 /* Attribute struct/enum definitions */ 66 67 /* 68 * Speed Attribute is stored as an enum and separated into categories of 69 * speed: very_slowm, slow, and normal. These speeds are relative to 70 * other KUnit tests. 71 * 72 * Note: unset speed attribute acts as default of KUNIT_SPEED_NORMAL. 73 */ 74 enum kunit_speed { 75 KUNIT_SPEED_UNSET, 76 KUNIT_SPEED_VERY_SLOW, 77 KUNIT_SPEED_SLOW, 78 KUNIT_SPEED_NORMAL, 79 KUNIT_SPEED_MAX = KUNIT_SPEED_NORMAL, 80 }; 81 82 /* Holds attributes for each test case and suite */ 83 struct kunit_attributes { 84 enum kunit_speed speed; 85 }; 86 87 /** 88 * struct kunit_case - represents an individual test case. 89 * 90 * @run_case: the function representing the actual test case. 91 * @name: the name of the test case. 92 * @generate_params: the generator function for parameterized tests. 93 * @attr: the attributes associated with the test 94 * 95 * A test case is a function with the signature, 96 * ``void (*)(struct kunit *)`` 97 * that makes expectations and assertions (see KUNIT_EXPECT_TRUE() and 98 * KUNIT_ASSERT_TRUE()) about code under test. Each test case is associated 99 * with a &struct kunit_suite and will be run after the suite's init 100 * function and followed by the suite's exit function. 101 * 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. 105 * 106 * Example: 107 * 108 * .. code-block:: c 109 * 110 * void add_test_basic(struct kunit *test) 111 * { 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)); 117 * } 118 * 119 * static struct kunit_case example_test_cases[] = { 120 * KUNIT_CASE(add_test_basic), 121 * {} 122 * }; 123 * 124 */ 125 struct kunit_case { 126 void (*run_case)(struct kunit *test); 127 const char *name; 128 const void* (*generate_params)(const void *prev, char *desc); 129 struct kunit_attributes attr; 130 131 /* private: internal use only. */ 132 enum kunit_status status; 133 char *module_name; 134 struct string_stream *log; 135 }; 136 137 static inline char *kunit_status_to_ok_not_ok(enum kunit_status status) 138 { 139 switch (status) { 140 case KUNIT_SKIPPED: 141 case KUNIT_SUCCESS: 142 return "ok"; 143 case KUNIT_FAILURE: 144 return "not ok"; 145 } 146 return "invalid"; 147 } 148 149 /** 150 * KUNIT_CASE - A helper for creating a &struct kunit_case 151 * 152 * @test_name: a reference to a test case function. 153 * 154 * Takes a symbol for a function representing a test case and creates a 155 * &struct kunit_case object from it. See the documentation for 156 * &struct kunit_case for an example on how to use it. 157 */ 158 #define KUNIT_CASE(test_name) \ 159 { .run_case = test_name, .name = #test_name, \ 160 .module_name = KBUILD_MODNAME} 161 162 /** 163 * KUNIT_CASE_ATTR - A helper for creating a &struct kunit_case 164 * with attributes 165 * 166 * @test_name: a reference to a test case function. 167 * @attributes: a reference to a struct kunit_attributes object containing 168 * test attributes 169 */ 170 #define KUNIT_CASE_ATTR(test_name, attributes) \ 171 { .run_case = test_name, .name = #test_name, \ 172 .attr = attributes, .module_name = KBUILD_MODNAME} 173 174 /** 175 * KUNIT_CASE_SLOW - A helper for creating a &struct kunit_case 176 * with the slow attribute 177 * 178 * @test_name: a reference to a test case function. 179 */ 180 181 #define KUNIT_CASE_SLOW(test_name) \ 182 { .run_case = test_name, .name = #test_name, \ 183 .attr.speed = KUNIT_SPEED_SLOW, .module_name = KBUILD_MODNAME} 184 185 /** 186 * KUNIT_CASE_PARAM - A helper for creation a parameterized &struct kunit_case 187 * 188 * @test_name: a reference to a test case function. 189 * @gen_params: a reference to a parameter generator function. 190 * 191 * The generator function:: 192 * 193 * const void* gen_params(const void *prev, char *desc) 194 * 195 * is used to lazily generate a series of arbitrarily typed values that fit into 196 * a void*. The argument @prev is the previously returned value, which should be 197 * used to derive the next value; @prev is set to NULL on the initial generator 198 * call. When no more values are available, the generator must return NULL. 199 * Optionally write a string into @desc (size of KUNIT_PARAM_DESC_SIZE) 200 * describing the parameter. 201 */ 202 #define KUNIT_CASE_PARAM(test_name, gen_params) \ 203 { .run_case = test_name, .name = #test_name, \ 204 .generate_params = gen_params, .module_name = KBUILD_MODNAME} 205 206 /** 207 * KUNIT_CASE_PARAM_ATTR - A helper for creating a parameterized &struct 208 * kunit_case with attributes 209 * 210 * @test_name: a reference to a test case function. 211 * @gen_params: a reference to a parameter generator function. 212 * @attributes: a reference to a struct kunit_attributes object containing 213 * test attributes 214 */ 215 #define KUNIT_CASE_PARAM_ATTR(test_name, gen_params, attributes) \ 216 { .run_case = test_name, .name = #test_name, \ 217 .generate_params = gen_params, \ 218 .attr = attributes, .module_name = KBUILD_MODNAME} 219 220 /** 221 * struct kunit_suite - describes a related collection of &struct kunit_case 222 * 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 230 * 231 * A kunit_suite is a collection of related &struct kunit_case s, such that 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* 234 * in other unit testing frameworks like JUnit or Googletest. 235 * 236 * Note that @exit and @suite_exit will run even if @init or @suite_init 237 * fail: make sure they can handle any inconsistent state which may result. 238 * 239 * Every &struct kunit_case must be associated with a kunit_suite for KUnit 240 * to run it. 241 */ 242 struct kunit_suite { 243 const char name[256]; 244 int (*suite_init)(struct kunit_suite *suite); 245 void (*suite_exit)(struct kunit_suite *suite); 246 int (*init)(struct kunit *test); 247 void (*exit)(struct kunit *test); 248 struct kunit_case *test_cases; 249 struct kunit_attributes attr; 250 251 /* private: internal use only */ 252 char status_comment[KUNIT_STATUS_COMMENT_SIZE]; 253 struct dentry *debugfs; 254 struct string_stream *log; 255 int suite_init_err; 256 bool is_init; 257 }; 258 259 /* Stores an array of suites, end points one past the end */ 260 struct kunit_suite_set { 261 struct kunit_suite * const *start; 262 struct kunit_suite * const *end; 263 }; 264 265 /** 266 * struct kunit - represents a running instance of a test. 267 * 268 * @priv: for user to store arbitrary data. Commonly used to pass data 269 * created in the init function (see &struct kunit_suite). 270 * 271 * Used to store information about the current context under which the test 272 * is running. Most of this data is private and should only be accessed 273 * indirectly via public functions; the one exception is @priv which can be 274 * used by the test writer to store arbitrary data. 275 */ 276 struct kunit { 277 void *priv; 278 279 /* private: internal use only. */ 280 const char *name; /* Read only after initialization! */ 281 struct string_stream *log; /* Points at case log after initialization */ 282 struct kunit_try_catch try_catch; 283 /* param_value is the current parameter value for a test case. */ 284 const void *param_value; 285 /* param_index stores the index of the parameter in parameterized tests. */ 286 int param_index; 287 /* 288 * success starts as true, and may only be set to false during a 289 * test case; thus, it is safe to update this across multiple 290 * threads using WRITE_ONCE; however, as a consequence, it may only 291 * be read after the test case finishes once all threads associated 292 * with the test case have terminated. 293 */ 294 spinlock_t lock; /* Guards all mutable test state. */ 295 enum kunit_status status; /* Read only after test_case finishes! */ 296 /* 297 * Because resources is a list that may be updated multiple times (with 298 * new resources) from any thread associated with a test case, we must 299 * protect it with some type of lock. 300 */ 301 struct list_head resources; /* Protected by lock. */ 302 303 char status_comment[KUNIT_STATUS_COMMENT_SIZE]; 304 /* Saves the last seen test. Useful to help with faults. */ 305 struct kunit_loc last_seen; 306 }; 307 308 static inline void kunit_set_failure(struct kunit *test) 309 { 310 WRITE_ONCE(test->status, KUNIT_FAILURE); 311 } 312 313 bool kunit_enabled(void); 314 const char *kunit_action(void); 315 const char *kunit_filter_glob(void); 316 char *kunit_filter(void); 317 char *kunit_filter_action(void); 318 319 void kunit_init_test(struct kunit *test, const char *name, struct string_stream *log); 320 321 int kunit_run_tests(struct kunit_suite *suite); 322 323 size_t kunit_suite_num_test_cases(struct kunit_suite *suite); 324 325 unsigned int kunit_test_case_num(struct kunit_suite *suite, 326 struct kunit_case *test_case); 327 328 struct kunit_suite_set 329 kunit_filter_suites(const struct kunit_suite_set *suite_set, 330 const char *filter_glob, 331 char *filters, 332 char *filter_action, 333 int *err); 334 void kunit_free_suite_set(struct kunit_suite_set suite_set); 335 336 int __kunit_test_suites_init(struct kunit_suite * const * const suites, int num_suites); 337 338 void __kunit_test_suites_exit(struct kunit_suite **suites, int num_suites); 339 340 void kunit_exec_run_tests(struct kunit_suite_set *suite_set, bool builtin); 341 void kunit_exec_list_tests(struct kunit_suite_set *suite_set, bool include_attr); 342 343 struct kunit_suite_set kunit_merge_suite_sets(struct kunit_suite_set init_suite_set, 344 struct kunit_suite_set suite_set); 345 346 #if IS_BUILTIN(CONFIG_KUNIT) 347 int kunit_run_all_tests(void); 348 #else 349 static inline int kunit_run_all_tests(void) 350 { 351 return 0; 352 } 353 #endif /* IS_BUILTIN(CONFIG_KUNIT) */ 354 355 #define __kunit_test_suites(unique_array, ...) \ 356 static struct kunit_suite *unique_array[] \ 357 __aligned(sizeof(struct kunit_suite *)) \ 358 __used __section(".kunit_test_suites") = { __VA_ARGS__ } 359 360 /** 361 * kunit_test_suites() - used to register one or more &struct kunit_suite 362 * with KUnit. 363 * 364 * @__suites: a statically allocated list of &struct kunit_suite. 365 * 366 * Registers @suites with the test framework. 367 * This is done by placing the array of struct kunit_suite * in the 368 * .kunit_test_suites ELF section. 369 * 370 * When builtin, KUnit tests are all run via the executor at boot, and when 371 * built as a module, they run on module load. 372 * 373 */ 374 #define kunit_test_suites(__suites...) \ 375 __kunit_test_suites(__UNIQUE_ID(array), \ 376 ##__suites) 377 378 #define kunit_test_suite(suite) kunit_test_suites(&suite) 379 380 #define __kunit_init_test_suites(unique_array, ...) \ 381 static struct kunit_suite *unique_array[] \ 382 __aligned(sizeof(struct kunit_suite *)) \ 383 __used __section(".kunit_init_test_suites") = { __VA_ARGS__ } 384 385 /** 386 * kunit_test_init_section_suites() - used to register one or more &struct 387 * kunit_suite containing init functions or 388 * init data. 389 * 390 * @__suites: a statically allocated list of &struct kunit_suite. 391 * 392 * This functions similar to kunit_test_suites() except that it compiles the 393 * list of suites during init phase. 394 * 395 * This macro also suffixes the array and suite declarations it makes with 396 * _probe; so that modpost suppresses warnings about referencing init data 397 * for symbols named in this manner. 398 * 399 * Note: these init tests are not able to be run after boot so there is no 400 * "run" debugfs file generated for these tests. 401 * 402 * Also, do not mark the suite or test case structs with __initdata because 403 * they will be used after the init phase with debugfs. 404 */ 405 #define kunit_test_init_section_suites(__suites...) \ 406 __kunit_init_test_suites(CONCATENATE(__UNIQUE_ID(array), _probe), \ 407 ##__suites) 408 409 #define kunit_test_init_section_suite(suite) \ 410 kunit_test_init_section_suites(&suite) 411 412 #define kunit_suite_for_each_test_case(suite, test_case) \ 413 for (test_case = suite->test_cases; test_case->run_case; test_case++) 414 415 enum kunit_status kunit_suite_has_succeeded(struct kunit_suite *suite); 416 417 /** 418 * kunit_kmalloc_array() - Like kmalloc_array() except the allocation is *test managed*. 419 * @test: The test context object. 420 * @n: number of elements. 421 * @size: The size in bytes of the desired memory. 422 * @gfp: flags passed to underlying kmalloc(). 423 * 424 * Just like `kmalloc_array(...)`, except the allocation is managed by the test case 425 * and is automatically cleaned up after the test case concludes. See kunit_add_action() 426 * for more information. 427 * 428 * Note that some internal context data is also allocated with GFP_KERNEL, 429 * regardless of the gfp passed in. 430 */ 431 void *kunit_kmalloc_array(struct kunit *test, size_t n, size_t size, gfp_t gfp); 432 433 /** 434 * kunit_kmalloc() - Like kmalloc() except the allocation is *test managed*. 435 * @test: The test context object. 436 * @size: The size in bytes of the desired memory. 437 * @gfp: flags passed to underlying kmalloc(). 438 * 439 * See kmalloc() and kunit_kmalloc_array() for more information. 440 * 441 * Note that some internal context data is also allocated with GFP_KERNEL, 442 * regardless of the gfp passed in. 443 */ 444 static inline void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp) 445 { 446 return kunit_kmalloc_array(test, 1, size, gfp); 447 } 448 449 /** 450 * kunit_kfree() - Like kfree except for allocations managed by KUnit. 451 * @test: The test case to which the resource belongs. 452 * @ptr: The memory allocation to free. 453 */ 454 void kunit_kfree(struct kunit *test, const void *ptr); 455 456 /** 457 * kunit_kzalloc() - Just like kunit_kmalloc(), but zeroes the allocation. 458 * @test: The test context object. 459 * @size: The size in bytes of the desired memory. 460 * @gfp: flags passed to underlying kmalloc(). 461 * 462 * See kzalloc() and kunit_kmalloc_array() for more information. 463 */ 464 static inline void *kunit_kzalloc(struct kunit *test, size_t size, gfp_t gfp) 465 { 466 return kunit_kmalloc(test, size, gfp | __GFP_ZERO); 467 } 468 469 /** 470 * kunit_kcalloc() - Just like kunit_kmalloc_array(), but zeroes the allocation. 471 * @test: The test context object. 472 * @n: number of elements. 473 * @size: The size in bytes of the desired memory. 474 * @gfp: flags passed to underlying kmalloc(). 475 * 476 * See kcalloc() and kunit_kmalloc_array() for more information. 477 */ 478 static inline void *kunit_kcalloc(struct kunit *test, size_t n, size_t size, gfp_t gfp) 479 { 480 return kunit_kmalloc_array(test, n, size, gfp | __GFP_ZERO); 481 } 482 483 /** 484 * kunit_vm_mmap() - Allocate KUnit-tracked vm_mmap() area 485 * @test: The test context object. 486 * @file: struct file pointer to map from, if any 487 * @addr: desired address, if any 488 * @len: how many bytes to allocate 489 * @prot: mmap PROT_* bits 490 * @flag: mmap flags 491 * @offset: offset into @file to start mapping from. 492 * 493 * See vm_mmap() for more information. 494 */ 495 unsigned long kunit_vm_mmap(struct kunit *test, struct file *file, 496 unsigned long addr, unsigned long len, 497 unsigned long prot, unsigned long flag, 498 unsigned long offset); 499 500 void kunit_cleanup(struct kunit *test); 501 502 void __printf(2, 3) kunit_log_append(struct string_stream *log, const char *fmt, ...); 503 504 /** 505 * kunit_mark_skipped() - Marks @test_or_suite as skipped 506 * 507 * @test_or_suite: The test context object. 508 * @fmt: A printk() style format string. 509 * 510 * Marks the test as skipped. @fmt is given output as the test status 511 * comment, typically the reason the test was skipped. 512 * 513 * Test execution continues after kunit_mark_skipped() is called. 514 */ 515 #define kunit_mark_skipped(test_or_suite, fmt, ...) \ 516 do { \ 517 WRITE_ONCE((test_or_suite)->status, KUNIT_SKIPPED); \ 518 scnprintf((test_or_suite)->status_comment, \ 519 KUNIT_STATUS_COMMENT_SIZE, \ 520 fmt, ##__VA_ARGS__); \ 521 } while (0) 522 523 /** 524 * kunit_skip() - Marks @test_or_suite as skipped 525 * 526 * @test_or_suite: The test context object. 527 * @fmt: A printk() style format string. 528 * 529 * Skips the test. @fmt is given output as the test status 530 * comment, typically the reason the test was skipped. 531 * 532 * Test execution is halted after kunit_skip() is called. 533 */ 534 #define kunit_skip(test_or_suite, fmt, ...) \ 535 do { \ 536 kunit_mark_skipped((test_or_suite), fmt, ##__VA_ARGS__);\ 537 kunit_try_catch_throw(&((test_or_suite)->try_catch)); \ 538 } while (0) 539 540 /* 541 * printk and log to per-test or per-suite log buffer. Logging only done 542 * if CONFIG_KUNIT_DEBUGFS is 'y'; if it is 'n', no log is allocated/used. 543 */ 544 #define kunit_log(lvl, test_or_suite, fmt, ...) \ 545 do { \ 546 printk(lvl fmt, ##__VA_ARGS__); \ 547 kunit_log_append((test_or_suite)->log, fmt, \ 548 ##__VA_ARGS__); \ 549 } while (0) 550 551 #define kunit_printk(lvl, test, fmt, ...) \ 552 kunit_log(lvl, test, KUNIT_SUBTEST_INDENT "# %s: " fmt, \ 553 (test)->name, ##__VA_ARGS__) 554 555 /** 556 * kunit_info() - Prints an INFO level message associated with @test. 557 * 558 * @test: The test context object. 559 * @fmt: A printk() style format string. 560 * 561 * Prints an info level message associated with the test suite being run. 562 * Takes a variable number of format parameters just like printk(). 563 */ 564 #define kunit_info(test, fmt, ...) \ 565 kunit_printk(KERN_INFO, test, fmt, ##__VA_ARGS__) 566 567 /** 568 * kunit_warn() - Prints a WARN level message associated with @test. 569 * 570 * @test: The test context object. 571 * @fmt: A printk() style format string. 572 * 573 * Prints a warning level message. 574 */ 575 #define kunit_warn(test, fmt, ...) \ 576 kunit_printk(KERN_WARNING, test, fmt, ##__VA_ARGS__) 577 578 /** 579 * kunit_err() - Prints an ERROR level message associated with @test. 580 * 581 * @test: The test context object. 582 * @fmt: A printk() style format string. 583 * 584 * Prints an error level message. 585 */ 586 #define kunit_err(test, fmt, ...) \ 587 kunit_printk(KERN_ERR, test, fmt, ##__VA_ARGS__) 588 589 /* 590 * Must be called at the beginning of each KUNIT_*_ASSERTION(). 591 * Cf. KUNIT_CURRENT_LOC. 592 */ 593 #define _KUNIT_SAVE_LOC(test) do { \ 594 WRITE_ONCE(test->last_seen.file, __FILE__); \ 595 WRITE_ONCE(test->last_seen.line, __LINE__); \ 596 } while (0) 597 598 /** 599 * KUNIT_SUCCEED() - A no-op expectation. Only exists for code clarity. 600 * @test: The test context object. 601 * 602 * The opposite of KUNIT_FAIL(), it is an expectation that cannot fail. In other 603 * words, it does nothing and only exists for code clarity. See 604 * KUNIT_EXPECT_TRUE() for more information. 605 */ 606 #define KUNIT_SUCCEED(test) _KUNIT_SAVE_LOC(test) 607 608 void __noreturn __kunit_abort(struct kunit *test); 609 610 void __printf(6, 7) __kunit_do_failed_assertion(struct kunit *test, 611 const struct kunit_loc *loc, 612 enum kunit_assert_type type, 613 const struct kunit_assert *assert, 614 assert_format_t assert_format, 615 const char *fmt, ...); 616 617 #define _KUNIT_FAILED(test, assert_type, assert_class, assert_format, INITIALIZER, fmt, ...) do { \ 618 static const struct kunit_loc __loc = KUNIT_CURRENT_LOC; \ 619 const struct assert_class __assertion = INITIALIZER; \ 620 __kunit_do_failed_assertion(test, \ 621 &__loc, \ 622 assert_type, \ 623 &__assertion.assert, \ 624 assert_format, \ 625 fmt, \ 626 ##__VA_ARGS__); \ 627 if (assert_type == KUNIT_ASSERTION) \ 628 __kunit_abort(test); \ 629 } while (0) 630 631 632 #define KUNIT_FAIL_ASSERTION(test, assert_type, fmt, ...) do { \ 633 _KUNIT_SAVE_LOC(test); \ 634 _KUNIT_FAILED(test, \ 635 assert_type, \ 636 kunit_fail_assert, \ 637 kunit_fail_assert_format, \ 638 {}, \ 639 fmt, \ 640 ##__VA_ARGS__); \ 641 } while (0) 642 643 /** 644 * KUNIT_FAIL() - Always causes a test to fail when evaluated. 645 * @test: The test context object. 646 * @fmt: an informational message to be printed when the assertion is made. 647 * @...: string format arguments. 648 * 649 * The opposite of KUNIT_SUCCEED(), it is an expectation that always fails. In 650 * other words, it always results in a failed expectation, and consequently 651 * always causes the test case to fail when evaluated. See KUNIT_EXPECT_TRUE() 652 * for more information. 653 */ 654 #define KUNIT_FAIL(test, fmt, ...) \ 655 KUNIT_FAIL_ASSERTION(test, \ 656 KUNIT_EXPECTATION, \ 657 fmt, \ 658 ##__VA_ARGS__) 659 660 /* Helper to safely pass around an initializer list to other macros. */ 661 #define KUNIT_INIT_ASSERT(initializers...) { initializers } 662 663 #define KUNIT_UNARY_ASSERTION(test, \ 664 assert_type, \ 665 condition_, \ 666 expected_true_, \ 667 fmt, \ 668 ...) \ 669 do { \ 670 _KUNIT_SAVE_LOC(test); \ 671 if (likely(!!(condition_) == !!expected_true_)) \ 672 break; \ 673 \ 674 _KUNIT_FAILED(test, \ 675 assert_type, \ 676 kunit_unary_assert, \ 677 kunit_unary_assert_format, \ 678 KUNIT_INIT_ASSERT(.condition = #condition_, \ 679 .expected_true = expected_true_), \ 680 fmt, \ 681 ##__VA_ARGS__); \ 682 } while (0) 683 684 #define KUNIT_TRUE_MSG_ASSERTION(test, assert_type, condition, fmt, ...) \ 685 KUNIT_UNARY_ASSERTION(test, \ 686 assert_type, \ 687 condition, \ 688 true, \ 689 fmt, \ 690 ##__VA_ARGS__) 691 692 #define KUNIT_FALSE_MSG_ASSERTION(test, assert_type, condition, fmt, ...) \ 693 KUNIT_UNARY_ASSERTION(test, \ 694 assert_type, \ 695 condition, \ 696 false, \ 697 fmt, \ 698 ##__VA_ARGS__) 699 700 /* 701 * A factory macro for defining the assertions and expectations for the basic 702 * comparisons defined for the built in types. 703 * 704 * Unfortunately, there is no common type that all types can be promoted to for 705 * which all the binary operators behave the same way as for the actual types 706 * (for example, there is no type that long long and unsigned long long can 707 * both be cast to where the comparison result is preserved for all values). So 708 * the best we can do is do the comparison in the original types and then coerce 709 * everything to long long for printing; this way, the comparison behaves 710 * correctly and the printed out value usually makes sense without 711 * interpretation, but can always be interpreted to figure out the actual 712 * value. 713 */ 714 #define KUNIT_BASE_BINARY_ASSERTION(test, \ 715 assert_class, \ 716 format_func, \ 717 assert_type, \ 718 left, \ 719 op, \ 720 right, \ 721 fmt, \ 722 ...) \ 723 do { \ 724 const typeof(left) __left = (left); \ 725 const typeof(right) __right = (right); \ 726 static const struct kunit_binary_assert_text __text = { \ 727 .operation = #op, \ 728 .left_text = #left, \ 729 .right_text = #right, \ 730 }; \ 731 \ 732 _KUNIT_SAVE_LOC(test); \ 733 if (likely(__left op __right)) \ 734 break; \ 735 \ 736 _KUNIT_FAILED(test, \ 737 assert_type, \ 738 assert_class, \ 739 format_func, \ 740 KUNIT_INIT_ASSERT(.text = &__text, \ 741 .left_value = __left, \ 742 .right_value = __right), \ 743 fmt, \ 744 ##__VA_ARGS__); \ 745 } while (0) 746 747 #define KUNIT_BINARY_INT_ASSERTION(test, \ 748 assert_type, \ 749 left, \ 750 op, \ 751 right, \ 752 fmt, \ 753 ...) \ 754 KUNIT_BASE_BINARY_ASSERTION(test, \ 755 kunit_binary_assert, \ 756 kunit_binary_assert_format, \ 757 assert_type, \ 758 left, op, right, \ 759 fmt, \ 760 ##__VA_ARGS__) 761 762 #define KUNIT_BINARY_PTR_ASSERTION(test, \ 763 assert_type, \ 764 left, \ 765 op, \ 766 right, \ 767 fmt, \ 768 ...) \ 769 KUNIT_BASE_BINARY_ASSERTION(test, \ 770 kunit_binary_ptr_assert, \ 771 kunit_binary_ptr_assert_format, \ 772 assert_type, \ 773 left, op, right, \ 774 fmt, \ 775 ##__VA_ARGS__) 776 777 #define KUNIT_BINARY_STR_ASSERTION(test, \ 778 assert_type, \ 779 left, \ 780 op, \ 781 right, \ 782 fmt, \ 783 ...) \ 784 do { \ 785 const char *__left = (left); \ 786 const char *__right = (right); \ 787 static const struct kunit_binary_assert_text __text = { \ 788 .operation = #op, \ 789 .left_text = #left, \ 790 .right_text = #right, \ 791 }; \ 792 \ 793 _KUNIT_SAVE_LOC(test); \ 794 if (likely((__left) && (__right) && (strcmp(__left, __right) op 0))) \ 795 break; \ 796 \ 797 \ 798 _KUNIT_FAILED(test, \ 799 assert_type, \ 800 kunit_binary_str_assert, \ 801 kunit_binary_str_assert_format, \ 802 KUNIT_INIT_ASSERT(.text = &__text, \ 803 .left_value = __left, \ 804 .right_value = __right), \ 805 fmt, \ 806 ##__VA_ARGS__); \ 807 } while (0) 808 809 #define KUNIT_MEM_ASSERTION(test, \ 810 assert_type, \ 811 left, \ 812 op, \ 813 right, \ 814 size_, \ 815 fmt, \ 816 ...) \ 817 do { \ 818 const void *__left = (left); \ 819 const void *__right = (right); \ 820 const size_t __size = (size_); \ 821 static const struct kunit_binary_assert_text __text = { \ 822 .operation = #op, \ 823 .left_text = #left, \ 824 .right_text = #right, \ 825 }; \ 826 \ 827 _KUNIT_SAVE_LOC(test); \ 828 if (likely(__left && __right)) \ 829 if (likely(memcmp(__left, __right, __size) op 0)) \ 830 break; \ 831 \ 832 _KUNIT_FAILED(test, \ 833 assert_type, \ 834 kunit_mem_assert, \ 835 kunit_mem_assert_format, \ 836 KUNIT_INIT_ASSERT(.text = &__text, \ 837 .left_value = __left, \ 838 .right_value = __right, \ 839 .size = __size), \ 840 fmt, \ 841 ##__VA_ARGS__); \ 842 } while (0) 843 844 #define KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 845 assert_type, \ 846 ptr, \ 847 fmt, \ 848 ...) \ 849 do { \ 850 const typeof(ptr) __ptr = (ptr); \ 851 \ 852 _KUNIT_SAVE_LOC(test); \ 853 if (!IS_ERR_OR_NULL(__ptr)) \ 854 break; \ 855 \ 856 _KUNIT_FAILED(test, \ 857 assert_type, \ 858 kunit_ptr_not_err_assert, \ 859 kunit_ptr_not_err_assert_format, \ 860 KUNIT_INIT_ASSERT(.text = #ptr, .value = __ptr), \ 861 fmt, \ 862 ##__VA_ARGS__); \ 863 } while (0) 864 865 /** 866 * KUNIT_EXPECT_TRUE() - Causes a test failure when the expression is not true. 867 * @test: The test context object. 868 * @condition: an arbitrary boolean expression. The test fails when this does 869 * not evaluate to true. 870 * 871 * This and expectations of the form `KUNIT_EXPECT_*` will cause the test case 872 * to fail when the specified condition is not met; however, it will not prevent 873 * the test case from continuing to run; this is otherwise known as an 874 * *expectation failure*. 875 */ 876 #define KUNIT_EXPECT_TRUE(test, condition) \ 877 KUNIT_EXPECT_TRUE_MSG(test, condition, NULL) 878 879 #define KUNIT_EXPECT_TRUE_MSG(test, condition, fmt, ...) \ 880 KUNIT_TRUE_MSG_ASSERTION(test, \ 881 KUNIT_EXPECTATION, \ 882 condition, \ 883 fmt, \ 884 ##__VA_ARGS__) 885 886 /** 887 * KUNIT_EXPECT_FALSE() - Makes a test failure when the expression is not false. 888 * @test: The test context object. 889 * @condition: an arbitrary boolean expression. The test fails when this does 890 * not evaluate to false. 891 * 892 * Sets an expectation that @condition evaluates to false. See 893 * KUNIT_EXPECT_TRUE() for more information. 894 */ 895 #define KUNIT_EXPECT_FALSE(test, condition) \ 896 KUNIT_EXPECT_FALSE_MSG(test, condition, NULL) 897 898 #define KUNIT_EXPECT_FALSE_MSG(test, condition, fmt, ...) \ 899 KUNIT_FALSE_MSG_ASSERTION(test, \ 900 KUNIT_EXPECTATION, \ 901 condition, \ 902 fmt, \ 903 ##__VA_ARGS__) 904 905 /** 906 * KUNIT_EXPECT_EQ() - Sets an expectation that @left and @right are equal. 907 * @test: The test context object. 908 * @left: an arbitrary expression that evaluates to a primitive C type. 909 * @right: an arbitrary expression that evaluates to a primitive C type. 910 * 911 * Sets an expectation that the values that @left and @right evaluate to are 912 * equal. This is semantically equivalent to 913 * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for 914 * more information. 915 */ 916 #define KUNIT_EXPECT_EQ(test, left, right) \ 917 KUNIT_EXPECT_EQ_MSG(test, left, right, NULL) 918 919 #define KUNIT_EXPECT_EQ_MSG(test, left, right, fmt, ...) \ 920 KUNIT_BINARY_INT_ASSERTION(test, \ 921 KUNIT_EXPECTATION, \ 922 left, ==, right, \ 923 fmt, \ 924 ##__VA_ARGS__) 925 926 /** 927 * KUNIT_EXPECT_PTR_EQ() - Expects that pointers @left and @right are equal. 928 * @test: The test context object. 929 * @left: an arbitrary expression that evaluates to a pointer. 930 * @right: an arbitrary expression that evaluates to a pointer. 931 * 932 * Sets an expectation that the values that @left and @right evaluate to are 933 * equal. This is semantically equivalent to 934 * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for 935 * more information. 936 */ 937 #define KUNIT_EXPECT_PTR_EQ(test, left, right) \ 938 KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, NULL) 939 940 #define KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, fmt, ...) \ 941 KUNIT_BINARY_PTR_ASSERTION(test, \ 942 KUNIT_EXPECTATION, \ 943 left, ==, right, \ 944 fmt, \ 945 ##__VA_ARGS__) 946 947 /** 948 * KUNIT_EXPECT_NE() - An expectation that @left and @right are not equal. 949 * @test: The test context object. 950 * @left: an arbitrary expression that evaluates to a primitive C type. 951 * @right: an arbitrary expression that evaluates to a primitive C type. 952 * 953 * Sets an expectation that the values that @left and @right evaluate to are not 954 * equal. This is semantically equivalent to 955 * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for 956 * more information. 957 */ 958 #define KUNIT_EXPECT_NE(test, left, right) \ 959 KUNIT_EXPECT_NE_MSG(test, left, right, NULL) 960 961 #define KUNIT_EXPECT_NE_MSG(test, left, right, fmt, ...) \ 962 KUNIT_BINARY_INT_ASSERTION(test, \ 963 KUNIT_EXPECTATION, \ 964 left, !=, right, \ 965 fmt, \ 966 ##__VA_ARGS__) 967 968 /** 969 * KUNIT_EXPECT_PTR_NE() - Expects that pointers @left and @right are not equal. 970 * @test: The test context object. 971 * @left: an arbitrary expression that evaluates to a pointer. 972 * @right: an arbitrary expression that evaluates to a pointer. 973 * 974 * Sets an expectation that the values that @left and @right evaluate to are not 975 * equal. This is semantically equivalent to 976 * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for 977 * more information. 978 */ 979 #define KUNIT_EXPECT_PTR_NE(test, left, right) \ 980 KUNIT_EXPECT_PTR_NE_MSG(test, left, right, NULL) 981 982 #define KUNIT_EXPECT_PTR_NE_MSG(test, left, right, fmt, ...) \ 983 KUNIT_BINARY_PTR_ASSERTION(test, \ 984 KUNIT_EXPECTATION, \ 985 left, !=, right, \ 986 fmt, \ 987 ##__VA_ARGS__) 988 989 /** 990 * KUNIT_EXPECT_LT() - An expectation that @left is less than @right. 991 * @test: The test context object. 992 * @left: an arbitrary expression that evaluates to a primitive C type. 993 * @right: an arbitrary expression that evaluates to a primitive C type. 994 * 995 * Sets an expectation that the value that @left evaluates to is less than the 996 * value that @right evaluates to. This is semantically equivalent to 997 * KUNIT_EXPECT_TRUE(@test, (@left) < (@right)). See KUNIT_EXPECT_TRUE() for 998 * more information. 999 */ 1000 #define KUNIT_EXPECT_LT(test, left, right) \ 1001 KUNIT_EXPECT_LT_MSG(test, left, right, NULL) 1002 1003 #define KUNIT_EXPECT_LT_MSG(test, left, right, fmt, ...) \ 1004 KUNIT_BINARY_INT_ASSERTION(test, \ 1005 KUNIT_EXPECTATION, \ 1006 left, <, right, \ 1007 fmt, \ 1008 ##__VA_ARGS__) 1009 1010 /** 1011 * KUNIT_EXPECT_LE() - Expects that @left is less than or equal to @right. 1012 * @test: The test context object. 1013 * @left: an arbitrary expression that evaluates to a primitive C type. 1014 * @right: an arbitrary expression that evaluates to a primitive C type. 1015 * 1016 * Sets an expectation that the value that @left evaluates to is less than or 1017 * equal to the value that @right evaluates to. Semantically this is equivalent 1018 * to KUNIT_EXPECT_TRUE(@test, (@left) <= (@right)). See KUNIT_EXPECT_TRUE() for 1019 * more information. 1020 */ 1021 #define KUNIT_EXPECT_LE(test, left, right) \ 1022 KUNIT_EXPECT_LE_MSG(test, left, right, NULL) 1023 1024 #define KUNIT_EXPECT_LE_MSG(test, left, right, fmt, ...) \ 1025 KUNIT_BINARY_INT_ASSERTION(test, \ 1026 KUNIT_EXPECTATION, \ 1027 left, <=, right, \ 1028 fmt, \ 1029 ##__VA_ARGS__) 1030 1031 /** 1032 * KUNIT_EXPECT_GT() - An expectation that @left is greater than @right. 1033 * @test: The test context object. 1034 * @left: an arbitrary expression that evaluates to a primitive C type. 1035 * @right: an arbitrary expression that evaluates to a primitive C type. 1036 * 1037 * Sets an expectation that the value that @left evaluates to is greater than 1038 * the value that @right evaluates to. This is semantically equivalent to 1039 * KUNIT_EXPECT_TRUE(@test, (@left) > (@right)). See KUNIT_EXPECT_TRUE() for 1040 * more information. 1041 */ 1042 #define KUNIT_EXPECT_GT(test, left, right) \ 1043 KUNIT_EXPECT_GT_MSG(test, left, right, NULL) 1044 1045 #define KUNIT_EXPECT_GT_MSG(test, left, right, fmt, ...) \ 1046 KUNIT_BINARY_INT_ASSERTION(test, \ 1047 KUNIT_EXPECTATION, \ 1048 left, >, right, \ 1049 fmt, \ 1050 ##__VA_ARGS__) 1051 1052 /** 1053 * KUNIT_EXPECT_GE() - Expects that @left is greater than or equal to @right. 1054 * @test: The test context object. 1055 * @left: an arbitrary expression that evaluates to a primitive C type. 1056 * @right: an arbitrary expression that evaluates to a primitive C type. 1057 * 1058 * Sets an expectation that the value that @left evaluates to is greater than 1059 * the value that @right evaluates to. This is semantically equivalent to 1060 * KUNIT_EXPECT_TRUE(@test, (@left) >= (@right)). See KUNIT_EXPECT_TRUE() for 1061 * more information. 1062 */ 1063 #define KUNIT_EXPECT_GE(test, left, right) \ 1064 KUNIT_EXPECT_GE_MSG(test, left, right, NULL) 1065 1066 #define KUNIT_EXPECT_GE_MSG(test, left, right, fmt, ...) \ 1067 KUNIT_BINARY_INT_ASSERTION(test, \ 1068 KUNIT_EXPECTATION, \ 1069 left, >=, right, \ 1070 fmt, \ 1071 ##__VA_ARGS__) 1072 1073 /** 1074 * KUNIT_EXPECT_STREQ() - Expects that strings @left and @right are equal. 1075 * @test: The test context object. 1076 * @left: an arbitrary expression that evaluates to a null terminated string. 1077 * @right: an arbitrary expression that evaluates to a null terminated string. 1078 * 1079 * Sets an expectation that the values that @left and @right evaluate to are 1080 * equal. This is semantically equivalent to 1081 * KUNIT_EXPECT_TRUE(@test, !strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE() 1082 * for more information. 1083 */ 1084 #define KUNIT_EXPECT_STREQ(test, left, right) \ 1085 KUNIT_EXPECT_STREQ_MSG(test, left, right, NULL) 1086 1087 #define KUNIT_EXPECT_STREQ_MSG(test, left, right, fmt, ...) \ 1088 KUNIT_BINARY_STR_ASSERTION(test, \ 1089 KUNIT_EXPECTATION, \ 1090 left, ==, right, \ 1091 fmt, \ 1092 ##__VA_ARGS__) 1093 1094 /** 1095 * KUNIT_EXPECT_STRNEQ() - Expects that strings @left and @right are not equal. 1096 * @test: The test context object. 1097 * @left: an arbitrary expression that evaluates to a null terminated string. 1098 * @right: an arbitrary expression that evaluates to a null terminated string. 1099 * 1100 * Sets an expectation that the values that @left and @right evaluate to are 1101 * not equal. This is semantically equivalent to 1102 * KUNIT_EXPECT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE() 1103 * for more information. 1104 */ 1105 #define KUNIT_EXPECT_STRNEQ(test, left, right) \ 1106 KUNIT_EXPECT_STRNEQ_MSG(test, left, right, NULL) 1107 1108 #define KUNIT_EXPECT_STRNEQ_MSG(test, left, right, fmt, ...) \ 1109 KUNIT_BINARY_STR_ASSERTION(test, \ 1110 KUNIT_EXPECTATION, \ 1111 left, !=, right, \ 1112 fmt, \ 1113 ##__VA_ARGS__) 1114 1115 /** 1116 * KUNIT_EXPECT_MEMEQ() - Expects that the first @size bytes of @left and @right are equal. 1117 * @test: The test context object. 1118 * @left: An arbitrary expression that evaluates to the specified size. 1119 * @right: An arbitrary expression that evaluates to the specified size. 1120 * @size: Number of bytes compared. 1121 * 1122 * Sets an expectation that the values that @left and @right evaluate to are 1123 * equal. This is semantically equivalent to 1124 * KUNIT_EXPECT_TRUE(@test, !memcmp((@left), (@right), (@size))). See 1125 * KUNIT_EXPECT_TRUE() for more information. 1126 * 1127 * Although this expectation works for any memory block, it is not recommended 1128 * for comparing more structured data, such as structs. This expectation is 1129 * recommended for comparing, for example, data arrays. 1130 */ 1131 #define KUNIT_EXPECT_MEMEQ(test, left, right, size) \ 1132 KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, NULL) 1133 1134 #define KUNIT_EXPECT_MEMEQ_MSG(test, left, right, size, fmt, ...) \ 1135 KUNIT_MEM_ASSERTION(test, \ 1136 KUNIT_EXPECTATION, \ 1137 left, ==, right, \ 1138 size, \ 1139 fmt, \ 1140 ##__VA_ARGS__) 1141 1142 /** 1143 * KUNIT_EXPECT_MEMNEQ() - Expects that the first @size bytes of @left and @right are not equal. 1144 * @test: The test context object. 1145 * @left: An arbitrary expression that evaluates to the specified size. 1146 * @right: An arbitrary expression that evaluates to the specified size. 1147 * @size: Number of bytes compared. 1148 * 1149 * Sets an expectation that the values that @left and @right evaluate to are 1150 * not equal. This is semantically equivalent to 1151 * KUNIT_EXPECT_TRUE(@test, memcmp((@left), (@right), (@size))). See 1152 * KUNIT_EXPECT_TRUE() for more information. 1153 * 1154 * Although this expectation works for any memory block, it is not recommended 1155 * for comparing more structured data, such as structs. This expectation is 1156 * recommended for comparing, for example, data arrays. 1157 */ 1158 #define KUNIT_EXPECT_MEMNEQ(test, left, right, size) \ 1159 KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, NULL) 1160 1161 #define KUNIT_EXPECT_MEMNEQ_MSG(test, left, right, size, fmt, ...) \ 1162 KUNIT_MEM_ASSERTION(test, \ 1163 KUNIT_EXPECTATION, \ 1164 left, !=, right, \ 1165 size, \ 1166 fmt, \ 1167 ##__VA_ARGS__) 1168 1169 /** 1170 * KUNIT_EXPECT_NULL() - Expects that @ptr is null. 1171 * @test: The test context object. 1172 * @ptr: an arbitrary pointer. 1173 * 1174 * Sets an expectation that the value that @ptr evaluates to is null. This is 1175 * semantically equivalent to KUNIT_EXPECT_PTR_EQ(@test, ptr, NULL). 1176 * See KUNIT_EXPECT_TRUE() for more information. 1177 */ 1178 #define KUNIT_EXPECT_NULL(test, ptr) \ 1179 KUNIT_EXPECT_NULL_MSG(test, \ 1180 ptr, \ 1181 NULL) 1182 1183 #define KUNIT_EXPECT_NULL_MSG(test, ptr, fmt, ...) \ 1184 KUNIT_BINARY_PTR_ASSERTION(test, \ 1185 KUNIT_EXPECTATION, \ 1186 ptr, ==, NULL, \ 1187 fmt, \ 1188 ##__VA_ARGS__) 1189 1190 /** 1191 * KUNIT_EXPECT_NOT_NULL() - Expects that @ptr is not null. 1192 * @test: The test context object. 1193 * @ptr: an arbitrary pointer. 1194 * 1195 * Sets an expectation that the value that @ptr evaluates to is not null. This 1196 * is semantically equivalent to KUNIT_EXPECT_PTR_NE(@test, ptr, NULL). 1197 * See KUNIT_EXPECT_TRUE() for more information. 1198 */ 1199 #define KUNIT_EXPECT_NOT_NULL(test, ptr) \ 1200 KUNIT_EXPECT_NOT_NULL_MSG(test, \ 1201 ptr, \ 1202 NULL) 1203 1204 #define KUNIT_EXPECT_NOT_NULL_MSG(test, ptr, fmt, ...) \ 1205 KUNIT_BINARY_PTR_ASSERTION(test, \ 1206 KUNIT_EXPECTATION, \ 1207 ptr, !=, NULL, \ 1208 fmt, \ 1209 ##__VA_ARGS__) 1210 1211 /** 1212 * KUNIT_EXPECT_NOT_ERR_OR_NULL() - Expects that @ptr is not null and not err. 1213 * @test: The test context object. 1214 * @ptr: an arbitrary pointer. 1215 * 1216 * Sets an expectation that the value that @ptr evaluates to is not null and not 1217 * an errno stored in a pointer. This is semantically equivalent to 1218 * KUNIT_EXPECT_TRUE(@test, !IS_ERR_OR_NULL(@ptr)). See KUNIT_EXPECT_TRUE() for 1219 * more information. 1220 */ 1221 #define KUNIT_EXPECT_NOT_ERR_OR_NULL(test, ptr) \ 1222 KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL) 1223 1224 #define KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...) \ 1225 KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 1226 KUNIT_EXPECTATION, \ 1227 ptr, \ 1228 fmt, \ 1229 ##__VA_ARGS__) 1230 1231 /** 1232 * KUNIT_FAIL_AND_ABORT() - Always causes a test to fail and abort when evaluated. 1233 * @test: The test context object. 1234 * @fmt: an informational message to be printed when the assertion is made. 1235 * @...: string format arguments. 1236 * 1237 * The opposite of KUNIT_SUCCEED(), it is an assertion that always fails. In 1238 * other words, it always results in a failed assertion, and consequently 1239 * always causes the test case to fail and abort when evaluated. 1240 * See KUNIT_ASSERT_TRUE() for more information. 1241 */ 1242 #define KUNIT_FAIL_AND_ABORT(test, fmt, ...) \ 1243 KUNIT_FAIL_ASSERTION(test, KUNIT_ASSERTION, fmt, ##__VA_ARGS__) 1244 1245 /** 1246 * KUNIT_ASSERT_TRUE() - Sets an assertion that @condition is true. 1247 * @test: The test context object. 1248 * @condition: an arbitrary boolean expression. The test fails and aborts when 1249 * this does not evaluate to true. 1250 * 1251 * This and assertions of the form `KUNIT_ASSERT_*` will cause the test case to 1252 * fail *and immediately abort* when the specified condition is not met. Unlike 1253 * an expectation failure, it will prevent the test case from continuing to run; 1254 * this is otherwise known as an *assertion failure*. 1255 */ 1256 #define KUNIT_ASSERT_TRUE(test, condition) \ 1257 KUNIT_ASSERT_TRUE_MSG(test, condition, NULL) 1258 1259 #define KUNIT_ASSERT_TRUE_MSG(test, condition, fmt, ...) \ 1260 KUNIT_TRUE_MSG_ASSERTION(test, \ 1261 KUNIT_ASSERTION, \ 1262 condition, \ 1263 fmt, \ 1264 ##__VA_ARGS__) 1265 1266 /** 1267 * KUNIT_ASSERT_FALSE() - Sets an assertion that @condition is false. 1268 * @test: The test context object. 1269 * @condition: an arbitrary boolean expression. 1270 * 1271 * Sets an assertion that the value that @condition evaluates to is false. This 1272 * is the same as KUNIT_EXPECT_FALSE(), except it causes an assertion failure 1273 * (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1274 */ 1275 #define KUNIT_ASSERT_FALSE(test, condition) \ 1276 KUNIT_ASSERT_FALSE_MSG(test, condition, NULL) 1277 1278 #define KUNIT_ASSERT_FALSE_MSG(test, condition, fmt, ...) \ 1279 KUNIT_FALSE_MSG_ASSERTION(test, \ 1280 KUNIT_ASSERTION, \ 1281 condition, \ 1282 fmt, \ 1283 ##__VA_ARGS__) 1284 1285 /** 1286 * KUNIT_ASSERT_EQ() - Sets an assertion that @left and @right are equal. 1287 * @test: The test context object. 1288 * @left: an arbitrary expression that evaluates to a primitive C type. 1289 * @right: an arbitrary expression that evaluates to a primitive C type. 1290 * 1291 * Sets an assertion that the values that @left and @right evaluate to are 1292 * equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion 1293 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1294 */ 1295 #define KUNIT_ASSERT_EQ(test, left, right) \ 1296 KUNIT_ASSERT_EQ_MSG(test, left, right, NULL) 1297 1298 #define KUNIT_ASSERT_EQ_MSG(test, left, right, fmt, ...) \ 1299 KUNIT_BINARY_INT_ASSERTION(test, \ 1300 KUNIT_ASSERTION, \ 1301 left, ==, right, \ 1302 fmt, \ 1303 ##__VA_ARGS__) 1304 1305 /** 1306 * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal. 1307 * @test: The test context object. 1308 * @left: an arbitrary expression that evaluates to a pointer. 1309 * @right: an arbitrary expression that evaluates to a pointer. 1310 * 1311 * Sets an assertion that the values that @left and @right evaluate to are 1312 * equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion 1313 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1314 */ 1315 #define KUNIT_ASSERT_PTR_EQ(test, left, right) \ 1316 KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, NULL) 1317 1318 #define KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, fmt, ...) \ 1319 KUNIT_BINARY_PTR_ASSERTION(test, \ 1320 KUNIT_ASSERTION, \ 1321 left, ==, right, \ 1322 fmt, \ 1323 ##__VA_ARGS__) 1324 1325 /** 1326 * KUNIT_ASSERT_NE() - An assertion that @left and @right are not equal. 1327 * @test: The test context object. 1328 * @left: an arbitrary expression that evaluates to a primitive C type. 1329 * @right: an arbitrary expression that evaluates to a primitive C type. 1330 * 1331 * Sets an assertion that the values that @left and @right evaluate to are not 1332 * equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion 1333 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1334 */ 1335 #define KUNIT_ASSERT_NE(test, left, right) \ 1336 KUNIT_ASSERT_NE_MSG(test, left, right, NULL) 1337 1338 #define KUNIT_ASSERT_NE_MSG(test, left, right, fmt, ...) \ 1339 KUNIT_BINARY_INT_ASSERTION(test, \ 1340 KUNIT_ASSERTION, \ 1341 left, !=, right, \ 1342 fmt, \ 1343 ##__VA_ARGS__) 1344 1345 /** 1346 * KUNIT_ASSERT_PTR_NE() - Asserts that pointers @left and @right are not equal. 1347 * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal. 1348 * @test: The test context object. 1349 * @left: an arbitrary expression that evaluates to a pointer. 1350 * @right: an arbitrary expression that evaluates to a pointer. 1351 * 1352 * Sets an assertion that the values that @left and @right evaluate to are not 1353 * equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion 1354 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1355 */ 1356 #define KUNIT_ASSERT_PTR_NE(test, left, right) \ 1357 KUNIT_ASSERT_PTR_NE_MSG(test, left, right, NULL) 1358 1359 #define KUNIT_ASSERT_PTR_NE_MSG(test, left, right, fmt, ...) \ 1360 KUNIT_BINARY_PTR_ASSERTION(test, \ 1361 KUNIT_ASSERTION, \ 1362 left, !=, right, \ 1363 fmt, \ 1364 ##__VA_ARGS__) 1365 /** 1366 * KUNIT_ASSERT_LT() - An assertion that @left is less than @right. 1367 * @test: The test context object. 1368 * @left: an arbitrary expression that evaluates to a primitive C type. 1369 * @right: an arbitrary expression that evaluates to a primitive C type. 1370 * 1371 * Sets an assertion that the value that @left evaluates to is less than the 1372 * value that @right evaluates to. This is the same as KUNIT_EXPECT_LT(), except 1373 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1374 * is not met. 1375 */ 1376 #define KUNIT_ASSERT_LT(test, left, right) \ 1377 KUNIT_ASSERT_LT_MSG(test, left, right, NULL) 1378 1379 #define KUNIT_ASSERT_LT_MSG(test, left, right, fmt, ...) \ 1380 KUNIT_BINARY_INT_ASSERTION(test, \ 1381 KUNIT_ASSERTION, \ 1382 left, <, right, \ 1383 fmt, \ 1384 ##__VA_ARGS__) 1385 /** 1386 * KUNIT_ASSERT_LE() - An assertion that @left is less than or equal to @right. 1387 * @test: The test context object. 1388 * @left: an arbitrary expression that evaluates to a primitive C type. 1389 * @right: an arbitrary expression that evaluates to a primitive C type. 1390 * 1391 * Sets an assertion that the value that @left evaluates to is less than or 1392 * equal to the value that @right evaluates to. This is the same as 1393 * KUNIT_EXPECT_LE(), except it causes an assertion failure (see 1394 * KUNIT_ASSERT_TRUE()) when the assertion is not met. 1395 */ 1396 #define KUNIT_ASSERT_LE(test, left, right) \ 1397 KUNIT_ASSERT_LE_MSG(test, left, right, NULL) 1398 1399 #define KUNIT_ASSERT_LE_MSG(test, left, right, fmt, ...) \ 1400 KUNIT_BINARY_INT_ASSERTION(test, \ 1401 KUNIT_ASSERTION, \ 1402 left, <=, right, \ 1403 fmt, \ 1404 ##__VA_ARGS__) 1405 1406 /** 1407 * KUNIT_ASSERT_GT() - An assertion that @left is greater than @right. 1408 * @test: The test context object. 1409 * @left: an arbitrary expression that evaluates to a primitive C type. 1410 * @right: an arbitrary expression that evaluates to a primitive C type. 1411 * 1412 * Sets an assertion that the value that @left evaluates to is greater than the 1413 * value that @right evaluates to. This is the same as KUNIT_EXPECT_GT(), except 1414 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1415 * is not met. 1416 */ 1417 #define KUNIT_ASSERT_GT(test, left, right) \ 1418 KUNIT_ASSERT_GT_MSG(test, left, right, NULL) 1419 1420 #define KUNIT_ASSERT_GT_MSG(test, left, right, fmt, ...) \ 1421 KUNIT_BINARY_INT_ASSERTION(test, \ 1422 KUNIT_ASSERTION, \ 1423 left, >, right, \ 1424 fmt, \ 1425 ##__VA_ARGS__) 1426 1427 /** 1428 * KUNIT_ASSERT_GE() - Assertion that @left is greater than or equal to @right. 1429 * @test: The test context object. 1430 * @left: an arbitrary expression that evaluates to a primitive C type. 1431 * @right: an arbitrary expression that evaluates to a primitive C type. 1432 * 1433 * Sets an assertion that the value that @left evaluates to is greater than the 1434 * value that @right evaluates to. This is the same as KUNIT_EXPECT_GE(), except 1435 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1436 * is not met. 1437 */ 1438 #define KUNIT_ASSERT_GE(test, left, right) \ 1439 KUNIT_ASSERT_GE_MSG(test, left, right, NULL) 1440 1441 #define KUNIT_ASSERT_GE_MSG(test, left, right, fmt, ...) \ 1442 KUNIT_BINARY_INT_ASSERTION(test, \ 1443 KUNIT_ASSERTION, \ 1444 left, >=, right, \ 1445 fmt, \ 1446 ##__VA_ARGS__) 1447 1448 /** 1449 * KUNIT_ASSERT_STREQ() - An assertion that strings @left and @right are equal. 1450 * @test: The test context object. 1451 * @left: an arbitrary expression that evaluates to a null terminated string. 1452 * @right: an arbitrary expression that evaluates to a null terminated string. 1453 * 1454 * Sets an assertion that the values that @left and @right evaluate to are 1455 * equal. This is the same as KUNIT_EXPECT_STREQ(), except it causes an 1456 * assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1457 */ 1458 #define KUNIT_ASSERT_STREQ(test, left, right) \ 1459 KUNIT_ASSERT_STREQ_MSG(test, left, right, NULL) 1460 1461 #define KUNIT_ASSERT_STREQ_MSG(test, left, right, fmt, ...) \ 1462 KUNIT_BINARY_STR_ASSERTION(test, \ 1463 KUNIT_ASSERTION, \ 1464 left, ==, right, \ 1465 fmt, \ 1466 ##__VA_ARGS__) 1467 1468 /** 1469 * KUNIT_ASSERT_STRNEQ() - An assertion that strings @left and @right are not equal. 1470 * @test: The test context object. 1471 * @left: an arbitrary expression that evaluates to a null terminated string. 1472 * @right: an arbitrary expression that evaluates to a null terminated string. 1473 * 1474 * Sets an assertion that the values that @left and @right evaluate to are 1475 * not equal. This is semantically equivalent to 1476 * KUNIT_ASSERT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_ASSERT_TRUE() 1477 * for more information. 1478 */ 1479 #define KUNIT_ASSERT_STRNEQ(test, left, right) \ 1480 KUNIT_ASSERT_STRNEQ_MSG(test, left, right, NULL) 1481 1482 #define KUNIT_ASSERT_STRNEQ_MSG(test, left, right, fmt, ...) \ 1483 KUNIT_BINARY_STR_ASSERTION(test, \ 1484 KUNIT_ASSERTION, \ 1485 left, !=, right, \ 1486 fmt, \ 1487 ##__VA_ARGS__) 1488 1489 /** 1490 * KUNIT_ASSERT_MEMEQ() - Asserts that the first @size bytes of @left and @right are equal. 1491 * @test: The test context object. 1492 * @left: An arbitrary expression that evaluates to the specified size. 1493 * @right: An arbitrary expression that evaluates to the specified size. 1494 * @size: Number of bytes compared. 1495 * 1496 * Sets an assertion that the values that @left and @right evaluate to are 1497 * equal. This is semantically equivalent to 1498 * KUNIT_ASSERT_TRUE(@test, !memcmp((@left), (@right), (@size))). See 1499 * KUNIT_ASSERT_TRUE() for more information. 1500 * 1501 * Although this assertion works for any memory block, it is not recommended 1502 * for comparing more structured data, such as structs. This assertion is 1503 * recommended for comparing, for example, data arrays. 1504 */ 1505 #define KUNIT_ASSERT_MEMEQ(test, left, right, size) \ 1506 KUNIT_ASSERT_MEMEQ_MSG(test, left, right, size, NULL) 1507 1508 #define KUNIT_ASSERT_MEMEQ_MSG(test, left, right, size, fmt, ...) \ 1509 KUNIT_MEM_ASSERTION(test, \ 1510 KUNIT_ASSERTION, \ 1511 left, ==, right, \ 1512 size, \ 1513 fmt, \ 1514 ##__VA_ARGS__) 1515 1516 /** 1517 * KUNIT_ASSERT_MEMNEQ() - Asserts that the first @size bytes of @left and @right are not equal. 1518 * @test: The test context object. 1519 * @left: An arbitrary expression that evaluates to the specified size. 1520 * @right: An arbitrary expression that evaluates to the specified size. 1521 * @size: Number of bytes compared. 1522 * 1523 * Sets an assertion that the values that @left and @right evaluate to are 1524 * not equal. This is semantically equivalent to 1525 * KUNIT_ASSERT_TRUE(@test, memcmp((@left), (@right), (@size))). See 1526 * KUNIT_ASSERT_TRUE() for more information. 1527 * 1528 * Although this assertion works for any memory block, it is not recommended 1529 * for comparing more structured data, such as structs. This assertion is 1530 * recommended for comparing, for example, data arrays. 1531 */ 1532 #define KUNIT_ASSERT_MEMNEQ(test, left, right, size) \ 1533 KUNIT_ASSERT_MEMNEQ_MSG(test, left, right, size, NULL) 1534 1535 #define KUNIT_ASSERT_MEMNEQ_MSG(test, left, right, size, fmt, ...) \ 1536 KUNIT_MEM_ASSERTION(test, \ 1537 KUNIT_ASSERTION, \ 1538 left, !=, right, \ 1539 size, \ 1540 fmt, \ 1541 ##__VA_ARGS__) 1542 1543 /** 1544 * KUNIT_ASSERT_NULL() - Asserts that pointers @ptr is null. 1545 * @test: The test context object. 1546 * @ptr: an arbitrary pointer. 1547 * 1548 * Sets an assertion that the values that @ptr evaluates to is null. This is 1549 * the same as KUNIT_EXPECT_NULL(), except it causes an assertion 1550 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1551 */ 1552 #define KUNIT_ASSERT_NULL(test, ptr) \ 1553 KUNIT_ASSERT_NULL_MSG(test, \ 1554 ptr, \ 1555 NULL) 1556 1557 #define KUNIT_ASSERT_NULL_MSG(test, ptr, fmt, ...) \ 1558 KUNIT_BINARY_PTR_ASSERTION(test, \ 1559 KUNIT_ASSERTION, \ 1560 ptr, ==, NULL, \ 1561 fmt, \ 1562 ##__VA_ARGS__) 1563 1564 /** 1565 * KUNIT_ASSERT_NOT_NULL() - Asserts that pointers @ptr is not null. 1566 * @test: The test context object. 1567 * @ptr: an arbitrary pointer. 1568 * 1569 * Sets an assertion that the values that @ptr evaluates to is not null. This 1570 * is the same as KUNIT_EXPECT_NOT_NULL(), except it causes an assertion 1571 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1572 */ 1573 #define KUNIT_ASSERT_NOT_NULL(test, ptr) \ 1574 KUNIT_ASSERT_NOT_NULL_MSG(test, \ 1575 ptr, \ 1576 NULL) 1577 1578 #define KUNIT_ASSERT_NOT_NULL_MSG(test, ptr, fmt, ...) \ 1579 KUNIT_BINARY_PTR_ASSERTION(test, \ 1580 KUNIT_ASSERTION, \ 1581 ptr, !=, NULL, \ 1582 fmt, \ 1583 ##__VA_ARGS__) 1584 1585 /** 1586 * KUNIT_ASSERT_NOT_ERR_OR_NULL() - Assertion that @ptr is not null and not err. 1587 * @test: The test context object. 1588 * @ptr: an arbitrary pointer. 1589 * 1590 * Sets an assertion that the value that @ptr evaluates to is not null and not 1591 * an errno stored in a pointer. This is the same as 1592 * KUNIT_EXPECT_NOT_ERR_OR_NULL(), except it causes an assertion failure (see 1593 * KUNIT_ASSERT_TRUE()) when the assertion is not met. 1594 */ 1595 #define KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ptr) \ 1596 KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL) 1597 1598 #define KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...) \ 1599 KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 1600 KUNIT_ASSERTION, \ 1601 ptr, \ 1602 fmt, \ 1603 ##__VA_ARGS__) 1604 1605 /** 1606 * KUNIT_ARRAY_PARAM() - Define test parameter generator from an array. 1607 * @name: prefix for the test parameter generator function. 1608 * @array: array of test parameters. 1609 * @get_desc: function to convert param to description; NULL to use default 1610 * 1611 * Define function @name_gen_params which uses @array to generate parameters. 1612 */ 1613 #define KUNIT_ARRAY_PARAM(name, array, get_desc) \ 1614 static const void *name##_gen_params(const void *prev, char *desc) \ 1615 { \ 1616 typeof((array)[0]) *__next = prev ? ((typeof(__next)) prev) + 1 : (array); \ 1617 if (__next - (array) < ARRAY_SIZE((array))) { \ 1618 void (*__get_desc)(typeof(__next), char *) = get_desc; \ 1619 if (__get_desc) \ 1620 __get_desc(__next, desc); \ 1621 return __next; \ 1622 } \ 1623 return NULL; \ 1624 } 1625 1626 /** 1627 * KUNIT_ARRAY_PARAM_DESC() - Define test parameter generator from an array. 1628 * @name: prefix for the test parameter generator function. 1629 * @array: array of test parameters. 1630 * @desc_member: structure member from array element to use as description 1631 * 1632 * Define function @name_gen_params which uses @array to generate parameters. 1633 */ 1634 #define KUNIT_ARRAY_PARAM_DESC(name, array, desc_member) \ 1635 static const void *name##_gen_params(const void *prev, char *desc) \ 1636 { \ 1637 typeof((array)[0]) *__next = prev ? ((typeof(__next)) prev) + 1 : (array); \ 1638 if (__next - (array) < ARRAY_SIZE((array))) { \ 1639 strscpy(desc, __next->desc_member, KUNIT_PARAM_DESC_SIZE); \ 1640 return __next; \ 1641 } \ 1642 return NULL; \ 1643 } 1644 1645 // TODO(dlatypov@google.com): consider eventually migrating users to explicitly 1646 // include resource.h themselves if they need it. 1647 #include <kunit/resource.h> 1648 1649 #endif /* _KUNIT_TEST_H */ 1650