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