1 /** @file 2 Provides a unit test framework. This allows tests to focus on testing logic 3 and the framework to focus on runnings, reporting, statistics, etc. 4 5 Copyright (c) Microsoft Corporation.<BR> 6 Copyright (c) 2020, Intel Corporation. All rights reserved.<BR> 7 SPDX-License-Identifier: BSD-2-Clause-Patent 8 **/ 9 10 #ifndef __UNIT_TEST_LIB_H__ 11 #define __UNIT_TEST_LIB_H__ 12 13 /// 14 /// Unit Test Status 15 /// 16 typedef UINT32 UNIT_TEST_STATUS; 17 #define UNIT_TEST_PASSED (0) 18 #define UNIT_TEST_ERROR_PREREQUISITE_NOT_MET (1) 19 #define UNIT_TEST_ERROR_TEST_FAILED (2) 20 #define UNIT_TEST_ERROR_CLEANUP_FAILED (3) 21 #define UNIT_TEST_SKIPPED (0xFFFFFFFD) 22 #define UNIT_TEST_RUNNING (0xFFFFFFFE) 23 #define UNIT_TEST_PENDING (0xFFFFFFFF) 24 25 /// 26 /// Declare PcdUnitTestLogLevel bits and UnitTestLog() ErrorLevel parameter. 27 /// 28 #define UNIT_TEST_LOG_LEVEL_ERROR BIT0 29 #define UNIT_TEST_LOG_LEVEL_WARN BIT1 30 #define UNIT_TEST_LOG_LEVEL_INFO BIT2 31 #define UNIT_TEST_LOG_LEVEL_VERBOSE BIT3 32 33 /// 34 /// Unit Test Framework Handle 35 /// 36 struct UNIT_TEST_FRAMEWORK_OBJECT; 37 typedef struct UNIT_TEST_FRAMEWORK_OBJECT *UNIT_TEST_FRAMEWORK_HANDLE; 38 39 /// 40 /// Unit Test Suite Handle 41 /// 42 struct UNIT_TEST_SUITE_OBJECT; 43 typedef struct UNIT_TEST_SUITE_OBJECT *UNIT_TEST_SUITE_HANDLE; 44 45 /// 46 /// Unit Test Handle 47 /// 48 struct UNIT_TEST_OBJECT; 49 typedef struct UNIT_TEST_OBJECT *UNIT_TEST_HANDLE; 50 51 /// 52 /// Unit Test Context 53 /// 54 typedef VOID* UNIT_TEST_CONTEXT; 55 56 /** 57 The prototype for a single UnitTest case function. 58 59 Functions with this prototype are registered to be dispatched by the 60 UnitTest framework, and results are recorded as test Pass or Fail. 61 62 @param[in] Context [Optional] An optional parameter that enables: 63 1) test-case reuse with varied parameters and 64 2) test-case re-entry for Target tests that need a 65 reboot. This parameter is a VOID* and it is the 66 responsibility of the test author to ensure that the 67 contents are well understood by all test cases that may 68 consume it. 69 70 @retval UNIT_TEST_PASSED The Unit test has completed and the test 71 case was successful. 72 @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed. 73 74 **/ 75 typedef 76 UNIT_TEST_STATUS 77 (EFIAPI *UNIT_TEST_FUNCTION)( 78 IN UNIT_TEST_CONTEXT Context 79 ); 80 81 /** 82 Unit-Test Prerequisite Function pointer type. 83 84 Functions with this prototype are registered to be dispatched by the unit test 85 framework prior to a given test case. If this prereq function returns 86 UNIT_TEST_ERROR_PREREQUISITE_NOT_MET, the test case will be skipped. 87 88 @param[in] Context [Optional] An optional parameter that enables: 89 1) test-case reuse with varied parameters and 90 2) test-case re-entry for Target tests that need a 91 reboot. This parameter is a VOID* and it is the 92 responsibility of the test author to ensure that the 93 contents are well understood by all test cases that may 94 consume it. 95 96 @retval UNIT_TEST_PASSED Unit test case prerequisites 97 are met. 98 @retval UNIT_TEST_ERROR_PREREQUISITE_NOT_MET Test case should be skipped. 99 100 **/ 101 typedef 102 UNIT_TEST_STATUS 103 (EFIAPI *UNIT_TEST_PREREQUISITE)( 104 IN UNIT_TEST_CONTEXT Context 105 ); 106 107 /** 108 Unit-Test Cleanup (after) function pointer type. 109 110 Functions with this prototype are registered to be dispatched by the 111 unit test framework after a given test case. This will be called even if the 112 test case returns an error, but not if the prerequisite fails and the test is 113 skipped. The purpose of this function is to clean up any global state or 114 test data. 115 116 @param[in] Context [Optional] An optional parameter that enables: 117 1) test-case reuse with varied parameters and 118 2) test-case re-entry for Target tests that need a 119 reboot. This parameter is a VOID* and it is the 120 responsibility of the test author to ensure that the 121 contents are well understood by all test cases that may 122 consume it. 123 124 @retval UNIT_TEST_PASSED Test case cleanup succeeded. 125 @retval UNIT_TEST_ERROR_CLEANUP_FAILED Test case cleanup failed. 126 127 **/ 128 typedef 129 VOID 130 (EFIAPI *UNIT_TEST_CLEANUP)( 131 IN UNIT_TEST_CONTEXT Context 132 ); 133 134 /** 135 Unit-Test Test Suite Setup (before) function pointer type. Functions with this 136 prototype are registered to be dispatched by the UnitTest framework prior to 137 running any of the test cases in a test suite. It will only be run once at 138 the beginning of the suite (not prior to each case). 139 140 The purpose of this function is to set up any global state or test data. 141 **/ 142 typedef 143 VOID 144 (EFIAPI *UNIT_TEST_SUITE_SETUP)( 145 VOID 146 ); 147 148 /** 149 Unit-Test Test Suite Teardown (after) function pointer type. Functions with 150 this prototype are registered to be dispatched by the UnitTest framework after 151 running all of the test cases in a test suite. It will only be run once at 152 the end of the suite. 153 154 The purpose of this function is to clean up any global state or test data. 155 **/ 156 typedef 157 VOID 158 (EFIAPI *UNIT_TEST_SUITE_TEARDOWN)( 159 VOID 160 ); 161 162 /** 163 Method to Initialize the Unit Test framework. This function registers the 164 test name and also initializes the internal state of the test framework to 165 receive any new suites and tests. 166 167 @param[out] FrameworkHandle Unit test framework to be created. 168 @param[in] Title Null-terminated ASCII string that is the user 169 friendly name of the framework. String is 170 copied. 171 @param[in] ShortTitle Null-terminated ASCII short string that is the 172 short name of the framework with no spaces. 173 String is copied. 174 @param[in] VersionString Null-terminated ASCII version string for the 175 framework. String is copied. 176 177 @retval EFI_SUCCESS The unit test framework was initialized. 178 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. 179 @retval EFI_INVALID_PARAMETER Title is NULL. 180 @retval EFI_INVALID_PARAMETER ShortTitle is NULL. 181 @retval EFI_INVALID_PARAMETER VersionString is NULL. 182 @retval EFI_INVALID_PARAMETER ShortTitle is invalid. 183 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to 184 initialize the unit test framework. 185 **/ 186 EFI_STATUS 187 EFIAPI 188 InitUnitTestFramework ( 189 OUT UNIT_TEST_FRAMEWORK_HANDLE *FrameworkHandle, 190 IN CHAR8 *Title, 191 IN CHAR8 *ShortTitle, 192 IN CHAR8 *VersionString 193 ); 194 195 /** 196 Registers a Unit Test Suite in the Unit Test Framework. 197 At least one test suite must be registered, because all test cases must be 198 within a unit test suite. 199 200 @param[out] SuiteHandle Unit test suite to create 201 @param[in] FrameworkHandle Unit test framework to add unit test suite to 202 @param[in] Title Null-terminated ASCII string that is the user 203 friendly name of the test suite. String is 204 copied. 205 @param[in] Name Null-terminated ASCII string that is the short 206 name of the test suite with no spaces. String 207 is copied. 208 @param[in] Setup Setup function, runs before suite. This is an 209 optional parameter that may be NULL. 210 @param[in] Teardown Teardown function, runs after suite. This is an 211 optional parameter that may be NULL. 212 213 @retval EFI_SUCCESS The unit test suite was created. 214 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL. 215 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. 216 @retval EFI_INVALID_PARAMETER Title is NULL. 217 @retval EFI_INVALID_PARAMETER Name is NULL. 218 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to 219 initialize the unit test suite. 220 **/ 221 EFI_STATUS 222 EFIAPI 223 CreateUnitTestSuite ( 224 OUT UNIT_TEST_SUITE_HANDLE *SuiteHandle, 225 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle, 226 IN CHAR8 *Title, 227 IN CHAR8 *Name, 228 IN UNIT_TEST_SUITE_SETUP Setup OPTIONAL, 229 IN UNIT_TEST_SUITE_TEARDOWN Teardown OPTIONAL 230 ); 231 232 /** 233 Adds test case to Suite 234 235 @param[in] SuiteHandle Unit test suite to add test to. 236 @param[in] Description Null-terminated ASCII string that is the user 237 friendly description of a test. String is copied. 238 @param[in] Name Null-terminated ASCII string that is the short name 239 of the test with no spaces. String is copied. 240 @param[in] Function Unit test function. 241 @param[in] Prerequisite Prerequisite function, runs before test. This is 242 an optional parameter that may be NULL. 243 @param[in] CleanUp Clean up function, runs after test. This is an 244 optional parameter that may be NULL. 245 @param[in] Context Pointer to context. This is an optional parameter 246 that may be NULL. 247 248 @retval EFI_SUCCESS The unit test case was added to Suite. 249 @retval EFI_INVALID_PARAMETER SuiteHandle is NULL. 250 @retval EFI_INVALID_PARAMETER Description is NULL. 251 @retval EFI_INVALID_PARAMETER Name is NULL. 252 @retval EFI_INVALID_PARAMETER Function is NULL. 253 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to 254 add the unit test case to Suite. 255 **/ 256 EFI_STATUS 257 EFIAPI 258 AddTestCase ( 259 IN UNIT_TEST_SUITE_HANDLE SuiteHandle, 260 IN CHAR8 *Description, 261 IN CHAR8 *Name, 262 IN UNIT_TEST_FUNCTION Function, 263 IN UNIT_TEST_PREREQUISITE Prerequisite OPTIONAL, 264 IN UNIT_TEST_CLEANUP CleanUp OPTIONAL, 265 IN UNIT_TEST_CONTEXT Context OPTIONAL 266 ); 267 268 /** 269 Execute all unit test cases in all unit test suites added to a Framework. 270 271 Once a unit test framework is initialized and all unit test suites and unit 272 test cases are registered, this function will cause the unit test framework to 273 dispatch all unit test cases in sequence and record the results for reporting. 274 275 @param[in] FrameworkHandle A handle to the current running framework that 276 dispatched the test. Necessary for recording 277 certain test events with the framework. 278 279 @retval EFI_SUCCESS All test cases were dispatched. 280 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. 281 **/ 282 EFI_STATUS 283 EFIAPI 284 RunAllTestSuites ( 285 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle 286 ); 287 288 /** 289 Cleanup a test framework. 290 291 After tests are run, this will teardown the entire framework and free all 292 allocated data within. 293 294 @param[in] FrameworkHandle A handle to the current running framework that 295 dispatched the test. Necessary for recording 296 certain test events with the framework. 297 298 @retval EFI_SUCCESS All resources associated with framework were 299 freed. 300 @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. 301 **/ 302 EFI_STATUS 303 EFIAPI 304 FreeUnitTestFramework ( 305 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle 306 ); 307 308 /** 309 Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're 310 a framework author) to save the state of the executing framework along with 311 any allocated data so that the test may be resumed upon reentry. A test case 312 should pass any needed context (which, to prevent an infinite loop, should be 313 at least the current execution count) which will be saved by the framework and 314 passed to the test case upon resume. 315 316 This should be called while the current test framework is valid and active. It is 317 generally called from within a test case prior to quitting or rebooting. 318 319 @param[in] ContextToSave A buffer of test case-specific data to be saved 320 along with framework state. Will be passed as 321 "Context" to the test case upon resume. This 322 is an optional parameter that may be NULL. 323 @param[in] ContextToSaveSize Size of the ContextToSave buffer. 324 325 @retval EFI_SUCCESS The framework state and context were saved. 326 @retval EFI_NOT_FOUND An active framework handle was not found. 327 @retval EFI_INVALID_PARAMETER ContextToSave is not NULL and 328 ContextToSaveSize is 0. 329 @retval EFI_INVALID_PARAMETER ContextToSave is >= 4GB. 330 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to 331 save the framework and context state. 332 @retval EFI_DEVICE_ERROR The framework and context state could not be 333 saved to a persistent storage device due to a 334 device error. 335 **/ 336 EFI_STATUS 337 EFIAPI 338 SaveFrameworkState ( 339 IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL, 340 IN UINTN ContextToSaveSize 341 ); 342 343 /** 344 This macro uses the framework assertion logic to check an expression for 345 "TRUE". If the expression evaluates to TRUE, execution continues. 346 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 347 348 @param[in] Expression Expression to be evaluated for TRUE. 349 **/ 350 #define UT_ASSERT_TRUE(Expression) \ 351 if(!UnitTestAssertTrue ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \ 352 return UNIT_TEST_ERROR_TEST_FAILED; \ 353 } 354 355 /** 356 This macro uses the framework assertion logic to check an expression for 357 "FALSE". If the expression evaluates to FALSE, execution continues. 358 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 359 360 @param[in] Expression Expression to be evaluated for FALSE. 361 **/ 362 #define UT_ASSERT_FALSE(Expression) \ 363 if(!UnitTestAssertFalse ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \ 364 return UNIT_TEST_ERROR_TEST_FAILED; \ 365 } 366 367 /** 368 This macro uses the framework assertion logic to check whether two simple 369 values are equal. If the values are equal, execution continues. 370 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 371 372 @param[in] ValueA Value to be compared for equality (64-bit comparison). 373 @param[in] ValueB Value to be compared for equality (64-bit comparison). 374 **/ 375 #define UT_ASSERT_EQUAL(ValueA, ValueB) \ 376 if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \ 377 return UNIT_TEST_ERROR_TEST_FAILED; \ 378 } 379 380 /** 381 This macro uses the framework assertion logic to check whether two memory 382 buffers are equal. If the buffers are equal, execution continues. 383 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 384 385 @param[in] BufferA Pointer to a buffer for comparison. 386 @param[in] BufferB Pointer to a buffer for comparison. 387 @param[in] Length Number of bytes to compare in BufferA and BufferB. 388 **/ 389 #define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length) \ 390 if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __FUNCTION__, __LINE__, __FILE__, #BufferA, #BufferB)) { \ 391 return UNIT_TEST_ERROR_TEST_FAILED; \ 392 } 393 394 /** 395 This macro uses the framework assertion logic to check whether two simple 396 values are non-equal. If the values are non-equal, execution continues. 397 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 398 399 @param[in] ValueA Value to be compared for inequality (64-bit comparison). 400 @param[in] ValueB Value to be compared for inequality (64-bit comparison). 401 **/ 402 #define UT_ASSERT_NOT_EQUAL(ValueA, ValueB) \ 403 if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \ 404 return UNIT_TEST_ERROR_TEST_FAILED; \ 405 } 406 407 /** 408 This macro uses the framework assertion logic to check whether an EFI_STATUS 409 value is !EFI_ERROR(). If the status is !EFI_ERROR(), execution continues. 410 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 411 412 @param[in] Status EFI_STATUS value to check. 413 **/ 414 #define UT_ASSERT_NOT_EFI_ERROR(Status) \ 415 if(!UnitTestAssertNotEfiError ((Status), __FUNCTION__, __LINE__, __FILE__, #Status)) { \ 416 return UNIT_TEST_ERROR_TEST_FAILED; \ 417 } 418 419 /** 420 This macro uses the framework assertion logic to check whether two EFI_STATUS 421 values are equal. If the values are equal, execution continues. 422 Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 423 424 @param[in] Status EFI_STATUS values to compare for equality. 425 @param[in] Expected EFI_STATUS values to compare for equality. 426 **/ 427 #define UT_ASSERT_STATUS_EQUAL(Status, Expected) \ 428 if(!UnitTestAssertStatusEqual ((Status), (Expected), __FUNCTION__, __LINE__, __FILE__, #Status)) { \ 429 return UNIT_TEST_ERROR_TEST_FAILED; \ 430 } 431 432 /** 433 This macro uses the framework assertion logic to check whether a pointer is 434 not NULL. If the pointer is not NULL, execution continues. Otherwise, the 435 test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. 436 437 @param[in] Pointer Pointer to be checked against NULL. 438 **/ 439 #define UT_ASSERT_NOT_NULL(Pointer) \ 440 if(!UnitTestAssertNotNull ((Pointer), __FUNCTION__, __LINE__, __FILE__, #Pointer)) { \ 441 return UNIT_TEST_ERROR_TEST_FAILED; \ 442 } 443 444 /** 445 This macro uses the framework assertion logic to check whether a function call 446 triggers an ASSERT() condition. The BaseLib SetJump()/LongJump() services 447 are used to establish a safe return point when an ASSERT() is triggered. 448 If an ASSERT() is triggered, unit test execution continues and Status is set 449 to UNIT_TEST_PASSED. Otherwise, a unit test case failure is raised and 450 Status is set to UNIT_TEST_ERROR_TEST_FAILED. 451 452 If ASSERT() macros are disabled, then the test case is skipped and a warning 453 message is added to the unit test log. Status is set to UNIT_TEST_SKIPPED. 454 455 @param[in] FunctionCall Function call that is expected to trigger ASSERT(). 456 @param[out] Status Pointer to a UNIT_TEST_STATUS return value. This 457 is an optional parameter that may be NULL. 458 **/ 459 #if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED) 460 #include <Library/BaseLib.h> 461 462 /// 463 /// Pointer to jump buffer used with SetJump()/LongJump() to test if a 464 /// function under test generates an expected ASSERT() condition. 465 /// 466 extern BASE_LIBRARY_JUMP_BUFFER *gUnitTestExpectAssertFailureJumpBuffer; 467 468 #define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) \ 469 do { \ 470 UNIT_TEST_STATUS UnitTestJumpStatus; \ 471 BASE_LIBRARY_JUMP_BUFFER UnitTestJumpBuffer; \ 472 UnitTestJumpStatus = UNIT_TEST_SKIPPED; \ 473 if (DebugAssertEnabled ()) { \ 474 gUnitTestExpectAssertFailureJumpBuffer = &UnitTestJumpBuffer; \ 475 if (SetJump (gUnitTestExpectAssertFailureJumpBuffer) == 0) { \ 476 FunctionCall; \ 477 UnitTestJumpStatus = UNIT_TEST_ERROR_TEST_FAILED; \ 478 } else { \ 479 UnitTestJumpStatus = UNIT_TEST_PASSED; \ 480 } \ 481 gUnitTestExpectAssertFailureJumpBuffer = NULL; \ 482 } \ 483 if (!UnitTestExpectAssertFailure ( \ 484 UnitTestJumpStatus, \ 485 __FUNCTION__, __LINE__, __FILE__, \ 486 #FunctionCall, Status)) { \ 487 return UNIT_TEST_ERROR_TEST_FAILED; \ 488 } \ 489 } while (FALSE) 490 #else 491 #define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) FunctionCall; 492 #endif 493 494 /** 495 If Expression is TRUE, then TRUE is returned. 496 If Expression is FALSE, then an assert is triggered and the location of the 497 assert provided by FunctionName, LineNumber, FileName, and Description are 498 recorded and FALSE is returned. 499 500 @param[in] Expression The BOOLEAN result of the expression evaluation. 501 @param[in] FunctionName Null-terminated ASCII string of the function 502 executing the assert macro. 503 @param[in] LineNumber The source file line number of the assert macro. 504 @param[in] FileName Null-terminated ASCII string of the filename 505 executing the assert macro. 506 @param[in] Description Null-terminated ASCII string of the expression being 507 evaluated. 508 509 @retval TRUE Expression is TRUE. 510 @retval FALSE Expression is FALSE. 511 **/ 512 BOOLEAN 513 EFIAPI 514 UnitTestAssertTrue ( 515 IN BOOLEAN Expression, 516 IN CONST CHAR8 *FunctionName, 517 IN UINTN LineNumber, 518 IN CONST CHAR8 *FileName, 519 IN CONST CHAR8 *Description 520 ); 521 522 /** 523 If Expression is FALSE, then TRUE is returned. 524 If Expression is TRUE, then an assert is triggered and the location of the 525 assert provided by FunctionName, LineNumber, FileName, and Description are 526 recorded and FALSE is returned. 527 528 @param[in] Expression The BOOLEAN result of the expression evaluation. 529 @param[in] FunctionName Null-terminated ASCII string of the function 530 executing the assert macro. 531 @param[in] LineNumber The source file line number of the assert macro. 532 @param[in] FileName Null-terminated ASCII string of the filename 533 executing the assert macro. 534 @param[in] Description Null-terminated ASCII string of the expression being 535 evaluated. 536 537 @retval TRUE Expression is FALSE. 538 @retval FALSE Expression is TRUE. 539 **/ 540 BOOLEAN 541 EFIAPI 542 UnitTestAssertFalse ( 543 IN BOOLEAN Expression, 544 IN CONST CHAR8 *FunctionName, 545 IN UINTN LineNumber, 546 IN CONST CHAR8 *FileName, 547 IN CONST CHAR8 *Description 548 ); 549 550 /** 551 If Status is not an EFI_ERROR(), then TRUE is returned. 552 If Status is an EFI_ERROR(), then an assert is triggered and the location of 553 the assert provided by FunctionName, LineNumber, FileName, and Description are 554 recorded and FALSE is returned. 555 556 @param[in] Status The EFI_STATUS value to evaluate. 557 @param[in] FunctionName Null-terminated ASCII string of the function 558 executing the assert macro. 559 @param[in] LineNumber The source file line number of the assert macro. 560 @param[in] FileName Null-terminated ASCII string of the filename 561 executing the assert macro. 562 @param[in] Description Null-terminated ASCII string of the status 563 expression being evaluated. 564 565 @retval TRUE Status is not an EFI_ERROR(). 566 @retval FALSE Status is an EFI_ERROR(). 567 **/ 568 BOOLEAN 569 EFIAPI 570 UnitTestAssertNotEfiError ( 571 IN EFI_STATUS Status, 572 IN CONST CHAR8 *FunctionName, 573 IN UINTN LineNumber, 574 IN CONST CHAR8 *FileName, 575 IN CONST CHAR8 *Description 576 ); 577 578 /** 579 If ValueA is equal ValueB, then TRUE is returned. 580 If ValueA is not equal to ValueB, then an assert is triggered and the location 581 of the assert provided by FunctionName, LineNumber, FileName, DescriptionA, 582 and DescriptionB are recorded and FALSE is returned. 583 584 @param[in] ValueA 64-bit value. 585 @param[in] ValueB 64-bit value. 586 @param[in] FunctionName Null-terminated ASCII string of the function 587 executing the assert macro. 588 @param[in] LineNumber The source file line number of the assert macro. 589 @param[in] FileName Null-terminated ASCII string of the filename 590 executing the assert macro. 591 @param[in] DescriptionA Null-terminated ASCII string that is a description 592 of ValueA. 593 @param[in] DescriptionB Null-terminated ASCII string that is a description 594 of ValueB. 595 596 @retval TRUE ValueA is equal to ValueB. 597 @retval FALSE ValueA is not equal to ValueB. 598 **/ 599 BOOLEAN 600 EFIAPI 601 UnitTestAssertEqual ( 602 IN UINT64 ValueA, 603 IN UINT64 ValueB, 604 IN CONST CHAR8 *FunctionName, 605 IN UINTN LineNumber, 606 IN CONST CHAR8 *FileName, 607 IN CONST CHAR8 *DescriptionA, 608 IN CONST CHAR8 *DescriptionB 609 ); 610 611 /** 612 If the contents of BufferA are identical to the contents of BufferB, then TRUE 613 is returned. If the contents of BufferA are not identical to the contents of 614 BufferB, then an assert is triggered and the location of the assert provided 615 by FunctionName, LineNumber, FileName, DescriptionA, and DescriptionB are 616 recorded and FALSE is returned. 617 618 @param[in] BufferA Pointer to a buffer for comparison. 619 @param[in] BufferB Pointer to a buffer for comparison. 620 @param[in] Length Number of bytes to compare in BufferA and BufferB. 621 @param[in] FunctionName Null-terminated ASCII string of the function 622 executing the assert macro. 623 @param[in] LineNumber The source file line number of the assert macro. 624 @param[in] FileName Null-terminated ASCII string of the filename 625 executing the assert macro. 626 @param[in] DescriptionA Null-terminated ASCII string that is a description 627 of BufferA. 628 @param[in] DescriptionB Null-terminated ASCII string that is a description 629 of BufferB. 630 631 @retval TRUE The contents of BufferA are identical to the contents of 632 BufferB. 633 @retval FALSE The contents of BufferA are not identical to the contents of 634 BufferB. 635 **/ 636 BOOLEAN 637 EFIAPI 638 UnitTestAssertMemEqual ( 639 IN VOID *BufferA, 640 IN VOID *BufferB, 641 IN UINTN Length, 642 IN CONST CHAR8 *FunctionName, 643 IN UINTN LineNumber, 644 IN CONST CHAR8 *FileName, 645 IN CONST CHAR8 *DescriptionA, 646 IN CONST CHAR8 *DescriptionB 647 ); 648 649 /** 650 If ValueA is not equal ValueB, then TRUE is returned. 651 If ValueA is equal to ValueB, then an assert is triggered and the location 652 of the assert provided by FunctionName, LineNumber, FileName, DescriptionA 653 and DescriptionB are recorded and FALSE is returned. 654 655 @param[in] ValueA 64-bit value. 656 @param[in] ValueB 64-bit value. 657 @param[in] FunctionName Null-terminated ASCII string of the function 658 executing the assert macro. 659 @param[in] LineNumber The source file line number of the assert macro. 660 @param[in] FileName Null-terminated ASCII string of the filename 661 executing the assert macro. 662 @param[in] DescriptionA Null-terminated ASCII string that is a description 663 of ValueA. 664 @param[in] DescriptionB Null-terminated ASCII string that is a description 665 of ValueB. 666 667 @retval TRUE ValueA is not equal to ValueB. 668 @retval FALSE ValueA is equal to ValueB. 669 **/ 670 BOOLEAN 671 EFIAPI 672 UnitTestAssertNotEqual ( 673 IN UINT64 ValueA, 674 IN UINT64 ValueB, 675 IN CONST CHAR8 *FunctionName, 676 IN UINTN LineNumber, 677 IN CONST CHAR8 *FileName, 678 IN CONST CHAR8 *DescriptionA, 679 IN CONST CHAR8 *DescriptionB 680 ); 681 682 /** 683 If Status is equal to Expected, then TRUE is returned. 684 If Status is not equal to Expected, then an assert is triggered and the 685 location of the assert provided by FunctionName, LineNumber, FileName, and 686 Description are recorded and FALSE is returned. 687 688 @param[in] Status EFI_STATUS value returned from an API under test. 689 @param[in] Expected The expected EFI_STATUS return value from an API 690 under test. 691 @param[in] FunctionName Null-terminated ASCII string of the function 692 executing the assert macro. 693 @param[in] LineNumber The source file line number of the assert macro. 694 @param[in] FileName Null-terminated ASCII string of the filename 695 executing the assert macro. 696 @param[in] Description Null-terminated ASCII string that is a description 697 of Status. 698 699 @retval TRUE Status is equal to Expected. 700 @retval FALSE Status is not equal to Expected. 701 **/ 702 BOOLEAN 703 EFIAPI 704 UnitTestAssertStatusEqual ( 705 IN EFI_STATUS Status, 706 IN EFI_STATUS Expected, 707 IN CONST CHAR8 *FunctionName, 708 IN UINTN LineNumber, 709 IN CONST CHAR8 *FileName, 710 IN CONST CHAR8 *Description 711 ); 712 713 /** 714 If Pointer is not equal to NULL, then TRUE is returned. 715 If Pointer is equal to NULL, then an assert is triggered and the location of 716 the assert provided by FunctionName, LineNumber, FileName, and PointerName 717 are recorded and FALSE is returned. 718 719 @param[in] Pointer Pointer value to be checked against NULL. 720 @param[in] Expected The expected EFI_STATUS return value from a function 721 under test. 722 @param[in] FunctionName Null-terminated ASCII string of the function 723 executing the assert macro. 724 @param[in] LineNumber The source file line number of the assert macro. 725 @param[in] FileName Null-terminated ASCII string of the filename 726 executing the assert macro. 727 @param[in] PointerName Null-terminated ASCII string that is a description 728 of Pointer. 729 730 @retval TRUE Pointer is not equal to NULL. 731 @retval FALSE Pointer is equal to NULL. 732 **/ 733 BOOLEAN 734 EFIAPI 735 UnitTestAssertNotNull ( 736 IN VOID *Pointer, 737 IN CONST CHAR8 *FunctionName, 738 IN UINTN LineNumber, 739 IN CONST CHAR8 *FileName, 740 IN CONST CHAR8 *PointerName 741 ); 742 743 /** 744 If UnitTestStatus is UNIT_TEST_PASSED, then log an info message and return 745 TRUE because an ASSERT() was expected when FunctionCall was executed and an 746 ASSERT() was triggered. If UnitTestStatus is UNIT_TEST_SKIPPED, then log a 747 warning message and return TRUE because ASSERT() macros are disabled. If 748 UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED, then log an error message and 749 return FALSE because an ASSERT() was expected when FunctionCall was executed, 750 but no ASSERT() conditions were triggered. The log messages contain 751 FunctionName, LineNumber, and FileName strings to provide the location of the 752 UT_EXPECT_ASSERT_FAILURE() macro. 753 754 @param[in] UnitTestStatus The status from UT_EXPECT_ASSERT_FAILURE() that 755 is either pass, skipped, or failed. 756 @param[in] FunctionName Null-terminated ASCII string of the function 757 executing the UT_EXPECT_ASSERT_FAILURE() macro. 758 @param[in] LineNumber The source file line number of the the function 759 executing the UT_EXPECT_ASSERT_FAILURE() macro. 760 @param[in] FileName Null-terminated ASCII string of the filename 761 executing the UT_EXPECT_ASSERT_FAILURE() macro. 762 @param[in] FunctionCall Null-terminated ASCII string of the function call 763 executed by the UT_EXPECT_ASSERT_FAILURE() macro. 764 @param[out] ResultStatus Used to return the UnitTestStatus value to the 765 caller of UT_EXPECT_ASSERT_FAILURE(). This is 766 optional parameter that may be NULL. 767 768 @retval TRUE UnitTestStatus is UNIT_TEST_PASSED. 769 @retval TRUE UnitTestStatus is UNIT_TEST_SKIPPED. 770 @retval FALSE UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED. 771 **/ 772 BOOLEAN 773 EFIAPI 774 UnitTestExpectAssertFailure ( 775 IN UNIT_TEST_STATUS UnitTestStatus, 776 IN CONST CHAR8 *FunctionName, 777 IN UINTN LineNumber, 778 IN CONST CHAR8 *FileName, 779 IN CONST CHAR8 *FunctionCall, 780 OUT UNIT_TEST_STATUS *ResultStatus OPTIONAL 781 ); 782 783 /** 784 Test logging macro that records an ERROR message in the test framework log. 785 Record is associated with the currently executing test case. 786 787 @param[in] Format Formatting string following the format defined in 788 MdePkg/Include/Library/PrintLib.h. 789 @param[in] ... Print args. 790 **/ 791 #define UT_LOG_ERROR(Format, ...) \ 792 UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__) 793 794 /** 795 Test logging macro that records a WARNING message in the test framework log. 796 Record is associated with the currently executing test case. 797 798 @param[in] Format Formatting string following the format defined in 799 MdePkg/Include/Library/PrintLib.h. 800 @param[in] ... Print args. 801 **/ 802 #define UT_LOG_WARNING(Format, ...) \ 803 UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__) 804 805 /** 806 Test logging macro that records an INFO message in the test framework log. 807 Record is associated with the currently executing test case. 808 809 @param[in] Format Formatting string following the format defined in 810 MdePkg/Include/Library/PrintLib.h. 811 @param[in] ... Print args. 812 **/ 813 #define UT_LOG_INFO(Format, ...) \ 814 UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__) 815 816 /** 817 Test logging macro that records a VERBOSE message in the test framework log. 818 Record is associated with the currently executing test case. 819 820 @param[in] Format Formatting string following the format defined in 821 MdePkg/Include/Library/PrintLib.h. 822 @param[in] ... Print args. 823 **/ 824 #define UT_LOG_VERBOSE(Format, ...) \ 825 UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__) 826 827 /** 828 Test logging function that records a messages in the test framework log. 829 Record is associated with the currently executing test case. 830 831 @param[in] ErrorLevel The error level of the unit test log message. 832 @param[in] Format Formatting string following the format defined in the 833 MdePkg/Include/Library/PrintLib.h. 834 @param[in] ... Print args. 835 **/ 836 VOID 837 EFIAPI 838 UnitTestLog ( 839 IN UINTN ErrorLevel, 840 IN CONST CHAR8 *Format, 841 ... 842 ); 843 844 #endif 845