MdePkg/Include/Library/UnitTestLib.h

   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