[edk2-devel] [Patch 03/11] MdePkg/Include/Library: Add UnitTestLib class
Wu, Hao A
hao.a.wu at intel.com
Fri Feb 7 01:22:21 UTC 2020
A couple of typos (some of them occur multiple times) in UnitTestLib.h:
Funtions -> Functions
paramter -> parameter
Null-terminaled -> Null-terminated
dispached -> dispatched
storage devide -> storage device
With them addressed,
Reviewed-by: Hao A Wu <hao.a.wu at intel.com>
Best Regards,
Hao Wu
> -----Original Message-----
> From: devel at edk2.groups.io [mailto:devel at edk2.groups.io] On Behalf Of
> Michael D Kinney
> Sent: Friday, January 24, 2020 10:10 AM
> To: devel at edk2.groups.io
> Cc: Bret Barkelew; Sean Brogan; Bret Barkelew; Gao, Liming
> Subject: [edk2-devel] [Patch 03/11] MdePkg/Include/Library: Add UnitTestLib
> class
>
> From: Bret Barkelew <brbarkel at microsoft.com>
>
> Add UnitTestLib class to MdePkg that provides services
> and macros to implement unit tests. These services and
> macros support the following features:
>
> * Create a Unit Test Framework
> * Add a Unit Test Suite to a Unit Test Framework
> + Support optional step that executes before a Unit
> Test Suite is started.
> + Support optional step that executes after a Unit
> Test Suite is finished.
> * Add a Unit Test to a Unit Test Suite
> + Support optional step that executes before a Unit
> Test is started.
> + Support optional step that executes after a Unit
> Test is finished.
> * Run all unit tests added to a Unit Test Framework
> * Save Unit Test Framework state to persistent storage
> * Support assertion checks in a unit test for TRUE, FALSE,
> EQUAL, MEM_EQUAL, NOT_EFI_ERROR, STATUS_EQUAL, and NOT_NULL.
> * Support generation of log messages at ERROR, WARN, INFO,
> and VERBOSE levels.
>
> Cc: Sean Brogan <sean.brogan at microsoft.com>
> Cc: Bret Barkelew <Bret.Barkelew at microsoft.com>
> Cc: Liming Gao <liming.gao at intel.com>
> Signed-off-by: Michael D Kinney <michael.d.kinney at intel.com>
> ---
> MdePkg/Include/Library/UnitTestLib.h | 757
> +++++++++++++++++++++++++++
> MdePkg/MdePkg.dec | 4 +
> 2 files changed, 761 insertions(+)
> create mode 100644 MdePkg/Include/Library/UnitTestLib.h
>
> diff --git a/MdePkg/Include/Library/UnitTestLib.h
> b/MdePkg/Include/Library/UnitTestLib.h
> new file mode 100644
> index 0000000000..757ebaf6ba
> --- /dev/null
> +++ b/MdePkg/Include/Library/UnitTestLib.h
> @@ -0,0 +1,757 @@
> +/** @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.<BR>
> + Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
> + 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.
> +
> + Funtions 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 paramter 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.
> +
> + Funtions 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 paramter 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.
> +
> + Funtions 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 paramter 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. Funtions 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. Funtions 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-terminaled ASCII short string that is the
> + short name of the framework with no spaces.
> + String is copied.
> + @param[in] VersionString Null-terminaled 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 dispached.
> + @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.
> +
> + Generally called from within a test case prior to quitting or rebooting.
> +
> + @param[in] FrameworkHandle A handle to the current running
> framework that
> + dispatched the test. Necessary for recording
> + certain test events with the framework.
> + @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_INVALID_PARAMETER FrameworkHandle is NULL.
> + @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 devide due to a
> + device error.
> +**/
> +EFI_STATUS
> +EFIAPI
> +SaveFrameworkState (
> + IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle,
> + 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; \
> + }
> +
> +/**
> + 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
> + );
> +
> +/**
> + 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
> diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
> index d022cc5e3e..ac1f5339af 100644
> --- a/MdePkg/MdePkg.dec
> +++ b/MdePkg/MdePkg.dec
> @@ -244,6 +244,10 @@ [LibraryClasses]
> ## @libraryclass Module entry point library for standalone MM drivers.
>
> StandaloneMmDriverEntryPoint|Include/Library/StandaloneMmDriverEntryP
> oint.h
>
> + ## @libraryclass Provides a unit test framework
> + #
> + UnitTestLib|Include/Library/UnitTestLib.h
> +
> [LibraryClasses.IA32, LibraryClasses.X64]
> ## @libraryclass Abstracts both S/W SMI generation and detection.
> ##
> --
> 2.21.0.windows.1
>
>
>
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#53934): https://edk2.groups.io/g/devel/message/53934
Mute This Topic: https://groups.io/mt/70061162/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-
More information about the edk2-devel-archive
mailing list