UnitTestFrameworkPkg/UnitTestLib: Add checks for ASSERT()

REF: REF: https://bugzilla.tianocore.org/show_bug.cgi?id=2801

Add UnitTestDebugAssertLib that provides the UnitTestDebugAssert()
service and the gUnitTestExpectAssertFailureJumpBuffer global
variable.  This NULL library is linked against all host and target
unit test builds.  This guarantees that the UnitTestDebugAssert()
service is available to link against all libraries and modules that
use the DebugLib class.

EDKII_UNIT_TEST_FRAMEWORK_ENABLED must always be defined when
building unit tests so the behavior of the DebugLib ASSERT()
macros can be adjusted to allow the unit test framework to
catch an ASSERT() if it is triggered by a function under test.

Cc: Sean Brogan <sean.brogan@microsoft.com>
Cc: Bret Barkelew <Bret.Barkelew@microsoft.com>
Cc: Jiewen Yao <jiewen.yao@intel.com>
Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
Reviewed-by: Bret Barkelew <Bret.Barkelew@microsoft.com>
This commit is contained in:
Michael D Kinney 2020-06-10 17:57:16 -07:00 committed by mergify[bot]
parent 425df6923e
commit 26824851b0
11 changed files with 308 additions and 50 deletions

@ -0,0 +1,49 @@
/** @file
Unit Test Debug Assert Library
Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent
**/
#include <Uefi.h>
#include <Library/BaseLib.h>
#include <Library/UnitTestLib.h>
///
/// Point to jump buffer used with SetJump()/LongJump() to test if a function
/// under test generates an expected ASSERT() condition.
///
BASE_LIBRARY_JUMP_BUFFER *gUnitTestExpectAssertFailureJumpBuffer = NULL;
/**
Unit test library replacement for DebugAssert() in DebugLib.
If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
@param FileName The pointer to the name of the source file that generated the assert condition.
@param LineNumber The line number in the source file that generated the assert condition
@param Description The pointer to the description of the assert condition.
**/
VOID
EFIAPI
UnitTestDebugAssert (
IN CONST CHAR8 *FileName,
IN UINTN LineNumber,
IN CONST CHAR8 *Description
)
{
CHAR8 Message[256];
if (gUnitTestExpectAssertFailureJumpBuffer != NULL) {
UT_LOG_INFO ("Detected expected ASSERT: %a(%d): %a\n", FileName, LineNumber, Description);
LongJump (gUnitTestExpectAssertFailureJumpBuffer, 1);
} else {
AsciiStrCpyS (Message, sizeof(Message), "Detected unexpected ASSERT(");
AsciiStrCatS (Message, sizeof(Message), Description);
AsciiStrCatS (Message, sizeof(Message), ")");
UnitTestAssertTrue (FALSE, "", LineNumber, FileName, Message);
}
}

@ -0,0 +1,31 @@
## @file
# Unit Test Debug Assert Library
#
# Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
# SPDX-License-Identifier: BSD-2-Clause-Patent
#
##
[Defines]
INF_VERSION = 0x00010005
BASE_NAME = UnitTestDebugAssertLib
MODULE_UNI_FILE = UnitTestDebugAssertLib.uni
FILE_GUID = 9D53AD0D-5416-451F-A5BF-E5420051A99B
MODULE_TYPE = BASE
VERSION_STRING = 1.0
LIBRARY_CLASS = NULL
#
# VALID_ARCHITECTURES = IA32 X64 ARM AARCH64
#
[Sources]
UnitTestDebugAssertLib.c
[Packages]
MdePkg/MdePkg.dec
UnitTestFrameworkPkg/UnitTestFrameworkPkg.dec
[LibraryClasses]
BaseLib
UnitTestLib

@ -0,0 +1,11 @@
// /** @file
// Unit Test Debug Assert Library
//
// Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
// SPDX-License-Identifier: BSD-2-Clause-Patent
//
// **/
#string STR_MODULE_ABSTRACT #language en-US "Unit Test Debug Assert Library"
#string STR_MODULE_DESCRIPTION #language en-US "Unit Test Debug Assert Library"

