/** @file
Provides a unit test framework. This allows tests to focus on testing logic
and the framework to focus on runnings, reporting, statistics, etc.
Copyright (c) Microsoft Corporation.
Copyright (c) 2020, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent
**/
#ifndef __UNIT_TEST_LIB_H__
#define __UNIT_TEST_LIB_H__
///
/// Unit Test Status
///
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)
///
/// Declare PcdUnitTestLogLevel bits and UnitTestLog() ErrorLevel parameter.
///
#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
///
/// Unit Test Framework Handle
///
struct UNIT_TEST_FRAMEWORK_OBJECT;
typedef struct UNIT_TEST_FRAMEWORK_OBJECT *UNIT_TEST_FRAMEWORK_HANDLE;
///
/// Unit Test Suite Handle
///
struct UNIT_TEST_SUITE_OBJECT;
typedef struct UNIT_TEST_SUITE_OBJECT *UNIT_TEST_SUITE_HANDLE;
///
/// Unit Test Handle
///
struct UNIT_TEST_OBJECT;
typedef struct UNIT_TEST_OBJECT *UNIT_TEST_HANDLE;
///
/// Unit Test Context
///
typedef VOID* UNIT_TEST_CONTEXT;
/**
The prototype for a single UnitTest case function.
Functions with this prototype are registered to be dispatched by the
UnitTest framework, and results are recorded as test Pass or Fail.
@param[in] Context [Optional] An optional parameter that enables:
1) test-case reuse with varied parameters and
2) test-case re-entry for Target tests that need a
reboot. This parameter is a VOID* and it is the
responsibility of the test author to ensure that the
contents are well understood by all test cases that may
consume it.
@retval UNIT_TEST_PASSED The Unit test has completed and the test
case was successful.
@retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed.
**/
typedef
UNIT_TEST_STATUS
(EFIAPI *UNIT_TEST_FUNCTION)(
IN UNIT_TEST_CONTEXT Context
);
/**
Unit-Test Prerequisite Function pointer type.
Functions with this prototype are registered to be dispatched by the unit test
framework prior to a given test case. If this prereq function returns
UNIT_TEST_ERROR_PREREQUISITE_NOT_MET, the test case will be skipped.
@param[in] Context [Optional] An optional parameter that enables:
1) test-case reuse with varied parameters and
2) test-case re-entry for Target tests that need a
reboot. This parameter is a VOID* and it is the
responsibility of the test author to ensure that the
contents are well understood by all test cases that may
consume it.
@retval UNIT_TEST_PASSED Unit test case prerequisites
are met.
@retval UNIT_TEST_ERROR_PREREQUISITE_NOT_MET Test case should be skipped.
**/
typedef
UNIT_TEST_STATUS
(EFIAPI *UNIT_TEST_PREREQUISITE)(
IN UNIT_TEST_CONTEXT Context
);
/**
Unit-Test Cleanup (after) function pointer type.
Functions with this prototype are registered to be dispatched by the
unit test framework after a given test case. This will be called even if the
test case returns an error, but not if the prerequisite fails and the test is
skipped. The purpose of this function is to clean up any global state or
test data.
@param[in] Context [Optional] An optional parameter that enables:
1) test-case reuse with varied parameters and
2) test-case re-entry for Target tests that need a
reboot. This parameter is a VOID* and it is the
responsibility of the test author to ensure that the
contents are well understood by all test cases that may
consume it.
@retval UNIT_TEST_PASSED Test case cleanup succeeded.
@retval UNIT_TEST_ERROR_CLEANUP_FAILED Test case cleanup failed.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_CLEANUP)(
IN UNIT_TEST_CONTEXT Context
);
/**
Unit-Test Test Suite Setup (before) function pointer type. Functions with this
prototype are registered to be dispatched by the UnitTest framework prior to
running any of the test cases in a test suite. It will only be run once at
the beginning of the suite (not prior to each case).
The purpose of this function is to set up any global state or test data.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_SUITE_SETUP)(
VOID
);
/**
Unit-Test Test Suite Teardown (after) function pointer type. Functions with
this prototype are registered to be dispatched by the UnitTest framework after
running all of the test cases in a test suite. It will only be run once at
the end of the suite.
The purpose of this function is to clean up any global state or test data.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_SUITE_TEARDOWN)(
VOID
);
/**
Method to Initialize the Unit Test framework. This function registers the
test name and also initializes the internal state of the test framework to
receive any new suites and tests.
@param[out] FrameworkHandle Unit test framework to be created.
@param[in] Title Null-terminated ASCII string that is the user
friendly name of the framework. String is
copied.
@param[in] ShortTitle Null-terminated ASCII short string that is the
short name of the framework with no spaces.
String is copied.
@param[in] VersionString Null-terminated ASCII version string for the
framework. String is copied.
@retval EFI_SUCCESS The unit test framework was initialized.
@retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
@retval EFI_INVALID_PARAMETER Title is NULL.
@retval EFI_INVALID_PARAMETER ShortTitle is NULL.
@retval EFI_INVALID_PARAMETER VersionString is NULL.
@retval EFI_INVALID_PARAMETER ShortTitle is invalid.
@retval EFI_OUT_OF_RESOURCES There are not enough resources available to
initialize the unit test framework.
**/
EFI_STATUS
EFIAPI
InitUnitTestFramework (
OUT UNIT_TEST_FRAMEWORK_HANDLE *FrameworkHandle,
IN CHAR8 *Title,
IN CHAR8 *ShortTitle,
IN CHAR8 *VersionString
);
/**
Registers a Unit Test Suite in the Unit Test Framework.
At least one test suite must be registered, because all test cases must be
within a unit test suite.
@param[out] SuiteHandle Unit test suite to create
@param[in] FrameworkHandle Unit test framework to add unit test suite to
@param[in] Title Null-terminated ASCII string that is the user
friendly name of the test suite. String is
copied.
@param[in] Name Null-terminated ASCII string that is the short
name of the test suite with no spaces. String
is copied.
@param[in] Setup Setup function, runs before suite. This is an
optional parameter that may be NULL.
@param[in] Teardown Teardown function, runs after suite. This is an
optional parameter that may be NULL.
@retval EFI_SUCCESS The unit test suite was created.
@retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
@retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
@retval EFI_INVALID_PARAMETER Title is NULL.
@retval EFI_INVALID_PARAMETER Name is NULL.
@retval EFI_OUT_OF_RESOURCES There are not enough resources available to
initialize the unit test suite.
**/
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
);
/**
Adds test case to Suite
@param[in] SuiteHandle Unit test suite to add test to.
@param[in] Description Null-terminated ASCII string that is the user
friendly description of a test. String is copied.
@param[in] Name Null-terminated ASCII string that is the short name
of the test with no spaces. String is copied.
@param[in] Function Unit test function.
@param[in] Prerequisite Prerequisite function, runs before test. This is
an optional parameter that may be NULL.
@param[in] CleanUp Clean up function, runs after test. This is an
optional parameter that may be NULL.
@param[in] Context Pointer to context. This is an optional parameter
that may be NULL.
@retval EFI_SUCCESS The unit test case was added to Suite.
@retval EFI_INVALID_PARAMETER SuiteHandle is NULL.
@retval EFI_INVALID_PARAMETER Description is NULL.
@retval EFI_INVALID_PARAMETER Name is NULL.
@retval EFI_INVALID_PARAMETER Function is NULL.
@retval EFI_OUT_OF_RESOURCES There are not enough resources available to
add the unit test case to Suite.
**/
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
);
/**
Execute all unit test cases in all unit test suites added to a Framework.
Once a unit test framework is initialized and all unit test suites and unit
test cases are registered, this function will cause the unit test framework to
dispatch all unit test cases in sequence and record the results for reporting.
@param[in] FrameworkHandle A handle to the current running framework that
dispatched the test. Necessary for recording
certain test events with the framework.
@retval EFI_SUCCESS All test cases were dispatched.
@retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
**/
EFI_STATUS
EFIAPI
RunAllTestSuites (
IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
);
/**
Cleanup a test framework.
After tests are run, this will teardown the entire framework and free all
allocated data within.
@param[in] FrameworkHandle A handle to the current running framework that
dispatched the test. Necessary for recording
certain test events with the framework.
@retval EFI_SUCCESS All resources associated with framework were
freed.
@retval EFI_INVALID_PARAMETER FrameworkHandle is NULL.
**/
EFI_STATUS
EFIAPI
FreeUnitTestFramework (
IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
);
/**
Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're
a framework author) to save the state of the executing framework along with
any allocated data so that the test may be resumed upon reentry. A test case
should pass any needed context (which, to prevent an infinite loop, should be
at least the current execution count) which will be saved by the framework and
passed to the test case upon resume.
This should be called while the current test framework is valid and active. It is
generally called from within a test case prior to quitting or rebooting.
@param[in] ContextToSave A buffer of test case-specific data to be saved
along with framework state. Will be passed as
"Context" to the test case upon resume. This
is an optional parameter that may be NULL.
@param[in] ContextToSaveSize Size of the ContextToSave buffer.
@retval EFI_SUCCESS The framework state and context were saved.
@retval EFI_NOT_FOUND An active framework handle was not found.
@retval EFI_INVALID_PARAMETER ContextToSave is not NULL and
ContextToSaveSize is 0.
@retval EFI_INVALID_PARAMETER ContextToSave is >= 4GB.
@retval EFI_OUT_OF_RESOURCES There are not enough resources available to
save the framework and context state.
@retval EFI_DEVICE_ERROR The framework and context state could not be
saved to a persistent storage device due to a
device error.
**/
EFI_STATUS
EFIAPI
SaveFrameworkState (
IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL,
IN UINTN ContextToSaveSize
);
/**
This macro uses the framework assertion logic to check an expression for
"TRUE". If the expression evaluates to TRUE, execution continues.
Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] Expression Expression to be evaluated for TRUE.
**/
#define UT_ASSERT_TRUE(Expression) \
if(!UnitTestAssertTrue ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check an expression for
"FALSE". If the expression evaluates to FALSE, execution continues.
Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] Expression Expression to be evaluated for FALSE.
**/
#define UT_ASSERT_FALSE(Expression) \
if(!UnitTestAssertFalse ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check whether two simple
values are equal. If the values are equal, execution continues.
Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] ValueA Value to be compared for equality (64-bit comparison).
@param[in] ValueB Value to be compared for equality (64-bit comparison).
**/
#define UT_ASSERT_EQUAL(ValueA, ValueB) \
if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check whether two memory
buffers are equal. If the buffers are equal, execution continues.
Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] BufferA Pointer to a buffer for comparison.
@param[in] BufferB Pointer to a buffer for comparison.
@param[in] Length Number of bytes to compare in BufferA and BufferB.
**/
#define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length) \
if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __FUNCTION__, __LINE__, __FILE__, #BufferA, #BufferB)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check whether two simple
values are non-equal. If the values are non-equal, execution continues.
Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] ValueA Value to be compared for inequality (64-bit comparison).
@param[in] ValueB Value to be compared for inequality (64-bit comparison).
**/
#define UT_ASSERT_NOT_EQUAL(ValueA, ValueB) \
if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check whether an EFI_STATUS
value is !EFI_ERROR(). If the status is !EFI_ERROR(), execution continues.
Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] Status EFI_STATUS value to check.
**/
#define UT_ASSERT_NOT_EFI_ERROR(Status) \
if(!UnitTestAssertNotEfiError ((Status), __FUNCTION__, __LINE__, __FILE__, #Status)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check whether two EFI_STATUS
values are equal. If the values are equal, execution continues.
Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] Status EFI_STATUS values to compare for equality.
@param[in] Expected EFI_STATUS values to compare for equality.
**/
#define UT_ASSERT_STATUS_EQUAL(Status, Expected) \
if(!UnitTestAssertStatusEqual ((Status), (Expected), __FUNCTION__, __LINE__, __FILE__, #Status)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check whether a pointer is
not NULL. If the pointer is not NULL, execution continues. Otherwise, the
test case immediately returns UNIT_TEST_ERROR_TEST_FAILED.
@param[in] Pointer Pointer to be checked against NULL.
**/
#define UT_ASSERT_NOT_NULL(Pointer) \
if(!UnitTestAssertNotNull ((Pointer), __FUNCTION__, __LINE__, __FILE__, #Pointer)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
}
/**
This macro uses the framework assertion logic to check whether a function call
triggers an ASSERT() condition. The BaseLib SetJump()/LongJump() services
are used to establish a safe return point when an ASSERT() is triggered.
If an ASSERT() is triggered, unit test execution continues and Status is set
to UNIT_TEST_PASSED. Otherwise, a unit test case failure is raised and
Status is set to UNIT_TEST_ERROR_TEST_FAILED.
If ASSERT() macros are disabled, then the test case is skipped and a warning
message is added to the unit test log. Status is set to UNIT_TEST_SKIPPED.
@param[in] FunctionCall Function call that is expected to trigger ASSERT().
@param[out] Status Pointer to a UNIT_TEST_STATUS return value. This
is an optional parameter that may be NULL.
**/
#if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED)
#include
///
/// Pointer to jump buffer used with SetJump()/LongJump() to test if a
/// function under test generates an expected ASSERT() condition.
///
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, \
__FUNCTION__, __LINE__, __FILE__, \
#FunctionCall, Status)) { \
return UNIT_TEST_ERROR_TEST_FAILED; \
} \
} while (FALSE)
#else
#define UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) FunctionCall;
#endif
/**
If Expression is TRUE, then TRUE is returned.
If Expression is FALSE, then an assert is triggered and the location of the
assert provided by FunctionName, LineNumber, FileName, and Description are
recorded and FALSE is returned.
@param[in] Expression The BOOLEAN result of the expression evaluation.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] Description Null-terminated ASCII string of the expression being
evaluated.
@retval TRUE Expression is TRUE.
@retval FALSE Expression is FALSE.
**/
BOOLEAN
EFIAPI
UnitTestAssertTrue (
IN BOOLEAN Expression,
IN CONST CHAR8 *FunctionName,
IN UINTN LineNumber,
IN CONST CHAR8 *FileName,
IN CONST CHAR8 *Description
);
/**
If Expression is FALSE, then TRUE is returned.
If Expression is TRUE, then an assert is triggered and the location of the
assert provided by FunctionName, LineNumber, FileName, and Description are
recorded and FALSE is returned.
@param[in] Expression The BOOLEAN result of the expression evaluation.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] Description Null-terminated ASCII string of the expression being
evaluated.
@retval TRUE Expression is FALSE.
@retval FALSE Expression is TRUE.
**/
BOOLEAN
EFIAPI
UnitTestAssertFalse (
IN BOOLEAN Expression,
IN CONST CHAR8 *FunctionName,
IN UINTN LineNumber,
IN CONST CHAR8 *FileName,
IN CONST CHAR8 *Description
);
/**
If Status is not an EFI_ERROR(), then TRUE is returned.
If Status is an EFI_ERROR(), then an assert is triggered and the location of
the assert provided by FunctionName, LineNumber, FileName, and Description are
recorded and FALSE is returned.
@param[in] Status The EFI_STATUS value to evaluate.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] Description Null-terminated ASCII string of the status
expression being evaluated.
@retval TRUE Status is not an EFI_ERROR().
@retval FALSE Status is an EFI_ERROR().
**/
BOOLEAN
EFIAPI
UnitTestAssertNotEfiError (
IN EFI_STATUS Status,
IN CONST CHAR8 *FunctionName,
IN UINTN LineNumber,
IN CONST CHAR8 *FileName,
IN CONST CHAR8 *Description
);
/**
If ValueA is equal ValueB, then TRUE is returned.
If ValueA is not equal to ValueB, then an assert is triggered and the location
of the assert provided by FunctionName, LineNumber, FileName, DescriptionA,
and DescriptionB are recorded and FALSE is returned.
@param[in] ValueA 64-bit value.
@param[in] ValueB 64-bit value.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] DescriptionA Null-terminated ASCII string that is a description
of ValueA.
@param[in] DescriptionB Null-terminated ASCII string that is a description
of ValueB.
@retval TRUE ValueA is equal to ValueB.
@retval FALSE ValueA is not equal to ValueB.
**/
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
);
/**
If the contents of BufferA are identical to the contents of BufferB, then TRUE
is returned. If the contents of BufferA are not identical to the contents of
BufferB, then an assert is triggered and the location of the assert provided
by FunctionName, LineNumber, FileName, DescriptionA, and DescriptionB are
recorded and FALSE is returned.
@param[in] BufferA Pointer to a buffer for comparison.
@param[in] BufferB Pointer to a buffer for comparison.
@param[in] Length Number of bytes to compare in BufferA and BufferB.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] DescriptionA Null-terminated ASCII string that is a description
of BufferA.
@param[in] DescriptionB Null-terminated ASCII string that is a description
of BufferB.
@retval TRUE The contents of BufferA are identical to the contents of
BufferB.
@retval FALSE The contents of BufferA are not identical to the contents of
BufferB.
**/
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
);
/**
If ValueA is not equal ValueB, then TRUE is returned.
If ValueA is equal to ValueB, then an assert is triggered and the location
of the assert provided by FunctionName, LineNumber, FileName, DescriptionA
and DescriptionB are recorded and FALSE is returned.
@param[in] ValueA 64-bit value.
@param[in] ValueB 64-bit value.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] DescriptionA Null-terminated ASCII string that is a description
of ValueA.
@param[in] DescriptionB Null-terminated ASCII string that is a description
of ValueB.
@retval TRUE ValueA is not equal to ValueB.
@retval FALSE ValueA is equal to ValueB.
**/
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
);
/**
If Status is equal to Expected, then TRUE is returned.
If Status is not equal to Expected, then an assert is triggered and the
location of the assert provided by FunctionName, LineNumber, FileName, and
Description are recorded and FALSE is returned.
@param[in] Status EFI_STATUS value returned from an API under test.
@param[in] Expected The expected EFI_STATUS return value from an API
under test.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] Description Null-terminated ASCII string that is a description
of Status.
@retval TRUE Status is equal to Expected.
@retval FALSE Status is not equal to Expected.
**/
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
);
/**
If Pointer is not equal to NULL, then TRUE is returned.
If Pointer is equal to NULL, then an assert is triggered and the location of
the assert provided by FunctionName, LineNumber, FileName, and PointerName
are recorded and FALSE is returned.
@param[in] Pointer Pointer value to be checked against NULL.
@param[in] Expected The expected EFI_STATUS return value from a function
under test.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the assert macro.
@param[in] LineNumber The source file line number of the assert macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the assert macro.
@param[in] PointerName Null-terminated ASCII string that is a description
of Pointer.
@retval TRUE Pointer is not equal to NULL.
@retval FALSE Pointer is equal to NULL.
**/
BOOLEAN
EFIAPI
UnitTestAssertNotNull (
IN VOID *Pointer,
IN CONST CHAR8 *FunctionName,
IN UINTN LineNumber,
IN CONST CHAR8 *FileName,
IN CONST CHAR8 *PointerName
);
/**
If UnitTestStatus is UNIT_TEST_PASSED, then log an info message and return
TRUE because an ASSERT() was expected when FunctionCall was executed and an
ASSERT() was triggered. If UnitTestStatus is UNIT_TEST_SKIPPED, then log a
warning message and return TRUE because ASSERT() macros are disabled. If
UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED, then log an error message and
return FALSE because an ASSERT() was expected when FunctionCall was executed,
but no ASSERT() conditions were triggered. The log messages contain
FunctionName, LineNumber, and FileName strings to provide the location of the
UT_EXPECT_ASSERT_FAILURE() macro.
@param[in] UnitTestStatus The status from UT_EXPECT_ASSERT_FAILURE() that
is either pass, skipped, or failed.
@param[in] FunctionName Null-terminated ASCII string of the function
executing the UT_EXPECT_ASSERT_FAILURE() macro.
@param[in] LineNumber The source file line number of the the function
executing the UT_EXPECT_ASSERT_FAILURE() macro.
@param[in] FileName Null-terminated ASCII string of the filename
executing the UT_EXPECT_ASSERT_FAILURE() macro.
@param[in] FunctionCall Null-terminated ASCII string of the function call
executed by the UT_EXPECT_ASSERT_FAILURE() macro.
@param[out] ResultStatus Used to return the UnitTestStatus value to the
caller of UT_EXPECT_ASSERT_FAILURE(). This is
optional parameter that may be NULL.
@retval TRUE UnitTestStatus is UNIT_TEST_PASSED.
@retval TRUE UnitTestStatus is UNIT_TEST_SKIPPED.
@retval FALSE UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED.
**/
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
);
/**
Test logging macro that records an ERROR message in the test framework log.
Record is associated with the currently executing test case.
@param[in] Format Formatting string following the format defined in
MdePkg/Include/Library/PrintLib.h.
@param[in] ... Print args.
**/
#define UT_LOG_ERROR(Format, ...) \
UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__)
/**
Test logging macro that records a WARNING message in the test framework log.
Record is associated with the currently executing test case.
@param[in] Format Formatting string following the format defined in
MdePkg/Include/Library/PrintLib.h.
@param[in] ... Print args.
**/
#define UT_LOG_WARNING(Format, ...) \
UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__)
/**
Test logging macro that records an INFO message in the test framework log.
Record is associated with the currently executing test case.
@param[in] Format Formatting string following the format defined in
MdePkg/Include/Library/PrintLib.h.
@param[in] ... Print args.
**/
#define UT_LOG_INFO(Format, ...) \
UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__)
/**
Test logging macro that records a VERBOSE message in the test framework log.
Record is associated with the currently executing test case.
@param[in] Format Formatting string following the format defined in
MdePkg/Include/Library/PrintLib.h.
@param[in] ... Print args.
**/
#define UT_LOG_VERBOSE(Format, ...) \
UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__)
/**
Test logging function that records a messages in the test framework log.
Record is associated with the currently executing test case.
@param[in] ErrorLevel The error level of the unit test log message.
@param[in] Format Formatting string following the format defined in the
MdePkg/Include/Library/PrintLib.h.
@param[in] ... Print args.
**/
VOID
EFIAPI
UnitTestLog (
IN UINTN ErrorLevel,
IN CONST CHAR8 *Format,
...
);
#endif