#include <PiPei.h>
#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/DebugLib.h>
#include <Library/UnitTestLib.h>
#include <Library/PrintLib.h>

Macros
#define	UNIT_TEST_NAME "Sample Unit Test Expect Fail"

#define	UNIT_TEST_VERSION "0.1"

Functions
UNIT_TEST_STATUS EFIAPI	MakeSureThatPointerIsNull (IN UNIT_TEST_CONTEXT Context)

VOID EFIAPI	ClearThePointer (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	OnePlusOneShouldEqualTwo (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	GlobalBooleanShouldBeChangeable (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	GlobalPointerShouldBeChangeable (IN UNIT_TEST_CONTEXT Context)

VOID EFIAPI	TestSuiteEnableAsserts (VOID)

VOID EFIAPI	TestSuiteDisableAsserts (VOID)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertTrue (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertFalse (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertEqual (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertMemEqual (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertNotEqual (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertNotEfiError (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertStatusEqual (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtAssertNotNull (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtExpectAssertFailure (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	GenerateUnexpectedAssert (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtLogError (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtLogWarning (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtLogInfo (IN UNIT_TEST_CONTEXT Context)

UNIT_TEST_STATUS EFIAPI	MacroUtLogVerbose (IN UNIT_TEST_CONTEXT Context)

EFI_STATUS EFIAPI	UefiTestMain (VOID)

EFI_STATUS EFIAPI	PeiEntryPoint (IN EFI_PEI_FILE_HANDLE FileHandle, IN CONST EFI_PEI_SERVICES **PeiServices)

EFI_STATUS EFIAPI	DxeEntryPoint (IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)

int	main (int argc, char *argv[])

Variables
BOOLEAN	mSampleGlobalTestBoolean = FALSE

VOID *	mSampleGlobalTestPointer = NULL

Detailed Description

This is a sample to demonstrate the usage of the Unit Test Library that supports the PEI, DXE, SMM, UEFI Shell, and host execution environments. All test case are always expected to fail to demonstrate the format of the log file and reports when failures occur.

Copyright (c) 2024, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file SampleUnitTestExpectFail.c.

Macro Definition Documentation

◆ UNIT_TEST_NAME

#define UNIT_TEST_NAME "Sample Unit Test Expect Fail"

Definition at line 18 of file SampleUnitTestExpectFail.c.

◆ UNIT_TEST_VERSION

#define UNIT_TEST_VERSION "0.1"

Definition at line 19 of file SampleUnitTestExpectFail.c.

Function Documentation

◆ ClearThePointer()

VOID EFIAPI ClearThePointer ( IN UNIT_TEST_CONTEXT Context )

Sample Unit-Test Cleanup (after) function that resets the global pointer to NULL.

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.

Definition at line 82 of file SampleUnitTestExpectFail.c.

◆ DxeEntryPoint()

EFI_STATUS EFIAPI DxeEntryPoint	(	IN EFI_HANDLE	ImageHandle,
		IN EFI_SYSTEM_TABLE *	SystemTable
	)

Standard UEFI entry point for target based unit test execution from DXE, SMM, UEFI Shell.

Definition at line 843 of file SampleUnitTestExpectFail.c.

◆ GenerateUnexpectedAssert()

UNIT_TEST_STATUS EFIAPI GenerateUnexpectedAssert ( IN UNIT_TEST_CONTEXT Context )

Sample unit test the triggers an unexpected ASSERT()

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.

Definition at line 553 of file SampleUnitTestExpectFail.c.

◆ GlobalBooleanShouldBeChangeable()

UNIT_TEST_STATUS EFIAPI GlobalBooleanShouldBeChangeable ( IN UNIT_TEST_CONTEXT Context )

Sample unit test that verifies that a global BOOLEAN is updatable.

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.

Definition at line 141 of file SampleUnitTestExpectFail.c.

◆ GlobalPointerShouldBeChangeable()

UNIT_TEST_STATUS EFIAPI GlobalPointerShouldBeChangeable ( IN UNIT_TEST_CONTEXT Context )

Sample unit test that logs a warning message and verifies that a global pointer is updatable.

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.

Definition at line 172 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertEqual()

UNIT_TEST_STATUS EFIAPI MacroUtAssertEqual ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_EQUAL() macro.

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.

Definition at line 307 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertFalse()

UNIT_TEST_STATUS EFIAPI MacroUtAssertFalse ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_FALSE() macro.

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.

Definition at line 270 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertMemEqual()

UNIT_TEST_STATUS EFIAPI MacroUtAssertMemEqual ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_MEM_EQUAL() macro.

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.

Definition at line 344 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertNotEfiError()

UNIT_TEST_STATUS EFIAPI MacroUtAssertNotEfiError ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_NOT_EFI_ERROR() macro.

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.

Definition at line 417 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertNotEqual()

UNIT_TEST_STATUS EFIAPI MacroUtAssertNotEqual ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_NOT_EQUAL() macro.

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.

Definition at line 380 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertNotNull()

UNIT_TEST_STATUS EFIAPI MacroUtAssertNotNull ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_NOT_NULL() macro.

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.

Definition at line 480 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertStatusEqual()

UNIT_TEST_STATUS EFIAPI MacroUtAssertStatusEqual ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_STATUS_EQUAL() macro.

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.

Definition at line 451 of file SampleUnitTestExpectFail.c.

◆ MacroUtAssertTrue()

UNIT_TEST_STATUS EFIAPI MacroUtAssertTrue ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_ASSERT_TRUE() macro.

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.

Definition at line 233 of file SampleUnitTestExpectFail.c.

◆ MacroUtExpectAssertFailure()

UNIT_TEST_STATUS EFIAPI MacroUtExpectAssertFailure ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_EXPECT_ASSERT_FAILURE() macro.

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.

Definition at line 509 of file SampleUnitTestExpectFail.c.

◆ MacroUtLogError()

UNIT_TEST_STATUS EFIAPI MacroUtLogError ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_LOG_ERROR() macro.

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.

Definition at line 592 of file SampleUnitTestExpectFail.c.

◆ MacroUtLogInfo()

UNIT_TEST_STATUS EFIAPI MacroUtLogInfo ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_LOG_INFO() macro.

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.

Definition at line 654 of file SampleUnitTestExpectFail.c.

◆ MacroUtLogVerbose()

UNIT_TEST_STATUS EFIAPI MacroUtLogVerbose ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_LOG_VERBOSE() macro.

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.

Definition at line 685 of file SampleUnitTestExpectFail.c.

◆ MacroUtLogWarning()

UNIT_TEST_STATUS EFIAPI MacroUtLogWarning ( IN UNIT_TEST_CONTEXT Context )

Sample unit test using the UT_LOG_WARNING() macro.

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.

Definition at line 623 of file SampleUnitTestExpectFail.c.

◆ main()

int main	(	int	argc,
		char *	argv[]
	)

Standard POSIX C entry point for host based unit test execution.

Definition at line 855 of file SampleUnitTestExpectFail.c.

◆ MakeSureThatPointerIsNull()

UNIT_TEST_STATUS EFIAPI MakeSureThatPointerIsNull ( IN UNIT_TEST_CONTEXT Context )

Sample Unit-Test Prerequisite Function that checks to make sure the global pointer used in the test is already set to NULL.

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.

Definition at line 50 of file SampleUnitTestExpectFail.c.

◆ OnePlusOneShouldEqualTwo()

UNIT_TEST_STATUS EFIAPI OnePlusOneShouldEqualTwo ( IN UNIT_TEST_CONTEXT Context )

Sample unit test that verifies the expected result of an unsigned integer addition operation.

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.

Definition at line 107 of file SampleUnitTestExpectFail.c.

◆ PeiEntryPoint()

EFI_STATUS EFIAPI PeiEntryPoint	(	IN EFI_PEI_FILE_HANDLE	FileHandle,
		IN CONST EFI_PEI_SERVICES **	PeiServices
	)

Standard PEIM entry point for target based unit test execution from PEI.

Definition at line 829 of file SampleUnitTestExpectFail.c.

◆ TestSuiteDisableAsserts()

VOID EFIAPI TestSuiteDisableAsserts ( VOID )

Unit-Test Test Suite Setup (before) function that disables ASSERT() macros.

Definition at line 206 of file SampleUnitTestExpectFail.c.

◆ TestSuiteEnableAsserts()

VOID EFIAPI TestSuiteEnableAsserts ( VOID )

Unit-Test Test Suite Setup (before) function that enables ASSERT() macros.

Definition at line 191 of file SampleUnitTestExpectFail.c.

◆ UefiTestMain()

EFI_STATUS EFIAPI UefiTestMain ( VOID )

Initialize the unit test framework, suite, and unit tests for the sample unit tests and run the unit tests.

Return values

EFI_SUCCESS	All test cases were dispatched.
EFI_OUT_OF_RESOURCES	There are not enough resources available to initialize the unit tests.

Definition at line 709 of file SampleUnitTestExpectFail.c.

Variable Documentation

◆ mSampleGlobalTestBoolean

BOOLEAN mSampleGlobalTestBoolean = FALSE

Global variables used in unit tests

Definition at line 24 of file SampleUnitTestExpectFail.c.

◆ mSampleGlobalTestPointer

VOID* mSampleGlobalTestPointer = NULL

Definition at line 25 of file SampleUnitTestExpectFail.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ UNIT_TEST_NAME

◆ UNIT_TEST_VERSION

Function Documentation

◆ ClearThePointer()

◆ DxeEntryPoint()

◆ GenerateUnexpectedAssert()

◆ GlobalBooleanShouldBeChangeable()

◆ GlobalPointerShouldBeChangeable()

◆ MacroUtAssertEqual()

◆ MacroUtAssertFalse()

◆ MacroUtAssertMemEqual()

◆ MacroUtAssertNotEfiError()

◆ MacroUtAssertNotEqual()

◆ MacroUtAssertNotNull()

◆ MacroUtAssertStatusEqual()

◆ MacroUtAssertTrue()

◆ MacroUtExpectAssertFailure()

◆ MacroUtLogError()

◆ MacroUtLogInfo()

◆ MacroUtLogVerbose()

◆ MacroUtLogWarning()

◆ main()

◆ MakeSureThatPointerIsNull()

◆ OnePlusOneShouldEqualTwo()

◆ PeiEntryPoint()

◆ TestSuiteDisableAsserts()

◆ TestSuiteEnableAsserts()

◆ UefiTestMain()

Variable Documentation

◆ mSampleGlobalTestBoolean

◆ mSampleGlobalTestPointer