@ -13,6 +13,8 @@
#include <Library/DebugLib.h>
#include <Library/PrintLib.h>
extern BASE_LIBRARY_JUMP_BUFFER gUnitTestJumpBuffer;
STATIC
EFI_STATUS
AddUnitTestFailure (
@ -71,7 +73,7 @@ UnitTestLogFailure (
FailureType
);
return;
LongJump (&gUnitTestJumpBuffer, 1);
}
/**
@ -103,15 +105,15 @@ UnitTestAssertTrue (
)
{
if (!Expression) {
UnitTestLogFailure (
FAILURETYPE_ASSERTTRUE,
"%a:%d: Expression (%a) is not TRUE!\n",
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Expression (%a) is not TRUE!\n",
FileName,
LineNumber,
Description
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Expression (%a) is not TRUE!\n",
UnitTestLogFailure (
FAILURETYPE_ASSERTTRUE,
"%a:%d: Expression (%a) is not TRUE!\n",
FileName,
LineNumber,
Description
@ -149,15 +151,15 @@ UnitTestAssertFalse (
)
{
if (Expression) {
UnitTestLogFailure (
FAILURETYPE_ASSERTFALSE,
"%a:%d: Expression(%a) is not FALSE!\n",
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Expression (%a) is not FALSE!\n",
FileName,
LineNumber,
Description
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Expression (%a) is not FALSE!\n",
UnitTestLogFailure (
FAILURETYPE_ASSERTFALSE,
"%a:%d: Expression(%a) is not FALSE!\n",
FileName,
LineNumber,
Description
@ -195,16 +197,16 @@ UnitTestAssertNotEfiError (
)
{
if (EFI_ERROR (Status)) {
UnitTestLogFailure (
FAILURETYPE_ASSERTNOTEFIERROR,
"%a:%d: Status '%a' is EFI_ERROR (%r)!\n",
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Status '%a' is EFI_ERROR (%r)!\n",
FileName,
LineNumber,
Description,
Status
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Status '%a' is EFI_ERROR (%r)!\n",
UnitTestLogFailure (
FAILURETYPE_ASSERTNOTEFIERROR,
"%a:%d: Status '%a' is EFI_ERROR (%r)!\n",
FileName,
LineNumber,
Description,
@ -248,9 +250,8 @@ UnitTestAssertEqual (
)
{
if (ValueA != ValueB) {
UnitTestLogFailure (
FAILURETYPE_ASSERTEQUAL,
"%a:%d: Value %a != %a (%d != %d)!\n",
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Value %a != %a (%d != %d)!\n",
FileName,
LineNumber,
DescriptionA,
@ -258,8 +259,9 @@ UnitTestAssertEqual (
ValueA,
ValueB
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Value %a != %a (%d != %d)!\n",
UnitTestLogFailure (
FAILURETYPE_ASSERTEQUAL,
"%a:%d: Value %a != %a (%d != %d)!\n",
FileName,
LineNumber,
DescriptionA,
@ -310,17 +312,17 @@ UnitTestAssertMemEqual (
)
{
if (CompareMem(BufferA, BufferB, Length) != 0) {
UnitTestLogFailure (
FAILURETYPE_ASSERTEQUAL,
"%a:%d: Memory at %a != %a for length %d bytes!\n",
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Value %a != %a for length %d bytes!\n",
FileName,
LineNumber,
DescriptionA,
DescriptionB,
Length
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Value %a != %a for length %d bytes!\n",
UnitTestLogFailure (
FAILURETYPE_ASSERTEQUAL,
"%a:%d: Memory at %a != %a for length %d bytes!\n",
FileName,
LineNumber,
DescriptionA,
@ -366,9 +368,8 @@ UnitTestAssertNotEqual (
)
{
if (ValueA == ValueB) {
UnitTestLogFailure (
FAILURETYPE_ASSERTNOTEQUAL,
"%a:%d: Value %a == %a (%d == %d)!\n",
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Value %a == %a (%d == %d)!\n",
FileName,
LineNumber,
DescriptionA,
@ -376,8 +377,9 @@ UnitTestAssertNotEqual (
ValueA,
ValueB
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Value %a == %a (%d == %d)!\n",
UnitTestLogFailure (
FAILURETYPE_ASSERTNOTEQUAL,
"%a:%d: Value %a == %a (%d == %d)!\n",
FileName,
LineNumber,
DescriptionA,
@ -421,17 +423,17 @@ UnitTestAssertStatusEqual (
)
{
if (Status != Expected) {
UnitTestLogFailure (
FAILURETYPE_ASSERTSTATUSEQUAL,
"%a:%d: Status '%a' is %r, should be %r!\n",
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Status '%a' is %r, should be %r!\n",
FileName,
LineNumber,
Description,
Status,
Expected
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Status '%a' is %r, should be %r!\n",
UnitTestLogFailure (
FAILURETYPE_ASSERTSTATUSEQUAL,
"%a:%d: Status '%a' is %r, should be %r!\n",
FileName,
LineNumber,
Description,
@ -473,6 +475,12 @@ UnitTestAssertNotNull (
)
{
if (Pointer == NULL) {
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Pointer (%a) is NULL!\n",
FileName,
LineNumber,
PointerName
);
UnitTestLogFailure (
FAILURETYPE_ASSERTNOTNULL,
"%a:%d: Pointer (%a) is NULL!\n",
@ -480,12 +488,83 @@ UnitTestAssertNotNull (
LineNumber,
PointerName
);
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Pointer (%a) is NULL!\n",
FileName,
LineNumber,
PointerName
);
}
return (Pointer != NULL);
}
/**
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
)
{
if (ResultStatus != NULL) {
*ResultStatus = UnitTestStatus;
}
if (UnitTestStatus == UNIT_TEST_PASSED) {
UT_LOG_INFO (
"[ASSERT PASS] %a:%d: UT_EXPECT_ASSERT_FAILURE(%a) detected expected assert\n",
FileName,
LineNumber,
FunctionCall
);
}
if (UnitTestStatus == UNIT_TEST_SKIPPED) {
UT_LOG_WARNING (
"[ASSERT WARN] %a:%d: UT_EXPECT_ASSERT_FAILURE(%a) disabled\n",
FileName,
LineNumber,
FunctionCall
);
}
if (UnitTestStatus == UNIT_TEST_ERROR_TEST_FAILED) {
UT_LOG_ERROR (
"[ASSERT FAIL] %a:%d: Function call (%a) did not ASSERT()!\n",
FileName,
LineNumber,
FunctionCall
);
UnitTestLogFailure (
FAILURETYPE_EXPECTASSERT,
"%a:%d: Function call (%a) did not ASSERT()!\n",
FileName,
LineNumber,
FunctionCall
);
}
return (UnitTestStatus != UNIT_TEST_ERROR_TEST_FAILED);
}

@ -333,3 +333,71 @@ UnitTestAssertNotNull (
return (Pointer != NULL);
}
/**
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
)
{
CHAR8 TempStr[MAX_STRING_SIZE];
if (ResultStatus != NULL) {
*ResultStatus = UnitTestStatus;
}
if (UnitTestStatus == UNIT_TEST_PASSED) {
UT_LOG_INFO (
"[ASSERT PASS] %a:%d: UT_EXPECT_ASSERT_FAILURE(%a) detected expected assert\n",
FileName,
LineNumber,
FunctionCall
);
}
if (UnitTestStatus == UNIT_TEST_SKIPPED) {
UT_LOG_WARNING (
"[ASSERT WARN] %a:%d: UT_EXPECT_ASSERT_FAILURE(%a) disabled\n",
FileName,
LineNumber,
FunctionCall
);
}
if (UnitTestStatus == UNIT_TEST_ERROR_TEST_FAILED) {
snprintf (TempStr, sizeof(TempStr), "UT_EXPECT_ASSERT_FAILURE(%s) did not trigger ASSERT()", FunctionCall);
_assert_true (FALSE, TempStr, FileName, (INT32)LineNumber);
}
return (UnitTestStatus != UNIT_TEST_ERROR_TEST_FAILED);
}

@ -14,6 +14,8 @@
STATIC UNIT_TEST_FRAMEWORK_HANDLE mFrameworkHandle = NULL;
BASE_LIBRARY_JUMP_BUFFER gUnitTestJumpBuffer;
UNIT_TEST_FRAMEWORK_HANDLE
GetActiveFrameworkHandle (
VOID
@ -75,7 +77,14 @@ RunTestSuite (
// Next, if we're still running, make sure that our test prerequisites are in place.
if (Test->Result == UNIT_TEST_PENDING && Test->Prerequisite != NULL) {
DEBUG ((DEBUG_VERBOSE, "PREREQ\n"));
if (Test->Prerequisite (Test->Context) != UNIT_TEST_PASSED) {
if (SetJump (&gUnitTestJumpBuffer) == 0) {
if (Test->Prerequisite (Test->Context) != UNIT_TEST_PASSED) {
DEBUG ((DEBUG_ERROR, "Prerequisite Not Met\n"));
Test->Result = UNIT_TEST_ERROR_PREREQUISITE_NOT_MET;
ParentFramework->CurrentTest = NULL;
continue;
}
} else {
DEBUG ((DEBUG_ERROR, "Prerequisite Not Met\n"));
Test->Result = UNIT_TEST_ERROR_PREREQUISITE_NOT_MET;
ParentFramework->CurrentTest = NULL;
@ -88,14 +97,20 @@ RunTestSuite (
// We set the status to UNIT_TEST_RUNNING in case the test needs to reboot
// or quit. The UNIT_TEST_RUNNING state will allow the test to resume
// but will prevent the Prerequisite from being dispatched a second time.
Test->Result = UNIT_TEST_RUNNING;
Test->Result = Test->RunTest (Test->Context);
if (SetJump (&gUnitTestJumpBuffer) == 0) {
Test->Result = UNIT_TEST_RUNNING;
Test->Result = Test->RunTest (Test->Context);
} else {
Test->Result = UNIT_TEST_ERROR_TEST_FAILED;
}
//
// Finally, clean everything up, if need be.
if (Test->CleanUp != NULL) {
DEBUG ((DEBUG_VERBOSE, "CLEANUP\n"));
Test->CleanUp (Test->Context);
if (SetJump (&gUnitTestJumpBuffer) == 0) {
Test->CleanUp (Test->Context);
}
}
//

@ -49,7 +49,8 @@ struct _UNIT_TEST_FAILURE_TYPE_STRING mFailureTypeStrings[] = {
{ FAILURETYPE_ASSERTNOTEQUAL, "ASSERT_NOTEQUAL FAILURE"},
{ FAILURETYPE_ASSERTNOTEFIERROR, "ASSERT_NOTEFIERROR FAILURE"},
{ FAILURETYPE_ASSERTSTATUSEQUAL, "ASSERT_STATUSEQUAL FAILURE"},
{ FAILURETYPE_ASSERTNOTNULL , "ASSERT_NOTNULL FAILURE"},
{ FAILURETYPE_ASSERTNOTNULL, "ASSERT_NOTNULL FAILURE"},
{ FAILURETYPE_EXPECTASSERT, "EXPECT_ASSERT FAILURE"},
{ 0, "*UNKNOWN* Failure"}
};

@ -44,6 +44,7 @@ typedef UINT32 FAILURE_TYPE;
#define FAILURETYPE_ASSERTNOTEFIERROR (6)
#define FAILURETYPE_ASSERTSTATUSEQUAL (7)
#define FAILURETYPE_ASSERTNOTNULL (8)
#define FAILURETYPE_EXPECTASSERT (9)
///
/// Unit Test context structure tracked by the unit test framework.

@ -25,7 +25,7 @@
UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestHost.inf
#
# Build Libraries
# Build HOST_APPLICATION Libraries
#
UnitTestFrameworkPkg/Library/CmockaLib/CmockaLib.inf
UnitTestFrameworkPkg/Library/Posix/DebugLibPosix/DebugLibPosix.inf

@ -28,6 +28,7 @@
UnitTestFrameworkPkg/Library/UnitTestResultReportLib/UnitTestResultReportLibConOut.inf
UnitTestFrameworkPkg/Library/UnitTestBootLibUsbClass/UnitTestBootLibUsbClass.inf
UnitTestFrameworkPkg/Library/UnitTestPersistenceLibSimpleFileSystem/UnitTestPersistenceLibSimpleFileSystem.inf
UnitTestFrameworkPkg/Library/UnitTestDebugAssertLib/UnitTestDebugAssertLib.inf
UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestDxe.inf
UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestPei.inf

@ -29,6 +29,7 @@
UnitTestLib|UnitTestFrameworkPkg/Library/UnitTestLib/UnitTestLib.inf
UnitTestPersistenceLib|UnitTestFrameworkPkg/Library/UnitTestPersistenceLibNull/UnitTestPersistenceLibNull.inf
UnitTestResultReportLib|UnitTestFrameworkPkg/Library/UnitTestResultReportLib/UnitTestResultReportLibDebugLib.inf
NULL|UnitTestFrameworkPkg/Library/UnitTestDebugAssertLib/UnitTestDebugAssertLib.inf
[LibraryClasses.ARM, LibraryClasses.AARCH64]
#
@ -56,5 +57,6 @@
gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0x17
[BuildOptions]
MSFT:*_*_*_CC_FLAGS = -D DISABLE_NEW_DEPRECATED_INTERFACES
GCC:*_*_*_CC_FLAGS = -D DISABLE_NEW_DEPRECATED_INTERFACES
MSFT:*_*_*_CC_FLAGS = -D DISABLE_NEW_DEPRECATED_INTERFACES -D EDKII_UNIT_TEST_FRAMEWORK_ENABLED
GCC:*_*_*_CC_FLAGS = -D DISABLE_NEW_DEPRECATED_INTERFACES -D EDKII_UNIT_TEST_FRAMEWORK_ENABLED
XCODE:*_*_*_CC_FLAGS = -D DISABLE_NEW_DEPRECATED_INTERFACES -D EDKII_UNIT_TEST_FRAMEWORK_ENABLED