Macros
#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

#define	UT_ASSERT_TRUE(Expression)

#define	UT_ASSERT_FALSE(Expression)

#define	UT_ASSERT_EQUAL(ValueA, ValueB)

#define	UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length)

#define	UT_ASSERT_NOT_EQUAL(ValueA, ValueB)

#define	UT_ASSERT_NOT_EFI_ERROR(Status)

#define	UT_ASSERT_STATUS_EQUAL(Status, Expected)

#define	UT_ASSERT_NOT_NULL(Pointer)

#define	UT_EXPECT_ASSERT_FAILURE(FunctionCall, Status) FunctionCall;

#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__)

Typedefs
typedef UINT32	UNIT_TEST_STATUS

typedef struct UNIT_TEST_FRAMEWORK_OBJECT *	UNIT_TEST_FRAMEWORK_HANDLE

typedef struct UNIT_TEST_SUITE_OBJECT *	UNIT_TEST_SUITE_HANDLE

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)

Functions
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, IN UNIT_TEST_SUITE_TEARDOWN Teardown)

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, IN UNIT_TEST_CLEANUP CleanUp, IN UNIT_TEST_CONTEXT Context)

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, IN UINTN ContextToSaveSize)

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)

VOID EFIAPI	UnitTestLog (IN UINTN ErrorLevel, IN CONST CHAR8 *Format,...)

Detailed Description

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

Macro Definition Documentation

#define UNIT_TEST_ERROR_CLEANUP_FAILED (3)

#define UNIT_TEST_ERROR_PREREQUISITE_NOT_MET (1)

#define UNIT_TEST_ERROR_TEST_FAILED (2)

#define UNIT_TEST_LOG_LEVEL_ERROR BIT0

Declare PcdUnitTestLogLevel bits and UnitTestLog() ErrorLevel parameter.

#define UNIT_TEST_LOG_LEVEL_INFO BIT2

#define UNIT_TEST_LOG_LEVEL_VERBOSE BIT3

#define UNIT_TEST_LOG_LEVEL_WARN BIT1

#define UNIT_TEST_PASSED (0)

#define UNIT_TEST_PENDING (0xFFFFFFFF)

#define UNIT_TEST_RUNNING (0xFFFFFFFE)

#define UNIT_TEST_SKIPPED (0xFFFFFFFD)

#define UT_ASSERT_EQUAL	(	ValueA,
		ValueB
	)

Value:

if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
    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.

Parameters

[in]	ValueA	Value to be compared for equality (64-bit comparison).
[in]	ValueB	Value to be compared for equality (64-bit comparison).

#define UT_ASSERT_FALSE ( Expression )

Value:

if(!UnitTestAssertFalse ((Expression), __FUNCTION__, DEBUG_LINE_NUMBER, __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.

Parameters

[in] Expression Expression to be evaluated for FALSE.

#define UT_ASSERT_MEM_EQUAL	(	BufferA,
		BufferB,
		Length
	)

Value:

if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #BufferA, #BufferB)) { \
    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.

Parameters

[in]	BufferA	Pointer to a buffer for comparison.
[in]	BufferB	Pointer to a buffer for comparison.
[in]	Length	Number of bytes to compare in BufferA and BufferB.

#define UT_ASSERT_NOT_EFI_ERROR ( Status )

Value:

if(!UnitTestAssertNotEfiError ((Status), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Status)) { \
    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.

Parameters

[in] Status EFI_STATUS value to check.

#define UT_ASSERT_NOT_EQUAL	(	ValueA,
		ValueB
	)

Value:

if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #ValueA, #ValueB)) { \
    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.

Parameters

[in]	ValueA	Value to be compared for inequality (64-bit comparison).
[in]	ValueB	Value to be compared for inequality (64-bit comparison).

#define UT_ASSERT_NOT_NULL ( Pointer )

Value:

if(!UnitTestAssertNotNull ((Pointer), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Pointer)) { \
    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.

Parameters

[in] Pointer Pointer to be checked against NULL.

#define UT_ASSERT_STATUS_EQUAL	(	Status,
		Expected
	)

Value:

if(!UnitTestAssertStatusEqual ((Status), (Expected), __FUNCTION__, DEBUG_LINE_NUMBER, __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.

Parameters

[in]	Status	EFI_STATUS values to compare for equality.
[in]	Expected	EFI_STATUS values to compare for equality.

#define UT_ASSERT_TRUE ( Expression )

Value:

if(!UnitTestAssertTrue ((Expression), __FUNCTION__, DEBUG_LINE_NUMBER, __FILE__, #Expression)) { \
    return UNIT_TEST_ERROR_TEST_FAILED;                                                            \
  }

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.

Parameters

[in] Expression Expression to be evaluated for TRUE.

#define UT_EXPECT_ASSERT_FAILURE	(	FunctionCall,
		Status
	)	FunctionCall;

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.

Parameters

[in]	FunctionCall	Function call that is expected to trigger ASSERT().
[out]	Status	Pointer to a UNIT_TEST_STATUS return value. This is an optional parameter that may be NULL.

#define UT_LOG_ERROR	(	Format,
		...
	)	UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__)

Test logging macro that records an ERROR message in the test framework log. Record is associated with the currently executing test case.

Parameters

[in]	Format	Formatting string following the format defined in MdePkg/Include/Library/PrintLib.h.
[in]	...	Print args.

#define UT_LOG_INFO	(	Format,
		...
	)	UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, 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.

