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   Generally called from within a test case prior to quitting or rebooting.
 317
 318   @param[in]  FrameworkHandle    A handle to the current running framework that
 319                                  dispatched the test.  Necessary for recording
 320                                  certain test events with the framework.
 321   @param[in]  ContextToSave      A buffer of test case-specific data to be saved
 322                                  along with framework state.  Will be passed as
 323                                  "Context" to the test case upon resume.  This
 324                                  is an optional parameter that may be NULL.
 325   @param[in]  ContextToSaveSize  Size of the ContextToSave buffer.
 326
 327   @retval  EFI_SUCCESS            The framework state and context were saved.
 328   @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.
 329   @retval  EFI_INVALID_PARAMETER  ContextToSave is not NULL and
 330                                   ContextToSaveSize is 0.
 331   @retval  EFI_INVALID_PARAMETER  ContextToSave is >= 4GB.
 332   @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to
 333                                   save the framework and context state.
 334   @retval  EFI_DEVICE_ERROR       The framework and context state could not be
 335                                   saved to a persistent storage device due to a
 336                                   device error.
 337 **/
 338 EFI_STATUS
 339 EFIAPI
 340 SaveFrameworkState (
 341   IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,
 342   IN UNIT_TEST_CONTEXT           ContextToSave     OPTIONAL,
 343   IN UINTN                       ContextToSaveSize
 344   );
 345
 346 /**
 347   This macro uses the framework assertion logic to check an expression for
 348   "TRUE". If the expression evaluates to TRUE, execution continues.
 349   Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 350
 351   @param[in]  Expression  Expression to be evaluated for TRUE.
 352 **/
 353 #define UT_ASSERT_TRUE(Expression)                                                        \
 354   if(!UnitTestAssertTrue ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \
 355     return UNIT_TEST_ERROR_TEST_FAILED;                                                   \
 356   }
 357
 358 /**
 359   This macro uses the framework assertion logic to check an expression for
 360   "FALSE". If the expression evaluates to FALSE, execution continues.
 361   Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 362
 363   @param[in]  Expression  Expression to be evaluated for FALSE.
 364 **/
 365 #define UT_ASSERT_FALSE(Expression)                                                        \
 366   if(!UnitTestAssertFalse ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \
 367     return UNIT_TEST_ERROR_TEST_FAILED;                                                    \
 368   }
 369
 370 /**
 371   This macro uses the framework assertion logic to check whether two simple
 372   values are equal.  If the values are equal, execution continues.
 373   Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 374
 375   @param[in]  ValueA  Value to be compared for equality (64-bit comparison).
 376   @param[in]  ValueB  Value to be compared for equality (64-bit comparison).
 377 **/
 378 #define UT_ASSERT_EQUAL(ValueA, ValueB)                                                                           \
 379   if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \
 380     return UNIT_TEST_ERROR_TEST_FAILED;                                                                           \
 381   }
 382
 383 /**
 384   This macro uses the framework assertion logic to check whether two memory
 385   buffers are equal.  If the buffers are equal, execution continues.
 386   Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 387
 388   @param[in]  BufferA  Pointer to a buffer for comparison.
 389   @param[in]  BufferB  Pointer to a buffer for comparison.
 390   @param[in]  Length   Number of bytes to compare in BufferA and BufferB.
 391 **/
 392 #define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length)                                                                               \
 393   if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __FUNCTION__, __LINE__, __FILE__, #BufferA, #BufferB)) { \
 394     return UNIT_TEST_ERROR_TEST_FAILED;                                                                                           \
 395   }
 396
 397 /**
 398   This macro uses the framework assertion logic to check whether two simple
 399   values are non-equal.  If the values are non-equal, execution continues.
 400   Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 401
 402   @param[in]  ValueA  Value to be compared for inequality (64-bit comparison).
 403   @param[in]  ValueB  Value to be compared for inequality (64-bit comparison).
 404 **/
 405 #define UT_ASSERT_NOT_EQUAL(ValueA, ValueB)                                                                          \
 406   if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \
 407     return UNIT_TEST_ERROR_TEST_FAILED;                                                                              \
 408   }
 409
 410 /**
 411   This macro uses the framework assertion logic to check whether an EFI_STATUS
 412   value is !EFI_ERROR().  If the status is !EFI_ERROR(), execution continues.
 413   Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 414
 415   @param[in]  Status  EFI_STATUS value to check.
 416 **/
 417 #define UT_ASSERT_NOT_EFI_ERROR(Status)                                                \
 418   if(!UnitTestAssertNotEfiError ((Status), __FUNCTION__, __LINE__, __FILE__, #Status)) { \
 419     return UNIT_TEST_ERROR_TEST_FAILED;                                                \
 420   }
 421
 422 /**
 423   This macro uses the framework assertion logic to check whether two EFI_STATUS
 424   values are equal.  If the values are equal, execution continues.
 425   Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 426
 427   @param[in]  Status    EFI_STATUS values to compare for equality.
 428   @param[in]  Expected  EFI_STATUS values to compare for equality.
 429 **/
 430 #define UT_ASSERT_STATUS_EQUAL(Status, Expected)                                                 \
 431   if(!UnitTestAssertStatusEqual ((Status), (Expected), __FUNCTION__, __LINE__, __FILE__, #Status)) { \
 432     return UNIT_TEST_ERROR_TEST_FAILED;                                                          \
 433   }
 434
 435 /**
 436   This macro uses the framework assertion logic to check whether a pointer is
 437   not NULL.  If the pointer is not NULL, execution continues. Otherwise, the
 438   test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
 439
 440   @param[in]  Pointer  Pointer to be checked against NULL.
 441 **/
 442 #define UT_ASSERT_NOT_NULL(Pointer)                                                  \
 443   if(!UnitTestAssertNotNull ((Pointer), __FUNCTION__, __LINE__, __FILE__, #Pointer)) { \
 444     return UNIT_TEST_ERROR_TEST_FAILED;                                              \
 445   }
 446
 447 /**
 448   If Expression is TRUE, then TRUE is returned.
 449   If Expression is FALSE, then an assert is triggered and the location of the
 450   assert provided by FunctionName, LineNumber, FileName, and Description are
 451   recorded and FALSE is returned.
 452
 453   @param[in]  Expression    The BOOLEAN result of the expression evaluation.
 454   @param[in]  FunctionName  Null-terminated ASCII string of the function
 455                             executing the assert macro.
 456   @param[in]  LineNumber    The source file line number of the assert macro.
 457   @param[in]  FileName      Null-terminated ASCII string of the filename
 458                             executing the assert macro.
 459   @param[in]  Description   Null-terminated ASCII string of the expression being
 460                             evaluated.
 461
 462   @retval  TRUE   Expression is TRUE.
 463   @retval  FALSE  Expression is FALSE.
 464 **/
 465 BOOLEAN
 466 EFIAPI
 467 UnitTestAssertTrue (
 468   IN BOOLEAN      Expression,
 469   IN CONST CHAR8  *FunctionName,
 470   IN UINTN        LineNumber,
 471   IN CONST CHAR8  *FileName,
 472   IN CONST CHAR8  *Description
 473   );
 474
 475 /**
 476   If Expression is FALSE, then TRUE is returned.
 477   If Expression is TRUE, then an assert is triggered and the location of the
 478   assert provided by FunctionName, LineNumber, FileName, and Description are
 479   recorded and FALSE is returned.
 480
 481   @param[in]  Expression    The BOOLEAN result of the expression evaluation.
 482   @param[in]  FunctionName  Null-terminated ASCII string of the function
 483                             executing the assert macro.
 484   @param[in]  LineNumber    The source file line number of the assert macro.
 485   @param[in]  FileName      Null-terminated ASCII string of the filename
 486                             executing the assert macro.
 487   @param[in]  Description   Null-terminated ASCII string of the expression being
 488                             evaluated.
 489
 490   @retval  TRUE   Expression is FALSE.
 491   @retval  FALSE  Expression is TRUE.
 492 **/
 493 BOOLEAN
 494 EFIAPI
 495 UnitTestAssertFalse (
 496   IN BOOLEAN      Expression,
 497   IN CONST CHAR8  *FunctionName,
 498   IN UINTN        LineNumber,
 499   IN CONST CHAR8  *FileName,
 500   IN CONST CHAR8  *Description
 501   );
 502
 503 /**
 504   If Status is not an EFI_ERROR(), then TRUE is returned.
 505   If Status is an EFI_ERROR(), then an assert is triggered and the location of
 506   the assert provided by FunctionName, LineNumber, FileName, and Description are
 507   recorded and FALSE is returned.
 508
 509   @param[in]  Status        The EFI_STATUS value to evaluate.
 510   @param[in]  FunctionName  Null-terminated ASCII string of the function
 511                             executing the assert macro.
 512   @param[in]  LineNumber    The source file line number of the assert macro.
 513   @param[in]  FileName      Null-terminated ASCII string of the filename
 514                             executing the assert macro.
 515   @param[in]  Description   Null-terminated ASCII string of the status
 516                             expression being evaluated.
 517
 518   @retval  TRUE   Status is not an EFI_ERROR().
 519   @retval  FALSE  Status is an EFI_ERROR().
 520 **/
 521 BOOLEAN
 522 EFIAPI
 523 UnitTestAssertNotEfiError (
 524   IN EFI_STATUS   Status,
 525   IN CONST CHAR8  *FunctionName,
 526   IN UINTN        LineNumber,
 527   IN CONST CHAR8  *FileName,
 528   IN CONST CHAR8  *Description
 529   );
 530
 531 /**
 532   If ValueA is equal ValueB, then TRUE is returned.
 533   If ValueA is not equal to ValueB, then an assert is triggered and the location
 534   of the assert provided by FunctionName, LineNumber, FileName, DescriptionA,
 535   and DescriptionB are recorded and FALSE is returned.
 536
 537   @param[in]  ValueA        64-bit value.
 538   @param[in]  ValueB        64-bit value.
 539   @param[in]  FunctionName  Null-terminated ASCII string of the function
 540                             executing the assert macro.
 541   @param[in]  LineNumber    The source file line number of the assert macro.
 542   @param[in]  FileName      Null-terminated ASCII string of the filename
 543                             executing the assert macro.
 544   @param[in]  DescriptionA  Null-terminated ASCII string that is a description
 545                             of ValueA.
 546   @param[in]  DescriptionB  Null-terminated ASCII string that is a description
 547                             of ValueB.
 548
 549   @retval  TRUE   ValueA is equal to ValueB.
 550   @retval  FALSE  ValueA is not equal to ValueB.
 551 **/
 552 BOOLEAN
 553 EFIAPI
 554 UnitTestAssertEqual (
 555   IN UINT64       ValueA,
 556   IN UINT64       ValueB,
 557   IN CONST CHAR8  *FunctionName,
 558   IN UINTN        LineNumber,
 559   IN CONST CHAR8  *FileName,
 560   IN CONST CHAR8  *DescriptionA,
 561   IN CONST CHAR8  *DescriptionB
 562   );
 563
 564 /**
 565   If the contents of BufferA are identical to the contents of BufferB, then TRUE
 566   is returned.  If the contents of BufferA are not identical to the contents of
 567   BufferB, then an assert is triggered and the location of the assert provided
 568   by FunctionName, LineNumber, FileName, DescriptionA, and DescriptionB are
 569   recorded and FALSE is returned.
 570
 571   @param[in]  BufferA       Pointer to a buffer for comparison.
 572   @param[in]  BufferB       Pointer to a buffer for comparison.
 573   @param[in]  Length        Number of bytes to compare in BufferA and BufferB.
 574   @param[in]  FunctionName  Null-terminated ASCII string of the function
 575                             executing the assert macro.
 576   @param[in]  LineNumber    The source file line number of the assert macro.
 577   @param[in]  FileName      Null-terminated ASCII string of the filename
 578                             executing the assert macro.
 579   @param[in]  DescriptionA  Null-terminated ASCII string that is a description
 580                             of BufferA.
 581   @param[in]  DescriptionB  Null-terminated ASCII string that is a description
 582                             of BufferB.
 583
 584   @retval  TRUE   The contents of BufferA are identical to the contents of
 585                   BufferB.
 586   @retval  FALSE  The contents of BufferA are not identical to the contents of
 587                   BufferB.
 588 **/
 589 BOOLEAN
 590 EFIAPI
 591 UnitTestAssertMemEqual (
 592   IN VOID         *BufferA,
 593   IN VOID         *BufferB,
 594   IN UINTN        Length,
 595   IN CONST CHAR8  *FunctionName,
 596   IN UINTN        LineNumber,
 597   IN CONST CHAR8  *FileName,
 598   IN CONST CHAR8  *DescriptionA,
 599   IN CONST CHAR8  *DescriptionB
 600   );
 601
 602 /**
 603   If ValueA is not equal ValueB, then TRUE is returned.
 604   If ValueA is equal to ValueB, then an assert is triggered and the location
 605   of the assert provided by FunctionName, LineNumber, FileName, DescriptionA
 606   and DescriptionB are recorded and FALSE is returned.
 607
 608   @param[in]  ValueA        64-bit value.
 609   @param[in]  ValueB        64-bit value.
 610   @param[in]  FunctionName  Null-terminated ASCII string of the function
 611                             executing the assert macro.
 612   @param[in]  LineNumber    The source file line number of the assert macro.
 613   @param[in]  FileName      Null-terminated ASCII string of the filename
 614                             executing the assert macro.
 615   @param[in]  DescriptionA  Null-terminated ASCII string that is a description
 616                             of ValueA.
 617   @param[in]  DescriptionB  Null-terminated ASCII string that is a description
 618                             of ValueB.
 619
 620   @retval  TRUE   ValueA is not equal to ValueB.
 621   @retval  FALSE  ValueA is equal to ValueB.
 622 **/
 623 BOOLEAN
 624 EFIAPI
 625 UnitTestAssertNotEqual (
 626   IN UINT64       ValueA,
 627   IN UINT64       ValueB,
 628   IN CONST CHAR8  *FunctionName,
 629   IN UINTN        LineNumber,
 630   IN CONST CHAR8  *FileName,
 631   IN CONST CHAR8  *DescriptionA,
 632   IN CONST CHAR8  *DescriptionB
 633   );
 634
 635 /**
 636   If Status is equal to Expected, then TRUE is returned.
 637   If Status is not equal to Expected, then an assert is triggered and the
 638   location of the assert provided by FunctionName, LineNumber, FileName, and
 639   Description are recorded and FALSE is returned.
 640
 641   @param[in]  Status        EFI_STATUS value returned from an API under test.
 642   @param[in]  Expected      The expected EFI_STATUS return value from an API
 643                             under test.
 644   @param[in]  FunctionName  Null-terminated ASCII string of the function
 645                             executing the assert macro.
 646   @param[in]  LineNumber    The source file line number of the assert macro.
 647   @param[in]  FileName      Null-terminated ASCII string of the filename
 648                             executing the assert macro.
 649   @param[in]  Description   Null-terminated ASCII string that is a description
 650                             of Status.
 651
 652   @retval  TRUE   Status is equal to Expected.
 653   @retval  FALSE  Status is not equal to Expected.
 654 **/
 655 BOOLEAN
 656 EFIAPI
 657 UnitTestAssertStatusEqual (
 658   IN EFI_STATUS   Status,
 659   IN EFI_STATUS   Expected,
 660   IN CONST CHAR8  *FunctionName,
 661   IN UINTN        LineNumber,
 662   IN CONST CHAR8  *FileName,
 663   IN CONST CHAR8  *Description
 664   );
 665
 666 /**
 667   If Pointer is not equal to NULL, then TRUE is returned.
 668   If Pointer is equal to NULL, then an assert is triggered and the location of
 669   the assert provided by FunctionName, LineNumber, FileName, and PointerName
 670   are recorded and FALSE is returned.
 671
 672   @param[in]  Pointer       Pointer value to be checked against NULL.
 673   @param[in]  Expected      The expected EFI_STATUS return value from a function
 674                             under test.
 675   @param[in]  FunctionName  Null-terminated ASCII string of the function
 676                             executing the assert macro.
 677   @param[in]  LineNumber    The source file line number of the assert macro.
 678   @param[in]  FileName      Null-terminated ASCII string of the filename
 679                             executing the assert macro.
 680   @param[in]  PointerName   Null-terminated ASCII string that is a description
 681                             of Pointer.
 682
 683   @retval  TRUE   Pointer is not equal to NULL.
 684   @retval  FALSE  Pointer is equal to NULL.
 685 **/
 686 BOOLEAN
 687 EFIAPI
 688 UnitTestAssertNotNull (
 689   IN VOID         *Pointer,
 690   IN CONST CHAR8  *FunctionName,
 691   IN UINTN        LineNumber,
 692   IN CONST CHAR8  *FileName,
 693   IN CONST CHAR8  *PointerName
 694   );
 695
 696 /**
 697   Test logging macro that records an ERROR message in the test framework log.
 698   Record is associated with the currently executing test case.
 699
 700   @param[in]  Format  Formatting string following the format defined in
 701                       MdePkg/Include/Library/PrintLib.h.
 702   @param[in]  ...     Print args.
 703 **/
 704 #define UT_LOG_ERROR(Format, ...)  \
 705   UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__)
 706
 707 /**
 708   Test logging macro that records a WARNING message in the test framework log.
 709   Record is associated with the currently executing test case.
 710
 711   @param[in]  Format  Formatting string following the format defined in
 712                       MdePkg/Include/Library/PrintLib.h.
 713   @param[in]  ...     Print args.
 714 **/
 715 #define UT_LOG_WARNING(Format, ...)  \
 716   UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__)
 717
 718 /**
 719   Test logging macro that records an INFO message in the test framework log.
 720   Record is associated with the currently executing test case.
 721
 722   @param[in]  Format  Formatting string following the format defined in
 723                       MdePkg/Include/Library/PrintLib.h.
 724   @param[in]  ...     Print args.
 725 **/
 726 #define UT_LOG_INFO(Format, ...)  \
 727   UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__)
 728
 729 /**
 730   Test logging macro that records a VERBOSE message in the test framework log.
 731   Record is associated with the currently executing test case.
 732
 733   @param[in]  Format  Formatting string following the format defined in
 734                       MdePkg/Include/Library/PrintLib.h.
 735   @param[in]  ...     Print args.
 736 **/
 737 #define UT_LOG_VERBOSE(Format, ...)  \
 738   UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__)
 739
 740 /**
 741   Test logging function that records a messages in the test framework log.
 742   Record is associated with the currently executing test case.
 743
 744   @param[in]  ErrorLevel  The error level of the unit test log message.
 745   @param[in]  Format      Formatting string following the format defined in the
 746                           MdePkg/Include/Library/PrintLib.h.
 747   @param[in]  ...         Print args.
 748 **/
 749 VOID
 750 EFIAPI
 751 UnitTestLog (
 752   IN  UINTN        ErrorLevel,
 753   IN  CONST CHAR8  *Format,
 754   ...
 755   );
 756
 757 #endif