UnitTestLib.h

Go to the documentation of this file.

 
#ifndef __UNIT_TEST_LIB_H__
#define __UNIT_TEST_LIB_H__
 
typedef UINT32 UNIT_TEST_STATUS;
#define UNIT_TEST_PASSED                      (0)
#define UNIT_TEST_ERROR_PREREQUISITE_NOT_MET  (1)
#define UNIT_TEST_ERROR_TEST_FAILED           (2)
#define UNIT_TEST_ERROR_CLEANUP_FAILED        (3)
#define UNIT_TEST_SKIPPED                     (0xFFFFFFFD)
#define UNIT_TEST_RUNNING                     (0xFFFFFFFE)
#define UNIT_TEST_PENDING                     (0xFFFFFFFF)
 
#define UNIT_TEST_LOG_LEVEL_ERROR    BIT0
#define UNIT_TEST_LOG_LEVEL_WARN     BIT1
#define UNIT_TEST_LOG_LEVEL_INFO     BIT2
#define UNIT_TEST_LOG_LEVEL_VERBOSE  BIT3
 
struct UNIT_TEST_FRAMEWORK_OBJECT;
typedef struct UNIT_TEST_FRAMEWORK_OBJECT *UNIT_TEST_FRAMEWORK_HANDLE;
 
struct UNIT_TEST_SUITE_OBJECT;
typedef struct UNIT_TEST_SUITE_OBJECT *UNIT_TEST_SUITE_HANDLE;
 
struct UNIT_TEST_OBJECT;
typedef struct UNIT_TEST_OBJECT *UNIT_TEST_HANDLE;
 
typedef VOID *UNIT_TEST_CONTEXT;
 
typedef
UNIT_TEST_STATUS
(EFIAPI *UNIT_TEST_FUNCTION)(
  IN UNIT_TEST_CONTEXT  Context
  );
 
typedef
UNIT_TEST_STATUS
(EFIAPI *UNIT_TEST_PREREQUISITE)(
  IN UNIT_TEST_CONTEXT  Context
  );
 
typedef
VOID
(EFIAPI *UNIT_TEST_CLEANUP)(
  IN UNIT_TEST_CONTEXT  Context
  );
 
typedef
VOID
(EFIAPI *UNIT_TEST_SUITE_SETUP)(
  VOID
  );
 
typedef
VOID
(EFIAPI *UNIT_TEST_SUITE_TEARDOWN)(
  VOID
  );
 
EFI_STATUS
EFIAPI
InitUnitTestFramework (
  OUT UNIT_TEST_FRAMEWORK_HANDLE  *FrameworkHandle,
  IN  CHAR8                       *Title,
  IN  CHAR8                       *ShortTitle,
  IN  CHAR8                       *VersionString
  );
 
EFI_STATUS
EFIAPI
CreateUnitTestSuite (
  OUT UNIT_TEST_SUITE_HANDLE      *SuiteHandle,
  IN  UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,
  IN  CHAR8                       *Title,
  IN  CHAR8                       *Name,
  IN  UNIT_TEST_SUITE_SETUP       Setup     OPTIONAL,
  IN  UNIT_TEST_SUITE_TEARDOWN    Teardown  OPTIONAL
  );
 
EFI_STATUS
EFIAPI
AddTestCase (
  IN UNIT_TEST_SUITE_HANDLE  SuiteHandle,
  IN CHAR8                   *Description,
  IN CHAR8                   *Name,
  IN UNIT_TEST_FUNCTION      Function,
  IN UNIT_TEST_PREREQUISITE  Prerequisite  OPTIONAL,
  IN UNIT_TEST_CLEANUP       CleanUp       OPTIONAL,
  IN UNIT_TEST_CONTEXT       Context       OPTIONAL
  );
 
EFI_STATUS
EFIAPI
RunAllTestSuites (
  IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle
  );
 
EFI_STATUS
EFIAPI
FreeUnitTestFramework (
  IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle
  );
 
EFI_STATUS
EFIAPI
SaveFrameworkState (
  IN UNIT_TEST_CONTEXT  ContextToSave     OPTIONAL,
  IN UINTN              ContextToSaveSize
  );
 
#define UT_ASSERT_TRUE(Expression)                                                                 \
  if(!UnitTestAssertTrue ((Expression), __func__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                            \
  }
 
#define UT_ASSERT_FALSE(Expression)                                                                 \
  if(!UnitTestAssertFalse ((Expression), __func__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                             \
  }
 
#define UT_ASSERT_EQUAL(ValueA, ValueB)                                                                           \
  if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __func__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                                           \
  }
 
#define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length)                                                                                                              \
  if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __func__, DEBUG_LINE_NUMBER, __FILE__, #BufferA, #BufferB)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                                                                                            \
  }
 
#define UT_ASSERT_NOT_EQUAL(ValueA, ValueB)                                                                                       \
  if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __func__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                                                           \
  }
 
#define UT_ASSERT_NOT_EFI_ERROR(Status)                                                           \
  if(!UnitTestAssertNotEfiError ((Status), __func__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                           \
  }
 
#define UT_ASSERT_STATUS_EQUAL(Status, Expected)                                                              \
  if(!UnitTestAssertStatusEqual ((Status), (Expected), __func__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                                       \
  }
 
#define UT_ASSERT_NOT_NULL(Pointer)                                                             \
  if(!UnitTestAssertNotNull ((Pointer), __func__, DEBUG_LINE_NUMBER, __FILE__, #Pointer)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                         \
  }
 
#if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED)
  #include <Library/BaseLib.h>
 
extern BASE_LIBRARY_JUMP_BUFFER  *gUnitTestExpectAssertFailureJumpBuffer;
 
#define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status)               \
    do {                                                               \
      UNIT_TEST_STATUS          UnitTestJumpStatus;                    \
      BASE_LIBRARY_JUMP_BUFFER  UnitTestJumpBuffer;                    \
      UnitTestJumpStatus = UNIT_TEST_SKIPPED;                          \
      if (DebugAssertEnabled ()) {                                     \
        gUnitTestExpectAssertFailureJumpBuffer = &UnitTestJumpBuffer;  \
        if (SetJump (gUnitTestExpectAssertFailureJumpBuffer) == 0) {   \
          FunctionCall;                                                \
          UnitTestJumpStatus = UNIT_TEST_ERROR_TEST_FAILED;            \
        } else {                                                       \
          UnitTestJumpStatus = UNIT_TEST_PASSED;                       \
        }                                                              \
        gUnitTestExpectAssertFailureJumpBuffer = NULL;                 \
      }                                                                \
      if (!UnitTestExpectAssertFailure (                               \
             UnitTestJumpStatus,                                       \
             __func__, DEBUG_LINE_NUMBER, __FILE__,                \
             #FunctionCall, Status)) {                                 \
        return UNIT_TEST_ERROR_TEST_FAILED;                            \
      }                                                                \
    } while (FALSE)
#else
#define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status)  FunctionCall;
#endif
 
BOOLEAN
EFIAPI
UnitTestAssertTrue (
  IN BOOLEAN      Expression,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *Description
  );
 
BOOLEAN
EFIAPI
UnitTestAssertFalse (
  IN BOOLEAN      Expression,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *Description
  );
 
BOOLEAN
EFIAPI
UnitTestAssertNotEfiError (
  IN EFI_STATUS   Status,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *Description
  );
 
BOOLEAN
EFIAPI
UnitTestAssertEqual (
  IN UINT64       ValueA,
  IN UINT64       ValueB,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *DescriptionA,
  IN CONST CHAR8  *DescriptionB
  );
 
BOOLEAN
EFIAPI
UnitTestAssertMemEqual (
  IN VOID         *BufferA,
  IN VOID         *BufferB,
  IN UINTN        Length,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *DescriptionA,
  IN CONST CHAR8  *DescriptionB
  );
 
BOOLEAN
EFIAPI
UnitTestAssertNotEqual (
  IN UINT64       ValueA,
  IN UINT64       ValueB,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *DescriptionA,
  IN CONST CHAR8  *DescriptionB
  );
 
BOOLEAN
EFIAPI
UnitTestAssertStatusEqual (
  IN EFI_STATUS   Status,
  IN EFI_STATUS   Expected,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *Description
  );
 
BOOLEAN
EFIAPI
UnitTestAssertNotNull (
  IN VOID         *Pointer,
  IN CONST CHAR8  *FunctionName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *FileName,
  IN CONST CHAR8  *PointerName
  );
 
BOOLEAN
EFIAPI
UnitTestExpectAssertFailure (
  IN  UNIT_TEST_STATUS  UnitTestStatus,
  IN  CONST CHAR8       *FunctionName,
  IN  UINTN             LineNumber,
  IN  CONST CHAR8       *FileName,
  IN  CONST CHAR8       *FunctionCall,
  OUT UNIT_TEST_STATUS  *ResultStatus  OPTIONAL
  );
 
#define UT_LOG_ERROR(Format, ...)  \
  UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__)
 
#define UT_LOG_WARNING(Format, ...)  \
  UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__)
 
#define UT_LOG_INFO(Format, ...)  \
  UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__)
 
#define UT_LOG_VERBOSE(Format, ...)  \
  UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__)
 
VOID
EFIAPI
UnitTestLog (
  IN  UINTN        ErrorLevel,
  IN  CONST CHAR8  *Format,
  ...
  );
 
#endif