Parameters

[in]	Format	Formatting string following the format defined in MdePkg/Include/Library/PrintLib.h.
[in]	...	Print args.

#define UT_LOG_VERBOSE	(	Format,
		...
	)	UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, 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.

Parameters

[in]	Format	Formatting string following the format defined in MdePkg/Include/Library/PrintLib.h.
[in]	...	Print args.

#define UT_LOG_WARNING	(	Format,
		...
	)	UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, 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.

Parameters

[in]	Format	Formatting string following the format defined in MdePkg/Include/Library/PrintLib.h.
[in]	...	Print args.

Typedef Documentation

typedef VOID(EFIAPI * UNIT_TEST_CLEANUP)(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.

Parameters

[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.

Return values

UNIT_TEST_PASSED	Test case cleanup succeeded.
UNIT_TEST_ERROR_CLEANUP_FAILED	Test case cleanup failed.

typedef VOID* UNIT_TEST_CONTEXT

Unit Test Context

typedef struct UNIT_TEST_FRAMEWORK_OBJECT* UNIT_TEST_FRAMEWORK_HANDLE

typedef UNIT_TEST_STATUS(EFIAPI * UNIT_TEST_FUNCTION)(IN UNIT_TEST_CONTEXT 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.

Parameters

[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.

Return values

UNIT_TEST_PASSED	The Unit test has completed and the test case was successful.
UNIT_TEST_ERROR_TEST_FAILED	A test case assertion has failed.

typedef struct UNIT_TEST_OBJECT* UNIT_TEST_HANDLE

typedef UNIT_TEST_STATUS(EFIAPI * UNIT_TEST_PREREQUISITE)(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.

Parameters

[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.

Return values

UNIT_TEST_PASSED	Unit test case prerequisites are met.
UNIT_TEST_ERROR_PREREQUISITE_NOT_MET	Test case should be skipped.

typedef UINT32 UNIT_TEST_STATUS

Unit Test Status

typedef struct UNIT_TEST_SUITE_OBJECT* UNIT_TEST_SUITE_HANDLE

typedef VOID(EFIAPI * UNIT_TEST_SUITE_SETUP)(VOID)

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_TEARDOWN)(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.

Function Documentation

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,
		IN UNIT_TEST_CLEANUP	CleanUp,
		IN UNIT_TEST_CONTEXT	Context
	)

Adds test case to Suite

Parameters

[in]	SuiteHandle	Unit test suite to add test to.
[in]	Description	Null-terminated ASCII string that is the user friendly description of a test. String is copied.
[in]	Name	Null-terminated ASCII string that is the short name of the test with no spaces. String is copied.
[in]	Function	Unit test function.
[in]	Prerequisite	Prerequisite function, runs before test. This is an optional parameter that may be NULL.
[in]	CleanUp	Clean up function, runs after test. This is an optional parameter that may be NULL.
[in]	Context	Pointer to context. This is an optional parameter that may be NULL.

Return values

EFI_SUCCESS	The unit test case was added to Suite.
EFI_INVALID_PARAMETER	SuiteHandle is NULL.
EFI_INVALID_PARAMETER	Description is NULL.
EFI_INVALID_PARAMETER	Name is NULL.
EFI_INVALID_PARAMETER	Function is NULL.
EFI_OUT_OF_RESOURCES	There are not enough resources available to add the unit test case to 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,
		IN UNIT_TEST_SUITE_TEARDOWN	Teardown
	)

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.

Parameters

[out]	SuiteHandle	Unit test suite to create
[in]	FrameworkHandle	Unit test framework to add unit test suite to
[in]	Title	Null-terminated ASCII string that is the user friendly name of the test suite. String is copied.
[in]	Name	Null-terminated ASCII string that is the short name of the test suite with no spaces. String is copied.
[in]	Setup	Setup function, runs before suite. This is an optional parameter that may be NULL.
[in]	Teardown	Teardown function, runs after suite. This is an optional parameter that may be NULL.

Return values

EFI_SUCCESS	The unit test suite was created.
EFI_INVALID_PARAMETER	SuiteHandle is NULL.
EFI_INVALID_PARAMETER	FrameworkHandle is NULL.
EFI_INVALID_PARAMETER	Title is NULL.
EFI_INVALID_PARAMETER	Name is NULL.
EFI_OUT_OF_RESOURCES	There are not enough resources available to initialize the unit test suite.

EFI_STATUS EFIAPI FreeUnitTestFramework ( 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.

Parameters

[in] FrameworkHandle A handle to the current running framework that dispatched the test. Necessary for recording certain test events with the framework.

Return values

EFI_SUCCESS	All resources associated with framework were freed.
EFI_INVALID_PARAMETER	FrameworkHandle is NULL.

EFI_STATUS EFIAPI InitUnitTestFramework	(	OUT UNIT_TEST_FRAMEWORK_HANDLE *	FrameworkHandle,
		IN CHAR8 *	Title,
		IN CHAR8 *	ShortTitle,
		IN CHAR8 *	VersionString
	)

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.

Parameters

[out]	FrameworkHandle	Unit test framework to be created.
[in]	Title	Null-terminated ASCII string that is the user friendly name of the framework. String is copied.
[in]	ShortTitle	Null-terminated ASCII short string that is the short name of the framework with no spaces. String is copied.
[in]	VersionString	Null-terminated ASCII version string for the framework. String is copied.

Return values

EFI_SUCCESS	The unit test framework was initialized.
EFI_INVALID_PARAMETER	FrameworkHandle is NULL.
EFI_INVALID_PARAMETER	Title is NULL.
EFI_INVALID_PARAMETER	ShortTitle is NULL.
EFI_INVALID_PARAMETER	VersionString is NULL.
EFI_INVALID_PARAMETER	ShortTitle is invalid.
EFI_OUT_OF_RESOURCES	There are not enough resources available to initialize the unit test framework.

EFI_STATUS EFIAPI RunAllTestSuites ( IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle )

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.

Parameters

[in] FrameworkHandle A handle to the current running framework that dispatched the test. Necessary for recording certain test events with the framework.

Return values

EFI_SUCCESS	All test cases were dispatched.
EFI_INVALID_PARAMETER	FrameworkHandle is NULL.

EFI_STATUS EFIAPI SaveFrameworkState	(	IN UNIT_TEST_CONTEXT	ContextToSave,
		IN UINTN	ContextToSaveSize
	)

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.

Parameters

[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.
[in]	ContextToSaveSize	Size of the ContextToSave buffer.

Return values

EFI_SUCCESS	The framework state and context were saved.
EFI_NOT_FOUND	An active framework handle was not found.
EFI_INVALID_PARAMETER	ContextToSave is not NULL and ContextToSaveSize is 0.
EFI_INVALID_PARAMETER	ContextToSave is >= 4GB.
EFI_OUT_OF_RESOURCES	There are not enough resources available to save the framework and context state.
EFI_DEVICE_ERROR	The framework and context state could not be saved to a persistent storage device due to a device error.

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 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.

Parameters

[in]	ValueA	64-bit value.
[in]	ValueB	64-bit value.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	DescriptionA	Null-terminated ASCII string that is a description of ValueA.
[in]	DescriptionB	Null-terminated ASCII string that is a description of ValueB.

Return values

TRUE	ValueA is equal to ValueB.
FALSE	ValueA is not equal to ValueB.

BOOLEAN EFIAPI UnitTestAssertFalse	(	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.

Parameters

[in]	Expression	The BOOLEAN result of the expression evaluation.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	Description	Null-terminated ASCII string of the expression being evaluated.

Return values

TRUE	Expression is FALSE.
FALSE	Expression is TRUE.

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 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.

Parameters

[in]	BufferA	Pointer to a buffer for comparison.
[in]	BufferB	Pointer to a buffer for comparison.
[in]	Length	Number of bytes to compare in BufferA and BufferB.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	DescriptionA	Null-terminated ASCII string that is a description of BufferA.
[in]	DescriptionB	Null-terminated ASCII string that is a description of BufferB.

Return values

TRUE	The contents of BufferA are identical to the contents of BufferB.
FALSE	The contents of BufferA are not identical to the contents of BufferB.

BOOLEAN EFIAPI UnitTestAssertNotEfiError	(	IN EFI_STATUS	Status,
		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.

Parameters

[in]	Status	The EFI_STATUS value to evaluate.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	Description	Null-terminated ASCII string of the status expression being evaluated.

Return values

TRUE	Status is not an EFI_ERROR().
FALSE	Status is an EFI_ERROR().

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 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.

Parameters

[in]	ValueA	64-bit value.
[in]	ValueB	64-bit value.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	DescriptionA	Null-terminated ASCII string that is a description of ValueA.
[in]	DescriptionB	Null-terminated ASCII string that is a description of ValueB.

Return values

TRUE	ValueA is not equal to ValueB.
FALSE	ValueA is equal to ValueB.

BOOLEAN EFIAPI UnitTestAssertNotNull	(	IN VOID *	Pointer,
		IN CONST CHAR8 *	FunctionName,
		IN UINTN	LineNumber,
		IN CONST CHAR8 *	FileName,
		IN CONST CHAR8 *	PointerName
	)

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.

Parameters

[in]	Pointer	Pointer value to be checked against NULL.
[in]	Expected	The expected EFI_STATUS return value from a function under test.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	PointerName	Null-terminated ASCII string that is a description of Pointer.

Return values

TRUE	Pointer is not equal to NULL.
FALSE	Pointer is equal to NULL.

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 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.

Parameters

[in]	Status	EFI_STATUS value returned from an API under test.
[in]	Expected	The expected EFI_STATUS return value from an API under test.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	Description	Null-terminated ASCII string that is a description of Status.

Return values

TRUE	Status is equal to Expected.
FALSE	Status is not equal to Expected.

BOOLEAN EFIAPI UnitTestAssertTrue	(	IN BOOLEAN	Expression,
		IN CONST CHAR8 *	FunctionName,
		IN UINTN	LineNumber,
		IN CONST CHAR8 *	FileName,
		IN CONST CHAR8 *	Description
	)

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.

Parameters

[in]	Expression	The BOOLEAN result of the expression evaluation.
[in]	FunctionName	Null-terminated ASCII string of the function executing the assert macro.
[in]	LineNumber	The source file line number of the assert macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the assert macro.
[in]	Description	Null-terminated ASCII string of the expression being evaluated.

Return values

TRUE	Expression is TRUE.
FALSE	Expression is FALSE.

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
	)

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.

Parameters

[in]	UnitTestStatus	The status from UT_EXPECT_ASSERT_FAILURE() that is either pass, skipped, or failed.
[in]	FunctionName	Null-terminated ASCII string of the function executing the UT_EXPECT_ASSERT_FAILURE() macro.
[in]	LineNumber	The source file line number of the the function executing the UT_EXPECT_ASSERT_FAILURE() macro.
[in]	FileName	Null-terminated ASCII string of the filename executing the UT_EXPECT_ASSERT_FAILURE() macro.
[in]	FunctionCall	Null-terminated ASCII string of the function call executed by the UT_EXPECT_ASSERT_FAILURE() macro.
[out]	ResultStatus	Used to return the UnitTestStatus value to the caller of UT_EXPECT_ASSERT_FAILURE(). This is optional parameter that may be NULL.

Return values

TRUE	UnitTestStatus is UNIT_TEST_PASSED.
TRUE	UnitTestStatus is UNIT_TEST_SKIPPED.
FALSE	UnitTestStatus is UNIT_TEST_ERROR_TEST_FAILED.

VOID EFIAPI UnitTestLog	(	IN UINTN	ErrorLevel,
		IN CONST CHAR8 *	Format,
			...
	)

Test logging function that records a messages in the test framework log. Record is associated with the currently executing test case.

Parameters

[in]	ErrorLevel	The error level of the unit test log message.
[in]	Format	Formatting string following the format defined in the MdePkg/Include/Library/PrintLib.h.
[in]	...	Print args.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation