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/compiler.h> 16 #include <linux/container_of.h> 17 #include <linux/err.h> 18 #include <linux/init.h> 19 #include <linux/kconfig.h> 20 #include <linux/kref.h> 21 #include <linux/list.h> 22 #include <linux/module.h> 23 #include <linux/slab.h> 24 #include <linux/spinlock.h> 25 #include <linux/string.h> 26 #include <linux/types.h> 27 28 #include <asm/rwonce.h> 29 30 struct kunit_resource; 31 32 typedef int (*kunit_resource_init_t)(struct kunit_resource *, void *); 33 typedef void (*kunit_resource_free_t)(struct kunit_resource *); 34 35 /** 36 * struct kunit_resource - represents a *test managed resource* 37 * @data: for the user to store arbitrary data. 38 * @name: optional name 39 * @free: a user supplied function to free the resource. Populated by 40 * kunit_resource_alloc(). 41 * 42 * Represents a *test managed resource*, a resource which will automatically be 43 * cleaned up at the end of a test case. 44 * 45 * Resources are reference counted so if a resource is retrieved via 46 * kunit_alloc_and_get_resource() or kunit_find_resource(), we need 47 * to call kunit_put_resource() to reduce the resource reference count 48 * when finished with it. Note that kunit_alloc_resource() does not require a 49 * kunit_resource_put() because it does not retrieve the resource itself. 50 * 51 * Example: 52 * 53 * .. code-block:: c 54 * 55 * struct kunit_kmalloc_params { 56 * size_t size; 57 * gfp_t gfp; 58 * }; 59 * 60 * static int kunit_kmalloc_init(struct kunit_resource *res, void *context) 61 * { 62 * struct kunit_kmalloc_params *params = context; 63 * res->data = kmalloc(params->size, params->gfp); 64 * 65 * if (!res->data) 66 * return -ENOMEM; 67 * 68 * return 0; 69 * } 70 * 71 * static void kunit_kmalloc_free(struct kunit_resource *res) 72 * { 73 * kfree(res->data); 74 * } 75 * 76 * void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp) 77 * { 78 * struct kunit_kmalloc_params params; 79 * 80 * params.size = size; 81 * params.gfp = gfp; 82 * 83 * return kunit_alloc_resource(test, kunit_kmalloc_init, 84 * kunit_kmalloc_free, ¶ms); 85 * } 86 * 87 * Resources can also be named, with lookup/removal done on a name 88 * basis also. kunit_add_named_resource(), kunit_find_named_resource() 89 * and kunit_destroy_named_resource(). Resource names must be 90 * unique within the test instance. 91 */ 92 struct kunit_resource { 93 void *data; 94 const char *name; 95 kunit_resource_free_t free; 96 97 /* private: internal use only. */ 98 struct kref refcount; 99 struct list_head node; 100 }; 101 102 struct kunit; 103 104 /* Size of log associated with test. */ 105 #define KUNIT_LOG_SIZE 512 106 107 /* Maximum size of parameter description string. */ 108 #define KUNIT_PARAM_DESC_SIZE 128 109 110 /* Maximum size of a status comment. */ 111 #define KUNIT_STATUS_COMMENT_SIZE 256 112 113 /* 114 * TAP specifies subtest stream indentation of 4 spaces, 8 spaces for a 115 * sub-subtest. See the "Subtests" section in 116 * https://node-tap.org/tap-protocol/ 117 */ 118 #define KUNIT_SUBTEST_INDENT " " 119 #define KUNIT_SUBSUBTEST_INDENT " " 120 121 /** 122 * enum kunit_status - Type of result for a test or test suite 123 * @KUNIT_SUCCESS: Denotes the test suite has not failed nor been skipped 124 * @KUNIT_FAILURE: Denotes the test has failed. 125 * @KUNIT_SKIPPED: Denotes the test has been skipped. 126 */ 127 enum kunit_status { 128 KUNIT_SUCCESS, 129 KUNIT_FAILURE, 130 KUNIT_SKIPPED, 131 }; 132 133 /** 134 * struct kunit_case - represents an individual test case. 135 * 136 * @run_case: the function representing the actual test case. 137 * @name: the name of the test case. 138 * @generate_params: the generator function for parameterized tests. 139 * 140 * A test case is a function with the signature, 141 * ``void (*)(struct kunit *)`` 142 * that makes expectations and assertions (see KUNIT_EXPECT_TRUE() and 143 * KUNIT_ASSERT_TRUE()) about code under test. Each test case is associated 144 * with a &struct kunit_suite and will be run after the suite's init 145 * function and followed by the suite's exit function. 146 * 147 * A test case should be static and should only be created with the 148 * KUNIT_CASE() macro; additionally, every array of test cases should be 149 * terminated with an empty test case. 150 * 151 * Example: 152 * 153 * .. code-block:: c 154 * 155 * void add_test_basic(struct kunit *test) 156 * { 157 * KUNIT_EXPECT_EQ(test, 1, add(1, 0)); 158 * KUNIT_EXPECT_EQ(test, 2, add(1, 1)); 159 * KUNIT_EXPECT_EQ(test, 0, add(-1, 1)); 160 * KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX)); 161 * KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN)); 162 * } 163 * 164 * static struct kunit_case example_test_cases[] = { 165 * KUNIT_CASE(add_test_basic), 166 * {} 167 * }; 168 * 169 */ 170 struct kunit_case { 171 void (*run_case)(struct kunit *test); 172 const char *name; 173 const void* (*generate_params)(const void *prev, char *desc); 174 175 /* private: internal use only. */ 176 enum kunit_status status; 177 char *log; 178 }; 179 180 static inline char *kunit_status_to_ok_not_ok(enum kunit_status status) 181 { 182 switch (status) { 183 case KUNIT_SKIPPED: 184 case KUNIT_SUCCESS: 185 return "ok"; 186 case KUNIT_FAILURE: 187 return "not ok"; 188 } 189 return "invalid"; 190 } 191 192 /** 193 * KUNIT_CASE - A helper for creating a &struct kunit_case 194 * 195 * @test_name: a reference to a test case function. 196 * 197 * Takes a symbol for a function representing a test case and creates a 198 * &struct kunit_case object from it. See the documentation for 199 * &struct kunit_case for an example on how to use it. 200 */ 201 #define KUNIT_CASE(test_name) { .run_case = test_name, .name = #test_name } 202 203 /** 204 * KUNIT_CASE_PARAM - A helper for creation a parameterized &struct kunit_case 205 * 206 * @test_name: a reference to a test case function. 207 * @gen_params: a reference to a parameter generator function. 208 * 209 * The generator function:: 210 * 211 * const void* gen_params(const void *prev, char *desc) 212 * 213 * is used to lazily generate a series of arbitrarily typed values that fit into 214 * a void*. The argument @prev is the previously returned value, which should be 215 * used to derive the next value; @prev is set to NULL on the initial generator 216 * call. When no more values are available, the generator must return NULL. 217 * Optionally write a string into @desc (size of KUNIT_PARAM_DESC_SIZE) 218 * describing the parameter. 219 */ 220 #define KUNIT_CASE_PARAM(test_name, gen_params) \ 221 { .run_case = test_name, .name = #test_name, \ 222 .generate_params = gen_params } 223 224 /** 225 * struct kunit_suite - describes a related collection of &struct kunit_case 226 * 227 * @name: the name of the test. Purely informational. 228 * @init: called before every test case. 229 * @exit: called after every test case. 230 * @test_cases: a null terminated array of test cases. 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 * Every &struct kunit_case must be associated with a kunit_suite for KUnit 238 * to run it. 239 */ 240 struct kunit_suite { 241 const char name[256]; 242 int (*init)(struct kunit *test); 243 void (*exit)(struct kunit *test); 244 struct kunit_case *test_cases; 245 246 /* private: internal use only */ 247 char status_comment[KUNIT_STATUS_COMMENT_SIZE]; 248 struct dentry *debugfs; 249 char *log; 250 }; 251 252 /** 253 * struct kunit - represents a running instance of a test. 254 * 255 * @priv: for user to store arbitrary data. Commonly used to pass data 256 * created in the init function (see &struct kunit_suite). 257 * 258 * Used to store information about the current context under which the test 259 * is running. Most of this data is private and should only be accessed 260 * indirectly via public functions; the one exception is @priv which can be 261 * used by the test writer to store arbitrary data. 262 */ 263 struct kunit { 264 void *priv; 265 266 /* private: internal use only. */ 267 const char *name; /* Read only after initialization! */ 268 char *log; /* Points at case log after initialization */ 269 struct kunit_try_catch try_catch; 270 /* param_value is the current parameter value for a test case. */ 271 const void *param_value; 272 /* param_index stores the index of the parameter in parameterized tests. */ 273 int param_index; 274 /* 275 * success starts as true, and may only be set to false during a 276 * test case; thus, it is safe to update this across multiple 277 * threads using WRITE_ONCE; however, as a consequence, it may only 278 * be read after the test case finishes once all threads associated 279 * with the test case have terminated. 280 */ 281 spinlock_t lock; /* Guards all mutable test state. */ 282 enum kunit_status status; /* Read only after test_case finishes! */ 283 /* 284 * Because resources is a list that may be updated multiple times (with 285 * new resources) from any thread associated with a test case, we must 286 * protect it with some type of lock. 287 */ 288 struct list_head resources; /* Protected by lock. */ 289 290 char status_comment[KUNIT_STATUS_COMMENT_SIZE]; 291 }; 292 293 static inline void kunit_set_failure(struct kunit *test) 294 { 295 WRITE_ONCE(test->status, KUNIT_FAILURE); 296 } 297 298 void kunit_init_test(struct kunit *test, const char *name, char *log); 299 300 int kunit_run_tests(struct kunit_suite *suite); 301 302 size_t kunit_suite_num_test_cases(struct kunit_suite *suite); 303 304 unsigned int kunit_test_case_num(struct kunit_suite *suite, 305 struct kunit_case *test_case); 306 307 int __kunit_test_suites_init(struct kunit_suite * const * const suites); 308 309 void __kunit_test_suites_exit(struct kunit_suite **suites); 310 311 #if IS_BUILTIN(CONFIG_KUNIT) 312 int kunit_run_all_tests(void); 313 #else 314 static inline int kunit_run_all_tests(void) 315 { 316 return 0; 317 } 318 #endif /* IS_BUILTIN(CONFIG_KUNIT) */ 319 320 #ifdef MODULE 321 /** 322 * kunit_test_suites_for_module() - used to register one or more 323 * &struct kunit_suite with KUnit. 324 * 325 * @__suites: a statically allocated list of &struct kunit_suite. 326 * 327 * Registers @__suites with the test framework. See &struct kunit_suite for 328 * more information. 329 * 330 * If a test suite is built-in, module_init() gets translated into 331 * an initcall which we don't want as the idea is that for builtins 332 * the executor will manage execution. So ensure we do not define 333 * module_{init|exit} functions for the builtin case when registering 334 * suites via kunit_test_suites() below. 335 */ 336 #define kunit_test_suites_for_module(__suites) \ 337 static int __init kunit_test_suites_init(void) \ 338 { \ 339 return __kunit_test_suites_init(__suites); \ 340 } \ 341 module_init(kunit_test_suites_init); \ 342 \ 343 static void __exit kunit_test_suites_exit(void) \ 344 { \ 345 return __kunit_test_suites_exit(__suites); \ 346 } \ 347 module_exit(kunit_test_suites_exit) 348 #else 349 #define kunit_test_suites_for_module(__suites) 350 #endif /* MODULE */ 351 352 #define __kunit_test_suites(unique_array, unique_suites, ...) \ 353 static struct kunit_suite *unique_array[] = { __VA_ARGS__, NULL }; \ 354 kunit_test_suites_for_module(unique_array); \ 355 static struct kunit_suite **unique_suites \ 356 __used __section(".kunit_test_suites") = unique_array 357 358 /** 359 * kunit_test_suites() - used to register one or more &struct kunit_suite 360 * with KUnit. 361 * 362 * @__suites: a statically allocated list of &struct kunit_suite. 363 * 364 * Registers @suites with the test framework. See &struct kunit_suite for 365 * more information. 366 * 367 * When builtin, KUnit tests are all run via executor; this is done 368 * by placing the array of struct kunit_suite * in the .kunit_test_suites 369 * ELF section. 370 * 371 * An alternative is to build the tests as a module. Because modules do not 372 * support multiple initcall()s, we need to initialize an array of suites for a 373 * module. 374 * 375 */ 376 #define kunit_test_suites(__suites...) \ 377 __kunit_test_suites(__UNIQUE_ID(array), \ 378 __UNIQUE_ID(suites), \ 379 ##__suites) 380 381 #define kunit_test_suite(suite) kunit_test_suites(&suite) 382 383 #define kunit_suite_for_each_test_case(suite, test_case) \ 384 for (test_case = suite->test_cases; test_case->run_case; test_case++) 385 386 enum kunit_status kunit_suite_has_succeeded(struct kunit_suite *suite); 387 388 /* 389 * Like kunit_alloc_resource() below, but returns the struct kunit_resource 390 * object that contains the allocation. This is mostly for testing purposes. 391 */ 392 struct kunit_resource *kunit_alloc_and_get_resource(struct kunit *test, 393 kunit_resource_init_t init, 394 kunit_resource_free_t free, 395 gfp_t internal_gfp, 396 void *context); 397 398 /** 399 * kunit_get_resource() - Hold resource for use. Should not need to be used 400 * by most users as we automatically get resources 401 * retrieved by kunit_find_resource*(). 402 * @res: resource 403 */ 404 static inline void kunit_get_resource(struct kunit_resource *res) 405 { 406 kref_get(&res->refcount); 407 } 408 409 /* 410 * Called when refcount reaches zero via kunit_put_resources(); 411 * should not be called directly. 412 */ 413 static inline void kunit_release_resource(struct kref *kref) 414 { 415 struct kunit_resource *res = container_of(kref, struct kunit_resource, 416 refcount); 417 418 /* If free function is defined, resource was dynamically allocated. */ 419 if (res->free) { 420 res->free(res); 421 kfree(res); 422 } 423 } 424 425 /** 426 * kunit_put_resource() - When caller is done with retrieved resource, 427 * kunit_put_resource() should be called to drop 428 * reference count. The resource list maintains 429 * a reference count on resources, so if no users 430 * are utilizing a resource and it is removed from 431 * the resource list, it will be freed via the 432 * associated free function (if any). Only 433 * needs to be used if we alloc_and_get() or 434 * find() resource. 435 * @res: resource 436 */ 437 static inline void kunit_put_resource(struct kunit_resource *res) 438 { 439 kref_put(&res->refcount, kunit_release_resource); 440 } 441 442 /** 443 * kunit_add_resource() - Add a *test managed resource*. 444 * @test: The test context object. 445 * @init: a user-supplied function to initialize the result (if needed). If 446 * none is supplied, the resource data value is simply set to @data. 447 * If an init function is supplied, @data is passed to it instead. 448 * @free: a user-supplied function to free the resource (if needed). 449 * @res: The resource. 450 * @data: value to pass to init function or set in resource data field. 451 */ 452 int kunit_add_resource(struct kunit *test, 453 kunit_resource_init_t init, 454 kunit_resource_free_t free, 455 struct kunit_resource *res, 456 void *data); 457 458 /** 459 * kunit_add_named_resource() - Add a named *test managed resource*. 460 * @test: The test context object. 461 * @init: a user-supplied function to initialize the resource data, if needed. 462 * @free: a user-supplied function to free the resource data, if needed. 463 * @res: The resource. 464 * @name: name to be set for resource. 465 * @data: value to pass to init function or set in resource data field. 466 */ 467 int kunit_add_named_resource(struct kunit *test, 468 kunit_resource_init_t init, 469 kunit_resource_free_t free, 470 struct kunit_resource *res, 471 const char *name, 472 void *data); 473 474 /** 475 * kunit_alloc_resource() - Allocates a *test managed resource*. 476 * @test: The test context object. 477 * @init: a user supplied function to initialize the resource. 478 * @free: a user supplied function to free the resource. 479 * @internal_gfp: gfp to use for internal allocations, if unsure, use GFP_KERNEL 480 * @context: for the user to pass in arbitrary data to the init function. 481 * 482 * Allocates a *test managed resource*, a resource which will automatically be 483 * cleaned up at the end of a test case. See &struct kunit_resource for an 484 * example. 485 * 486 * Note: KUnit needs to allocate memory for a kunit_resource object. You must 487 * specify an @internal_gfp that is compatible with the use context of your 488 * resource. 489 */ 490 static inline void *kunit_alloc_resource(struct kunit *test, 491 kunit_resource_init_t init, 492 kunit_resource_free_t free, 493 gfp_t internal_gfp, 494 void *context) 495 { 496 struct kunit_resource *res; 497 498 res = kzalloc(sizeof(*res), internal_gfp); 499 if (!res) 500 return NULL; 501 502 if (!kunit_add_resource(test, init, free, res, context)) 503 return res->data; 504 505 return NULL; 506 } 507 508 typedef bool (*kunit_resource_match_t)(struct kunit *test, 509 struct kunit_resource *res, 510 void *match_data); 511 512 /** 513 * kunit_resource_instance_match() - Match a resource with the same instance. 514 * @test: Test case to which the resource belongs. 515 * @res: The resource. 516 * @match_data: The resource pointer to match against. 517 * 518 * An instance of kunit_resource_match_t that matches a resource whose 519 * allocation matches @match_data. 520 */ 521 static inline bool kunit_resource_instance_match(struct kunit *test, 522 struct kunit_resource *res, 523 void *match_data) 524 { 525 return res->data == match_data; 526 } 527 528 /** 529 * kunit_resource_name_match() - Match a resource with the same name. 530 * @test: Test case to which the resource belongs. 531 * @res: The resource. 532 * @match_name: The name to match against. 533 */ 534 static inline bool kunit_resource_name_match(struct kunit *test, 535 struct kunit_resource *res, 536 void *match_name) 537 { 538 return res->name && strcmp(res->name, match_name) == 0; 539 } 540 541 /** 542 * kunit_find_resource() - Find a resource using match function/data. 543 * @test: Test case to which the resource belongs. 544 * @match: match function to be applied to resources/match data. 545 * @match_data: data to be used in matching. 546 */ 547 static inline struct kunit_resource * 548 kunit_find_resource(struct kunit *test, 549 kunit_resource_match_t match, 550 void *match_data) 551 { 552 struct kunit_resource *res, *found = NULL; 553 unsigned long flags; 554 555 spin_lock_irqsave(&test->lock, flags); 556 557 list_for_each_entry_reverse(res, &test->resources, node) { 558 if (match(test, res, (void *)match_data)) { 559 found = res; 560 kunit_get_resource(found); 561 break; 562 } 563 } 564 565 spin_unlock_irqrestore(&test->lock, flags); 566 567 return found; 568 } 569 570 /** 571 * kunit_find_named_resource() - Find a resource using match name. 572 * @test: Test case to which the resource belongs. 573 * @name: match name. 574 */ 575 static inline struct kunit_resource * 576 kunit_find_named_resource(struct kunit *test, 577 const char *name) 578 { 579 return kunit_find_resource(test, kunit_resource_name_match, 580 (void *)name); 581 } 582 583 /** 584 * kunit_destroy_resource() - Find a kunit_resource and destroy it. 585 * @test: Test case to which the resource belongs. 586 * @match: Match function. Returns whether a given resource matches @match_data. 587 * @match_data: Data passed into @match. 588 * 589 * RETURNS: 590 * 0 if kunit_resource is found and freed, -ENOENT if not found. 591 */ 592 int kunit_destroy_resource(struct kunit *test, 593 kunit_resource_match_t match, 594 void *match_data); 595 596 static inline int kunit_destroy_named_resource(struct kunit *test, 597 const char *name) 598 { 599 return kunit_destroy_resource(test, kunit_resource_name_match, 600 (void *)name); 601 } 602 603 /** 604 * kunit_remove_resource() - remove resource from resource list associated with 605 * test. 606 * @test: The test context object. 607 * @res: The resource to be removed. 608 * 609 * Note that the resource will not be immediately freed since it is likely 610 * the caller has a reference to it via alloc_and_get() or find(); 611 * in this case a final call to kunit_put_resource() is required. 612 */ 613 void kunit_remove_resource(struct kunit *test, struct kunit_resource *res); 614 615 /** 616 * kunit_kmalloc_array() - Like kmalloc_array() except the allocation is *test managed*. 617 * @test: The test context object. 618 * @n: number of elements. 619 * @size: The size in bytes of the desired memory. 620 * @gfp: flags passed to underlying kmalloc(). 621 * 622 * Just like `kmalloc_array(...)`, except the allocation is managed by the test case 623 * and is automatically cleaned up after the test case concludes. See &struct 624 * kunit_resource for more information. 625 */ 626 void *kunit_kmalloc_array(struct kunit *test, size_t n, size_t size, gfp_t gfp); 627 628 /** 629 * kunit_kmalloc() - Like kmalloc() except the allocation is *test managed*. 630 * @test: The test context object. 631 * @size: The size in bytes of the desired memory. 632 * @gfp: flags passed to underlying kmalloc(). 633 * 634 * See kmalloc() and kunit_kmalloc_array() for more information. 635 */ 636 static inline void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp) 637 { 638 return kunit_kmalloc_array(test, 1, size, gfp); 639 } 640 641 /** 642 * kunit_kfree() - Like kfree except for allocations managed by KUnit. 643 * @test: The test case to which the resource belongs. 644 * @ptr: The memory allocation to free. 645 */ 646 void kunit_kfree(struct kunit *test, const void *ptr); 647 648 /** 649 * kunit_kzalloc() - Just like kunit_kmalloc(), but zeroes the allocation. 650 * @test: The test context object. 651 * @size: The size in bytes of the desired memory. 652 * @gfp: flags passed to underlying kmalloc(). 653 * 654 * See kzalloc() and kunit_kmalloc_array() for more information. 655 */ 656 static inline void *kunit_kzalloc(struct kunit *test, size_t size, gfp_t gfp) 657 { 658 return kunit_kmalloc(test, size, gfp | __GFP_ZERO); 659 } 660 661 /** 662 * kunit_kcalloc() - Just like kunit_kmalloc_array(), but zeroes the allocation. 663 * @test: The test context object. 664 * @n: number of elements. 665 * @size: The size in bytes of the desired memory. 666 * @gfp: flags passed to underlying kmalloc(). 667 * 668 * See kcalloc() and kunit_kmalloc_array() for more information. 669 */ 670 static inline void *kunit_kcalloc(struct kunit *test, size_t n, size_t size, gfp_t gfp) 671 { 672 return kunit_kmalloc_array(test, n, size, gfp | __GFP_ZERO); 673 } 674 675 void kunit_cleanup(struct kunit *test); 676 677 void __printf(2, 3) kunit_log_append(char *log, const char *fmt, ...); 678 679 /** 680 * kunit_mark_skipped() - Marks @test_or_suite as skipped 681 * 682 * @test_or_suite: The test context object. 683 * @fmt: A printk() style format string. 684 * 685 * Marks the test as skipped. @fmt is given output as the test status 686 * comment, typically the reason the test was skipped. 687 * 688 * Test execution continues after kunit_mark_skipped() is called. 689 */ 690 #define kunit_mark_skipped(test_or_suite, fmt, ...) \ 691 do { \ 692 WRITE_ONCE((test_or_suite)->status, KUNIT_SKIPPED); \ 693 scnprintf((test_or_suite)->status_comment, \ 694 KUNIT_STATUS_COMMENT_SIZE, \ 695 fmt, ##__VA_ARGS__); \ 696 } while (0) 697 698 /** 699 * kunit_skip() - Marks @test_or_suite as skipped 700 * 701 * @test_or_suite: The test context object. 702 * @fmt: A printk() style format string. 703 * 704 * Skips the test. @fmt is given output as the test status 705 * comment, typically the reason the test was skipped. 706 * 707 * Test execution is halted after kunit_skip() is called. 708 */ 709 #define kunit_skip(test_or_suite, fmt, ...) \ 710 do { \ 711 kunit_mark_skipped((test_or_suite), fmt, ##__VA_ARGS__);\ 712 kunit_try_catch_throw(&((test_or_suite)->try_catch)); \ 713 } while (0) 714 715 /* 716 * printk and log to per-test or per-suite log buffer. Logging only done 717 * if CONFIG_KUNIT_DEBUGFS is 'y'; if it is 'n', no log is allocated/used. 718 */ 719 #define kunit_log(lvl, test_or_suite, fmt, ...) \ 720 do { \ 721 printk(lvl fmt, ##__VA_ARGS__); \ 722 kunit_log_append((test_or_suite)->log, fmt "\n", \ 723 ##__VA_ARGS__); \ 724 } while (0) 725 726 #define kunit_printk(lvl, test, fmt, ...) \ 727 kunit_log(lvl, test, KUNIT_SUBTEST_INDENT "# %s: " fmt, \ 728 (test)->name, ##__VA_ARGS__) 729 730 /** 731 * kunit_info() - Prints an INFO level message associated with @test. 732 * 733 * @test: The test context object. 734 * @fmt: A printk() style format string. 735 * 736 * Prints an info level message associated with the test suite being run. 737 * Takes a variable number of format parameters just like printk(). 738 */ 739 #define kunit_info(test, fmt, ...) \ 740 kunit_printk(KERN_INFO, test, fmt, ##__VA_ARGS__) 741 742 /** 743 * kunit_warn() - Prints a WARN level message associated with @test. 744 * 745 * @test: The test context object. 746 * @fmt: A printk() style format string. 747 * 748 * Prints a warning level message. 749 */ 750 #define kunit_warn(test, fmt, ...) \ 751 kunit_printk(KERN_WARNING, test, fmt, ##__VA_ARGS__) 752 753 /** 754 * kunit_err() - Prints an ERROR level message associated with @test. 755 * 756 * @test: The test context object. 757 * @fmt: A printk() style format string. 758 * 759 * Prints an error level message. 760 */ 761 #define kunit_err(test, fmt, ...) \ 762 kunit_printk(KERN_ERR, test, fmt, ##__VA_ARGS__) 763 764 /** 765 * KUNIT_SUCCEED() - A no-op expectation. Only exists for code clarity. 766 * @test: The test context object. 767 * 768 * The opposite of KUNIT_FAIL(), it is an expectation that cannot fail. In other 769 * words, it does nothing and only exists for code clarity. See 770 * KUNIT_EXPECT_TRUE() for more information. 771 */ 772 #define KUNIT_SUCCEED(test) do {} while (0) 773 774 void kunit_do_failed_assertion(struct kunit *test, 775 const struct kunit_loc *loc, 776 enum kunit_assert_type type, 777 struct kunit_assert *assert, 778 const char *fmt, ...); 779 780 #define KUNIT_ASSERTION(test, assert_type, pass, assert_class, INITIALIZER, fmt, ...) do { \ 781 if (unlikely(!(pass))) { \ 782 static const struct kunit_loc __loc = KUNIT_CURRENT_LOC; \ 783 struct assert_class __assertion = INITIALIZER; \ 784 kunit_do_failed_assertion(test, \ 785 &__loc, \ 786 assert_type, \ 787 &__assertion.assert, \ 788 fmt, \ 789 ##__VA_ARGS__); \ 790 } \ 791 } while (0) 792 793 794 #define KUNIT_FAIL_ASSERTION(test, assert_type, fmt, ...) \ 795 KUNIT_ASSERTION(test, \ 796 assert_type, \ 797 false, \ 798 kunit_fail_assert, \ 799 KUNIT_INIT_FAIL_ASSERT_STRUCT, \ 800 fmt, \ 801 ##__VA_ARGS__) 802 803 /** 804 * KUNIT_FAIL() - Always causes a test to fail when evaluated. 805 * @test: The test context object. 806 * @fmt: an informational message to be printed when the assertion is made. 807 * @...: string format arguments. 808 * 809 * The opposite of KUNIT_SUCCEED(), it is an expectation that always fails. In 810 * other words, it always results in a failed expectation, and consequently 811 * always causes the test case to fail when evaluated. See KUNIT_EXPECT_TRUE() 812 * for more information. 813 */ 814 #define KUNIT_FAIL(test, fmt, ...) \ 815 KUNIT_FAIL_ASSERTION(test, \ 816 KUNIT_EXPECTATION, \ 817 fmt, \ 818 ##__VA_ARGS__) 819 820 #define KUNIT_UNARY_ASSERTION(test, \ 821 assert_type, \ 822 condition, \ 823 expected_true, \ 824 fmt, \ 825 ...) \ 826 KUNIT_ASSERTION(test, \ 827 assert_type, \ 828 !!(condition) == !!expected_true, \ 829 kunit_unary_assert, \ 830 KUNIT_INIT_UNARY_ASSERT_STRUCT(#condition, \ 831 expected_true), \ 832 fmt, \ 833 ##__VA_ARGS__) 834 835 #define KUNIT_TRUE_MSG_ASSERTION(test, assert_type, condition, fmt, ...) \ 836 KUNIT_UNARY_ASSERTION(test, \ 837 assert_type, \ 838 condition, \ 839 true, \ 840 fmt, \ 841 ##__VA_ARGS__) 842 843 #define KUNIT_FALSE_MSG_ASSERTION(test, assert_type, condition, fmt, ...) \ 844 KUNIT_UNARY_ASSERTION(test, \ 845 assert_type, \ 846 condition, \ 847 false, \ 848 fmt, \ 849 ##__VA_ARGS__) 850 851 /* 852 * A factory macro for defining the assertions and expectations for the basic 853 * comparisons defined for the built in types. 854 * 855 * Unfortunately, there is no common type that all types can be promoted to for 856 * which all the binary operators behave the same way as for the actual types 857 * (for example, there is no type that long long and unsigned long long can 858 * both be cast to where the comparison result is preserved for all values). So 859 * the best we can do is do the comparison in the original types and then coerce 860 * everything to long long for printing; this way, the comparison behaves 861 * correctly and the printed out value usually makes sense without 862 * interpretation, but can always be interpreted to figure out the actual 863 * value. 864 */ 865 #define KUNIT_BASE_BINARY_ASSERTION(test, \ 866 assert_class, \ 867 format_func, \ 868 assert_type, \ 869 left, \ 870 op, \ 871 right, \ 872 fmt, \ 873 ...) \ 874 do { \ 875 const typeof(left) __left = (left); \ 876 const typeof(right) __right = (right); \ 877 static const struct kunit_binary_assert_text __text = { \ 878 .operation = #op, \ 879 .left_text = #left, \ 880 .right_text = #right, \ 881 }; \ 882 \ 883 KUNIT_ASSERTION(test, \ 884 assert_type, \ 885 __left op __right, \ 886 assert_class, \ 887 KUNIT_INIT_BINARY_ASSERT_STRUCT(format_func, \ 888 &__text, \ 889 __left, \ 890 __right), \ 891 fmt, \ 892 ##__VA_ARGS__); \ 893 } while (0) 894 895 #define KUNIT_BINARY_INT_ASSERTION(test, \ 896 assert_type, \ 897 left, \ 898 op, \ 899 right, \ 900 fmt, \ 901 ...) \ 902 KUNIT_BASE_BINARY_ASSERTION(test, \ 903 kunit_binary_assert, \ 904 kunit_binary_assert_format, \ 905 assert_type, \ 906 left, op, right, \ 907 fmt, \ 908 ##__VA_ARGS__) 909 910 #define KUNIT_BINARY_PTR_ASSERTION(test, \ 911 assert_type, \ 912 left, \ 913 op, \ 914 right, \ 915 fmt, \ 916 ...) \ 917 KUNIT_BASE_BINARY_ASSERTION(test, \ 918 kunit_binary_ptr_assert, \ 919 kunit_binary_ptr_assert_format, \ 920 assert_type, \ 921 left, op, right, \ 922 fmt, \ 923 ##__VA_ARGS__) 924 925 #define KUNIT_BINARY_STR_ASSERTION(test, \ 926 assert_type, \ 927 left, \ 928 op, \ 929 right, \ 930 fmt, \ 931 ...) \ 932 do { \ 933 const char *__left = (left); \ 934 const char *__right = (right); \ 935 static const struct kunit_binary_assert_text __text = { \ 936 .operation = #op, \ 937 .left_text = #left, \ 938 .right_text = #right, \ 939 }; \ 940 \ 941 KUNIT_ASSERTION(test, \ 942 assert_type, \ 943 strcmp(__left, __right) op 0, \ 944 kunit_binary_str_assert, \ 945 KUNIT_INIT_BINARY_ASSERT_STRUCT(kunit_binary_str_assert_format,\ 946 &__text, \ 947 __left, \ 948 __right), \ 949 fmt, \ 950 ##__VA_ARGS__); \ 951 } while (0) 952 953 #define KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 954 assert_type, \ 955 ptr, \ 956 fmt, \ 957 ...) \ 958 do { \ 959 const typeof(ptr) __ptr = (ptr); \ 960 \ 961 KUNIT_ASSERTION(test, \ 962 assert_type, \ 963 !IS_ERR_OR_NULL(__ptr), \ 964 kunit_ptr_not_err_assert, \ 965 KUNIT_INIT_PTR_NOT_ERR_STRUCT(#ptr, \ 966 __ptr), \ 967 fmt, \ 968 ##__VA_ARGS__); \ 969 } while (0) 970 971 /** 972 * KUNIT_EXPECT_TRUE() - Causes a test failure when the expression is not true. 973 * @test: The test context object. 974 * @condition: an arbitrary boolean expression. The test fails when this does 975 * not evaluate to true. 976 * 977 * This and expectations of the form `KUNIT_EXPECT_*` will cause the test case 978 * to fail when the specified condition is not met; however, it will not prevent 979 * the test case from continuing to run; this is otherwise known as an 980 * *expectation failure*. 981 */ 982 #define KUNIT_EXPECT_TRUE(test, condition) \ 983 KUNIT_EXPECT_TRUE_MSG(test, condition, NULL) 984 985 #define KUNIT_EXPECT_TRUE_MSG(test, condition, fmt, ...) \ 986 KUNIT_TRUE_MSG_ASSERTION(test, \ 987 KUNIT_EXPECTATION, \ 988 condition, \ 989 fmt, \ 990 ##__VA_ARGS__) 991 992 /** 993 * KUNIT_EXPECT_FALSE() - Makes a test failure when the expression is not false. 994 * @test: The test context object. 995 * @condition: an arbitrary boolean expression. The test fails when this does 996 * not evaluate to false. 997 * 998 * Sets an expectation that @condition evaluates to false. See 999 * KUNIT_EXPECT_TRUE() for more information. 1000 */ 1001 #define KUNIT_EXPECT_FALSE(test, condition) \ 1002 KUNIT_EXPECT_FALSE_MSG(test, condition, NULL) 1003 1004 #define KUNIT_EXPECT_FALSE_MSG(test, condition, fmt, ...) \ 1005 KUNIT_FALSE_MSG_ASSERTION(test, \ 1006 KUNIT_EXPECTATION, \ 1007 condition, \ 1008 fmt, \ 1009 ##__VA_ARGS__) 1010 1011 /** 1012 * KUNIT_EXPECT_EQ() - Sets an expectation that @left and @right are equal. 1013 * @test: The test context object. 1014 * @left: an arbitrary expression that evaluates to a primitive C type. 1015 * @right: an arbitrary expression that evaluates to a primitive C type. 1016 * 1017 * Sets an expectation that the values that @left and @right evaluate to are 1018 * equal. This is semantically equivalent to 1019 * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for 1020 * more information. 1021 */ 1022 #define KUNIT_EXPECT_EQ(test, left, right) \ 1023 KUNIT_EXPECT_EQ_MSG(test, left, right, NULL) 1024 1025 #define KUNIT_EXPECT_EQ_MSG(test, left, right, fmt, ...) \ 1026 KUNIT_BINARY_INT_ASSERTION(test, \ 1027 KUNIT_EXPECTATION, \ 1028 left, ==, right, \ 1029 fmt, \ 1030 ##__VA_ARGS__) 1031 1032 /** 1033 * KUNIT_EXPECT_PTR_EQ() - Expects that pointers @left and @right are equal. 1034 * @test: The test context object. 1035 * @left: an arbitrary expression that evaluates to a pointer. 1036 * @right: an arbitrary expression that evaluates to a pointer. 1037 * 1038 * Sets an expectation that the values that @left and @right evaluate to are 1039 * equal. This is semantically equivalent to 1040 * KUNIT_EXPECT_TRUE(@test, (@left) == (@right)). See KUNIT_EXPECT_TRUE() for 1041 * more information. 1042 */ 1043 #define KUNIT_EXPECT_PTR_EQ(test, left, right) \ 1044 KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, NULL) 1045 1046 #define KUNIT_EXPECT_PTR_EQ_MSG(test, left, right, fmt, ...) \ 1047 KUNIT_BINARY_PTR_ASSERTION(test, \ 1048 KUNIT_EXPECTATION, \ 1049 left, ==, right, \ 1050 fmt, \ 1051 ##__VA_ARGS__) 1052 1053 /** 1054 * KUNIT_EXPECT_NE() - An expectation that @left and @right are not equal. 1055 * @test: The test context object. 1056 * @left: an arbitrary expression that evaluates to a primitive C type. 1057 * @right: an arbitrary expression that evaluates to a primitive C type. 1058 * 1059 * Sets an expectation that the values that @left and @right evaluate to are not 1060 * equal. This is semantically equivalent to 1061 * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for 1062 * more information. 1063 */ 1064 #define KUNIT_EXPECT_NE(test, left, right) \ 1065 KUNIT_EXPECT_NE_MSG(test, left, right, NULL) 1066 1067 #define KUNIT_EXPECT_NE_MSG(test, left, right, fmt, ...) \ 1068 KUNIT_BINARY_INT_ASSERTION(test, \ 1069 KUNIT_EXPECTATION, \ 1070 left, !=, right, \ 1071 fmt, \ 1072 ##__VA_ARGS__) 1073 1074 /** 1075 * KUNIT_EXPECT_PTR_NE() - Expects that pointers @left and @right are not equal. 1076 * @test: The test context object. 1077 * @left: an arbitrary expression that evaluates to a pointer. 1078 * @right: an arbitrary expression that evaluates to a pointer. 1079 * 1080 * Sets an expectation that the values that @left and @right evaluate to are not 1081 * equal. This is semantically equivalent to 1082 * KUNIT_EXPECT_TRUE(@test, (@left) != (@right)). See KUNIT_EXPECT_TRUE() for 1083 * more information. 1084 */ 1085 #define KUNIT_EXPECT_PTR_NE(test, left, right) \ 1086 KUNIT_EXPECT_PTR_NE_MSG(test, left, right, NULL) 1087 1088 #define KUNIT_EXPECT_PTR_NE_MSG(test, left, right, fmt, ...) \ 1089 KUNIT_BINARY_PTR_ASSERTION(test, \ 1090 KUNIT_EXPECTATION, \ 1091 left, !=, right, \ 1092 fmt, \ 1093 ##__VA_ARGS__) 1094 1095 /** 1096 * KUNIT_EXPECT_LT() - An expectation that @left is less than @right. 1097 * @test: The test context object. 1098 * @left: an arbitrary expression that evaluates to a primitive C type. 1099 * @right: an arbitrary expression that evaluates to a primitive C type. 1100 * 1101 * Sets an expectation that the value that @left evaluates to is less than the 1102 * value that @right evaluates to. This is semantically equivalent to 1103 * KUNIT_EXPECT_TRUE(@test, (@left) < (@right)). See KUNIT_EXPECT_TRUE() for 1104 * more information. 1105 */ 1106 #define KUNIT_EXPECT_LT(test, left, right) \ 1107 KUNIT_EXPECT_LT_MSG(test, left, right, NULL) 1108 1109 #define KUNIT_EXPECT_LT_MSG(test, left, right, fmt, ...) \ 1110 KUNIT_BINARY_INT_ASSERTION(test, \ 1111 KUNIT_EXPECTATION, \ 1112 left, <, right, \ 1113 fmt, \ 1114 ##__VA_ARGS__) 1115 1116 /** 1117 * KUNIT_EXPECT_LE() - Expects that @left is less than or equal to @right. 1118 * @test: The test context object. 1119 * @left: an arbitrary expression that evaluates to a primitive C type. 1120 * @right: an arbitrary expression that evaluates to a primitive C type. 1121 * 1122 * Sets an expectation that the value that @left evaluates to is less than or 1123 * equal to the value that @right evaluates to. Semantically this is equivalent 1124 * to KUNIT_EXPECT_TRUE(@test, (@left) <= (@right)). See KUNIT_EXPECT_TRUE() for 1125 * more information. 1126 */ 1127 #define KUNIT_EXPECT_LE(test, left, right) \ 1128 KUNIT_EXPECT_LE_MSG(test, left, right, NULL) 1129 1130 #define KUNIT_EXPECT_LE_MSG(test, left, right, fmt, ...) \ 1131 KUNIT_BINARY_INT_ASSERTION(test, \ 1132 KUNIT_ASSERTION, \ 1133 left, <=, right, \ 1134 fmt, \ 1135 ##__VA_ARGS__) 1136 1137 /** 1138 * KUNIT_EXPECT_GT() - An expectation that @left is greater than @right. 1139 * @test: The test context object. 1140 * @left: an arbitrary expression that evaluates to a primitive C type. 1141 * @right: an arbitrary expression that evaluates to a primitive C type. 1142 * 1143 * Sets an expectation that the value that @left evaluates to is greater than 1144 * the value that @right evaluates to. This is semantically equivalent to 1145 * KUNIT_EXPECT_TRUE(@test, (@left) > (@right)). See KUNIT_EXPECT_TRUE() for 1146 * more information. 1147 */ 1148 #define KUNIT_EXPECT_GT(test, left, right) \ 1149 KUNIT_EXPECT_GT_MSG(test, left, right, NULL) 1150 1151 #define KUNIT_EXPECT_GT_MSG(test, left, right, fmt, ...) \ 1152 KUNIT_BINARY_INT_ASSERTION(test, \ 1153 KUNIT_EXPECTATION, \ 1154 left, >, right, \ 1155 fmt, \ 1156 ##__VA_ARGS__) 1157 1158 /** 1159 * KUNIT_EXPECT_GE() - Expects that @left is greater than or equal to @right. 1160 * @test: The test context object. 1161 * @left: an arbitrary expression that evaluates to a primitive C type. 1162 * @right: an arbitrary expression that evaluates to a primitive C type. 1163 * 1164 * Sets an expectation that the value that @left evaluates to is greater than 1165 * the value that @right evaluates to. This is semantically equivalent to 1166 * KUNIT_EXPECT_TRUE(@test, (@left) >= (@right)). See KUNIT_EXPECT_TRUE() for 1167 * more information. 1168 */ 1169 #define KUNIT_EXPECT_GE(test, left, right) \ 1170 KUNIT_EXPECT_GE_MSG(test, left, right, NULL) 1171 1172 #define KUNIT_EXPECT_GE_MSG(test, left, right, fmt, ...) \ 1173 KUNIT_BINARY_INT_ASSERTION(test, \ 1174 KUNIT_EXPECTATION, \ 1175 left, >=, right, \ 1176 fmt, \ 1177 ##__VA_ARGS__) 1178 1179 /** 1180 * KUNIT_EXPECT_STREQ() - Expects that strings @left and @right are equal. 1181 * @test: The test context object. 1182 * @left: an arbitrary expression that evaluates to a null terminated string. 1183 * @right: an arbitrary expression that evaluates to a null terminated string. 1184 * 1185 * Sets an expectation that the values that @left and @right evaluate to are 1186 * equal. This is semantically equivalent to 1187 * KUNIT_EXPECT_TRUE(@test, !strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE() 1188 * for more information. 1189 */ 1190 #define KUNIT_EXPECT_STREQ(test, left, right) \ 1191 KUNIT_EXPECT_STREQ_MSG(test, left, right, NULL) 1192 1193 #define KUNIT_EXPECT_STREQ_MSG(test, left, right, fmt, ...) \ 1194 KUNIT_BINARY_STR_ASSERTION(test, \ 1195 KUNIT_EXPECTATION, \ 1196 left, ==, right, \ 1197 fmt, \ 1198 ##__VA_ARGS__) 1199 1200 /** 1201 * KUNIT_EXPECT_STRNEQ() - Expects that strings @left and @right are not equal. 1202 * @test: The test context object. 1203 * @left: an arbitrary expression that evaluates to a null terminated string. 1204 * @right: an arbitrary expression that evaluates to a null terminated string. 1205 * 1206 * Sets an expectation that the values that @left and @right evaluate to are 1207 * not equal. This is semantically equivalent to 1208 * KUNIT_EXPECT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_EXPECT_TRUE() 1209 * for more information. 1210 */ 1211 #define KUNIT_EXPECT_STRNEQ(test, left, right) \ 1212 KUNIT_EXPECT_STRNEQ_MSG(test, left, right, NULL) 1213 1214 #define KUNIT_EXPECT_STRNEQ_MSG(test, left, right, fmt, ...) \ 1215 KUNIT_BINARY_STR_ASSERTION(test, \ 1216 KUNIT_EXPECTATION, \ 1217 left, !=, right, \ 1218 fmt, \ 1219 ##__VA_ARGS__) 1220 1221 /** 1222 * KUNIT_EXPECT_NOT_ERR_OR_NULL() - Expects that @ptr is not null and not err. 1223 * @test: The test context object. 1224 * @ptr: an arbitrary pointer. 1225 * 1226 * Sets an expectation that the value that @ptr evaluates to is not null and not 1227 * an errno stored in a pointer. This is semantically equivalent to 1228 * KUNIT_EXPECT_TRUE(@test, !IS_ERR_OR_NULL(@ptr)). See KUNIT_EXPECT_TRUE() for 1229 * more information. 1230 */ 1231 #define KUNIT_EXPECT_NOT_ERR_OR_NULL(test, ptr) \ 1232 KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL) 1233 1234 #define KUNIT_EXPECT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...) \ 1235 KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 1236 KUNIT_EXPECTATION, \ 1237 ptr, \ 1238 fmt, \ 1239 ##__VA_ARGS__) 1240 1241 #define KUNIT_ASSERT_FAILURE(test, fmt, ...) \ 1242 KUNIT_FAIL_ASSERTION(test, KUNIT_ASSERTION, fmt, ##__VA_ARGS__) 1243 1244 /** 1245 * KUNIT_ASSERT_TRUE() - Sets an assertion that @condition is true. 1246 * @test: The test context object. 1247 * @condition: an arbitrary boolean expression. The test fails and aborts when 1248 * this does not evaluate to true. 1249 * 1250 * This and assertions of the form `KUNIT_ASSERT_*` will cause the test case to 1251 * fail *and immediately abort* when the specified condition is not met. Unlike 1252 * an expectation failure, it will prevent the test case from continuing to run; 1253 * this is otherwise known as an *assertion failure*. 1254 */ 1255 #define KUNIT_ASSERT_TRUE(test, condition) \ 1256 KUNIT_ASSERT_TRUE_MSG(test, condition, NULL) 1257 1258 #define KUNIT_ASSERT_TRUE_MSG(test, condition, fmt, ...) \ 1259 KUNIT_TRUE_MSG_ASSERTION(test, \ 1260 KUNIT_ASSERTION, \ 1261 condition, \ 1262 fmt, \ 1263 ##__VA_ARGS__) 1264 1265 /** 1266 * KUNIT_ASSERT_FALSE() - Sets an assertion that @condition is false. 1267 * @test: The test context object. 1268 * @condition: an arbitrary boolean expression. 1269 * 1270 * Sets an assertion that the value that @condition evaluates to is false. This 1271 * is the same as KUNIT_EXPECT_FALSE(), except it causes an assertion failure 1272 * (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1273 */ 1274 #define KUNIT_ASSERT_FALSE(test, condition) \ 1275 KUNIT_ASSERT_FALSE_MSG(test, condition, NULL) 1276 1277 #define KUNIT_ASSERT_FALSE_MSG(test, condition, fmt, ...) \ 1278 KUNIT_FALSE_MSG_ASSERTION(test, \ 1279 KUNIT_ASSERTION, \ 1280 condition, \ 1281 fmt, \ 1282 ##__VA_ARGS__) 1283 1284 /** 1285 * KUNIT_ASSERT_EQ() - Sets an assertion that @left and @right are equal. 1286 * @test: The test context object. 1287 * @left: an arbitrary expression that evaluates to a primitive C type. 1288 * @right: an arbitrary expression that evaluates to a primitive C type. 1289 * 1290 * Sets an assertion that the values that @left and @right evaluate to are 1291 * equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion 1292 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1293 */ 1294 #define KUNIT_ASSERT_EQ(test, left, right) \ 1295 KUNIT_ASSERT_EQ_MSG(test, left, right, NULL) 1296 1297 #define KUNIT_ASSERT_EQ_MSG(test, left, right, fmt, ...) \ 1298 KUNIT_BINARY_INT_ASSERTION(test, \ 1299 KUNIT_ASSERTION, \ 1300 left, ==, right, \ 1301 fmt, \ 1302 ##__VA_ARGS__) 1303 1304 /** 1305 * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal. 1306 * @test: The test context object. 1307 * @left: an arbitrary expression that evaluates to a pointer. 1308 * @right: an arbitrary expression that evaluates to a pointer. 1309 * 1310 * Sets an assertion that the values that @left and @right evaluate to are 1311 * equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion 1312 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1313 */ 1314 #define KUNIT_ASSERT_PTR_EQ(test, left, right) \ 1315 KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, NULL) 1316 1317 #define KUNIT_ASSERT_PTR_EQ_MSG(test, left, right, fmt, ...) \ 1318 KUNIT_BINARY_PTR_ASSERTION(test, \ 1319 KUNIT_ASSERTION, \ 1320 left, ==, right, \ 1321 fmt, \ 1322 ##__VA_ARGS__) 1323 1324 /** 1325 * KUNIT_ASSERT_NE() - An assertion that @left and @right are not equal. 1326 * @test: The test context object. 1327 * @left: an arbitrary expression that evaluates to a primitive C type. 1328 * @right: an arbitrary expression that evaluates to a primitive C type. 1329 * 1330 * Sets an assertion that the values that @left and @right evaluate to are not 1331 * equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion 1332 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1333 */ 1334 #define KUNIT_ASSERT_NE(test, left, right) \ 1335 KUNIT_ASSERT_NE_MSG(test, left, right, NULL) 1336 1337 #define KUNIT_ASSERT_NE_MSG(test, left, right, fmt, ...) \ 1338 KUNIT_BINARY_INT_ASSERTION(test, \ 1339 KUNIT_ASSERTION, \ 1340 left, !=, right, \ 1341 fmt, \ 1342 ##__VA_ARGS__) 1343 1344 /** 1345 * KUNIT_ASSERT_PTR_NE() - Asserts that pointers @left and @right are not equal. 1346 * KUNIT_ASSERT_PTR_EQ() - Asserts that pointers @left and @right are equal. 1347 * @test: The test context object. 1348 * @left: an arbitrary expression that evaluates to a pointer. 1349 * @right: an arbitrary expression that evaluates to a pointer. 1350 * 1351 * Sets an assertion that the values that @left and @right evaluate to are not 1352 * equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion 1353 * failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1354 */ 1355 #define KUNIT_ASSERT_PTR_NE(test, left, right) \ 1356 KUNIT_ASSERT_PTR_NE_MSG(test, left, right, NULL) 1357 1358 #define KUNIT_ASSERT_PTR_NE_MSG(test, left, right, fmt, ...) \ 1359 KUNIT_BINARY_PTR_ASSERTION(test, \ 1360 KUNIT_ASSERTION, \ 1361 left, !=, right, \ 1362 fmt, \ 1363 ##__VA_ARGS__) 1364 /** 1365 * KUNIT_ASSERT_LT() - An assertion that @left is less than @right. 1366 * @test: The test context object. 1367 * @left: an arbitrary expression that evaluates to a primitive C type. 1368 * @right: an arbitrary expression that evaluates to a primitive C type. 1369 * 1370 * Sets an assertion that the value that @left evaluates to is less than the 1371 * value that @right evaluates to. This is the same as KUNIT_EXPECT_LT(), except 1372 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1373 * is not met. 1374 */ 1375 #define KUNIT_ASSERT_LT(test, left, right) \ 1376 KUNIT_ASSERT_LT_MSG(test, left, right, NULL) 1377 1378 #define KUNIT_ASSERT_LT_MSG(test, left, right, fmt, ...) \ 1379 KUNIT_BINARY_INT_ASSERTION(test, \ 1380 KUNIT_EXPECTATION, \ 1381 left, <, right, \ 1382 fmt, \ 1383 ##__VA_ARGS__) 1384 /** 1385 * KUNIT_ASSERT_LE() - An assertion that @left is less than or equal to @right. 1386 * @test: The test context object. 1387 * @left: an arbitrary expression that evaluates to a primitive C type. 1388 * @right: an arbitrary expression that evaluates to a primitive C type. 1389 * 1390 * Sets an assertion that the value that @left evaluates to is less than or 1391 * equal to the value that @right evaluates to. This is the same as 1392 * KUNIT_EXPECT_LE(), except it causes an assertion failure (see 1393 * KUNIT_ASSERT_TRUE()) when the assertion is not met. 1394 */ 1395 #define KUNIT_ASSERT_LE(test, left, right) \ 1396 KUNIT_ASSERT_LE_MSG(test, left, right, NULL) 1397 1398 #define KUNIT_ASSERT_LE_MSG(test, left, right, fmt, ...) \ 1399 KUNIT_BINARY_INT_ASSERTION(test, \ 1400 KUNIT_ASSERTION, \ 1401 left, <=, right, \ 1402 fmt, \ 1403 ##__VA_ARGS__) 1404 1405 /** 1406 * KUNIT_ASSERT_GT() - An assertion that @left is greater than @right. 1407 * @test: The test context object. 1408 * @left: an arbitrary expression that evaluates to a primitive C type. 1409 * @right: an arbitrary expression that evaluates to a primitive C type. 1410 * 1411 * Sets an assertion that the value that @left evaluates to is greater than the 1412 * value that @right evaluates to. This is the same as KUNIT_EXPECT_GT(), except 1413 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1414 * is not met. 1415 */ 1416 #define KUNIT_ASSERT_GT(test, left, right) \ 1417 KUNIT_ASSERT_GT_MSG(test, left, right, NULL) 1418 1419 #define KUNIT_ASSERT_GT_MSG(test, left, right, fmt, ...) \ 1420 KUNIT_BINARY_INT_ASSERTION(test, \ 1421 KUNIT_EXPECTATION, \ 1422 left, >, right, \ 1423 fmt, \ 1424 ##__VA_ARGS__) 1425 1426 /** 1427 * KUNIT_ASSERT_GE() - Assertion that @left is greater than or equal to @right. 1428 * @test: The test context object. 1429 * @left: an arbitrary expression that evaluates to a primitive C type. 1430 * @right: an arbitrary expression that evaluates to a primitive C type. 1431 * 1432 * Sets an assertion that the value that @left evaluates to is greater than the 1433 * value that @right evaluates to. This is the same as KUNIT_EXPECT_GE(), except 1434 * it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion 1435 * is not met. 1436 */ 1437 #define KUNIT_ASSERT_GE(test, left, right) \ 1438 KUNIT_ASSERT_GE_MSG(test, left, right, NULL) 1439 1440 #define KUNIT_ASSERT_GE_MSG(test, left, right, fmt, ...) \ 1441 KUNIT_BINARY_INT_ASSERTION(test, \ 1442 KUNIT_ASSERTION, \ 1443 left, >=, right, \ 1444 fmt, \ 1445 ##__VA_ARGS__) 1446 1447 /** 1448 * KUNIT_ASSERT_STREQ() - An assertion that strings @left and @right are equal. 1449 * @test: The test context object. 1450 * @left: an arbitrary expression that evaluates to a null terminated string. 1451 * @right: an arbitrary expression that evaluates to a null terminated string. 1452 * 1453 * Sets an assertion that the values that @left and @right evaluate to are 1454 * equal. This is the same as KUNIT_EXPECT_STREQ(), except it causes an 1455 * assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met. 1456 */ 1457 #define KUNIT_ASSERT_STREQ(test, left, right) \ 1458 KUNIT_ASSERT_STREQ_MSG(test, left, right, NULL) 1459 1460 #define KUNIT_ASSERT_STREQ_MSG(test, left, right, fmt, ...) \ 1461 KUNIT_BINARY_STR_ASSERTION(test, \ 1462 KUNIT_ASSERTION, \ 1463 left, ==, right, \ 1464 fmt, \ 1465 ##__VA_ARGS__) 1466 1467 /** 1468 * KUNIT_ASSERT_STRNEQ() - Expects that strings @left and @right are not equal. 1469 * @test: The test context object. 1470 * @left: an arbitrary expression that evaluates to a null terminated string. 1471 * @right: an arbitrary expression that evaluates to a null terminated string. 1472 * 1473 * Sets an expectation that the values that @left and @right evaluate to are 1474 * not equal. This is semantically equivalent to 1475 * KUNIT_ASSERT_TRUE(@test, strcmp((@left), (@right))). See KUNIT_ASSERT_TRUE() 1476 * for more information. 1477 */ 1478 #define KUNIT_ASSERT_STRNEQ(test, left, right) \ 1479 KUNIT_ASSERT_STRNEQ_MSG(test, left, right, NULL) 1480 1481 #define KUNIT_ASSERT_STRNEQ_MSG(test, left, right, fmt, ...) \ 1482 KUNIT_BINARY_STR_ASSERTION(test, \ 1483 KUNIT_ASSERTION, \ 1484 left, !=, right, \ 1485 fmt, \ 1486 ##__VA_ARGS__) 1487 1488 /** 1489 * KUNIT_ASSERT_NOT_ERR_OR_NULL() - Assertion that @ptr is not null and not err. 1490 * @test: The test context object. 1491 * @ptr: an arbitrary pointer. 1492 * 1493 * Sets an assertion that the value that @ptr evaluates to is not null and not 1494 * an errno stored in a pointer. This is the same as 1495 * KUNIT_EXPECT_NOT_ERR_OR_NULL(), except it causes an assertion failure (see 1496 * KUNIT_ASSERT_TRUE()) when the assertion is not met. 1497 */ 1498 #define KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ptr) \ 1499 KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, NULL) 1500 1501 #define KUNIT_ASSERT_NOT_ERR_OR_NULL_MSG(test, ptr, fmt, ...) \ 1502 KUNIT_PTR_NOT_ERR_OR_NULL_MSG_ASSERTION(test, \ 1503 KUNIT_ASSERTION, \ 1504 ptr, \ 1505 fmt, \ 1506 ##__VA_ARGS__) 1507 1508 /** 1509 * KUNIT_ARRAY_PARAM() - Define test parameter generator from an array. 1510 * @name: prefix for the test parameter generator function. 1511 * @array: array of test parameters. 1512 * @get_desc: function to convert param to description; NULL to use default 1513 * 1514 * Define function @name_gen_params which uses @array to generate parameters. 1515 */ 1516 #define KUNIT_ARRAY_PARAM(name, array, get_desc) \ 1517 static const void *name##_gen_params(const void *prev, char *desc) \ 1518 { \ 1519 typeof((array)[0]) *__next = prev ? ((typeof(__next)) prev) + 1 : (array); \ 1520 if (__next - (array) < ARRAY_SIZE((array))) { \ 1521 void (*__get_desc)(typeof(__next), char *) = get_desc; \ 1522 if (__get_desc) \ 1523 __get_desc(__next, desc); \ 1524 return __next; \ 1525 } \ 1526 return NULL; \ 1527 } 1528 1529 #endif /* _KUNIT_TEST_H */ 1530