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