diff --git a/UnitTestFrameworkPkg/ReadMe.md b/UnitTestFrameworkPkg/ReadMe.md index d28cb5cb0a..d8d5d45dc3 100644 --- a/UnitTestFrameworkPkg/ReadMe.md +++ b/UnitTestFrameworkPkg/ReadMe.md @@ -66,11 +66,6 @@ reviewed. The paths to the SecureBootVariableLib unit tests are: | Type-Parameterized Tests | NO | YES | | Timeout Support | NO | YES | | Mocking Support | Cmocka | gMock | -| JUNIT XML Reports | YES | YES | -| Execute subset of tests | NO | YES | -| VS Code Extensions | NO | YES | - -## Framework Libraries ### UnitTestLib @@ -124,7 +119,7 @@ you should be good to go. See this example in `SampleUnitTestUefiShell.inf`... -``` +```inf [Packages] MdePkg/MdePkg.dec @@ -139,7 +134,7 @@ See this example in `SampleUnitTestUefiShell.inf`... Also, if you want your test to automatically be picked up by the Test Runner plugin, you will need to make sure that the module `BASE_NAME` contains the word `Test`... -``` +```inf [Defines] BASE_NAME = SampleUnitTestUefiShell ``` @@ -151,7 +146,7 @@ section so that the unit tests will be built. See this example in `UnitTestFrameworkPkg.dsc`... -``` +```inf [Components] UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestUefiShell.inf ``` @@ -160,7 +155,7 @@ Also, based on the type of tests that are being created, the associated DSC incl UnitTestFrameworkPkg for Host or Target based tests should also be included at the top of the DSC file. -``` +```inf !include UnitTestFrameworkPkg/UnitTestFrameworkPkgTarget.dsc.inc ``` @@ -170,7 +165,7 @@ they should be added in the \ sub-section for the INF file in t See this example in `SecurityPkgHostTest.dsc`... -``` +```inf [Components] SecurityPkg/Library/SecureBootVariableLib/UnitTest/SecureBootVariableLibUnitTest.inf { @@ -326,7 +321,7 @@ Beyond that, if you're writing host-based tests and want to take a dependency on leverage the `cmocka.h` interface and write tests with all the features of the Cmocka framework. Documentation for Cmocka can be found here: -https://api.cmocka.org/ + ## GoogleTest Libraries @@ -354,7 +349,7 @@ the following tables. | Matcher Name | Similar gMock Generic Matcher | Usage | |:--- |:--- |:--- | | `BufferEq()` | `Pointee(Eq())` | Used to compare two buffer pointer types (such as UINT8*, VOID*, a structure pointer, etc.). Can be used in an `EXPECT_CALL()`, `EXPECT_THAT()`, or anywhere else a matcher to compare two buffers is needed. | -| `Char16StrEq()` | `Pointee(Eq())` | Used to compare two CHAR16* strings. Can be used in an `EXPECT_CALL()`, `EXPECT_THAT()`, or anywhere else a matcher to compare two CHAR16* strings is needed. | +| `Char16StrEq()` | `Pointee(Eq())` | Used to compare two CHAR16 string pointers. Can be used in an `EXPECT_CALL()`, `EXPECT_THAT()`, or anywhere else a matcher to compare two CHAR16* strings is needed. | ### FunctionMockLib @@ -370,6 +365,7 @@ the mock functions, and the other two macros are related to creating an interfac to contain the mock functions and connect them into the gMock framework. The macros used to create the interface are... + 1. `MOCK_INTERFACE_DECLARATION(MOCK)` 2. `MOCK_INTERFACE_DEFINITION(MOCK)` @@ -392,6 +388,7 @@ MOCK_INTERFACE_DEFINITION(MockUefiLib); ``` The macros used to create the mock functions are... + 1. `MOCK_FUNCTION_DECLARATION(RET_TYPE, FUNC, ARGS)` 2. `MOCK_FUNCTION_DEFINITION(MOCK, FUNC, NUM_ARGS, CALL_TYPE)` 3. `MOCK_FUNCTION_INTERNAL_DECLARATION(RET_TYPE, FUNC, ARGS)` @@ -839,7 +836,7 @@ the `GoogleTestLib`, and the `[BuildOptions]` will need to append the `/EHsc` compilation flag to all MSFT builds to enable proper use of the C++ exception handler. Below is the complete `MockUefiLib.inf` as an example. -``` +```text [Defines] INF_VERSION = 0x00010005 BASE_NAME = MockUefiLib @@ -874,7 +871,7 @@ if no test uses it yet, this created INF file needs to be added into the which this INF file resides. For example, the above `MockUefiLib.inf` would need to be added to the `MdePkg/Test/MdePkgHostTest.dsc` file as shown below. -``` +```text [Components] MdePkg/Test/Mock/Library/GoogleTest/MockUefiLib/MockUefiLib.inf ``` @@ -892,7 +889,7 @@ locate the mock function header file. For example, if `MockUefiLib.inf` were the first mock added to the `MdePkg`, then the below snippet would need to be added to the `MdePkg.dec` file. -``` +```text [Includes] Test/Mock/Include ``` @@ -912,7 +909,7 @@ mock function definitions file be added to the `[Sources]` section, the Below is a minimal contrived example for a `MyModuleGoogleTest.inf` that uses a `MockMyModuleInternalFunctions.cpp` source file for its internal mock functions. -``` +```text [Defines] INF_VERSION = 0x00010017 BASE_NAME = MyModuleGoogleTest @@ -974,7 +971,7 @@ you should be good to go. See this example in `SampleGoogleTestHost.inf`... -``` +```text [Packages] MdePkg/MdePkg.dec UnitTestFrameworkPkg/UnitTestFrameworkPkg.dec @@ -988,7 +985,7 @@ See this example in `SampleGoogleTestHost.inf`... Also, if you want your test to automatically be picked up by the Test Runner plugin, you will need to make sure that the module `BASE_NAME` contains the word `Test`... -``` +```text [Defines] BASE_NAME = SampleGoogleTestHost ``` @@ -1000,7 +997,7 @@ section so that the unit tests will be built. See this example in `UnitTestFrameworkPkgHostTest.dsc`... -``` +```text [Components] UnitTestFrameworkPkg/Test/GoogleTest/Sample/SampleGoogleTest/SampleGoogleTestHost.inf ``` @@ -1009,7 +1006,7 @@ Also, based on the type of tests that are being created, the associated DSC incl UnitTestFrameworkPkg for Host or Target based tests should also be included at the top of the DSC file. -``` +```text !include UnitTestFrameworkPkg/UnitTestFrameworkPkgHost.dsc.inc ``` @@ -1022,7 +1019,7 @@ See this example in `SecurityPkgHostTest.dsc` where the `SecureBootVariableLib` being tested using mock versions of `UefiRuntimeServicesTableLib`, `PlatformPKProtectionLib`, and `UefiLib`... -``` +```text [Components] SecurityPkg/Library/SecureBootVariableLib/GoogleTest/SecureBootVariableLibGoogleTest.inf { @@ -1469,7 +1466,7 @@ Unit test applications using Framework are built using Cmocka that requires the following environment variables to be set to generate structured XML output rather than text: -``` +```inf CMOCKA_MESSAGE_OUTPUT=xml CMOCKA_XML_FILE= ``` @@ -1477,7 +1474,7 @@ CMOCKA_XML_FILE= Unit test applications using GoogleTest require the following environment variable to be set to generate structured XML output rather than text: -``` +```inf GTEST_OUTPUT=xml: ``` @@ -1490,40 +1487,43 @@ Host based Unit Tests will automatically enable coverage data. For Windows, this is primarily leveraged for pipeline builds, but this can be leveraged locally using the OpenCppCoverage windows tool to parse coverage data to cobertura xml format. -- Windows Prerequisite - ```bash +* Windows Prerequisite + + ```text Download and install https://github.com/OpenCppCoverage/OpenCppCoverage/releases python -m pip install --upgrade -r ./pip-requirements.txt stuart_ci_build -c .pytool/CISettings.py -t NOOPT TOOL_CHAIN_TAG=VS2019 -p MdeModulePkg Open Build/coverage.xml ``` - - How to see code coverage data on IDE Visual Studio - ``` + * How to see code coverage data on IDE Visual Studio + + ```text Open Visual Studio VS2019 or above version Click "Tools" -> "OpenCppCoverage Settings" Fill your execute file into "Program to run:" Click "Tools" -> "Run OpenCppCoverage" ``` - For Linux, this is primarily leveraged for pipeline builds, but this can be leveraged locally using the lcov linux tool, and parsed using the lcov_cobertura python tool to parse it to cobertura xml format. -- Linux Prerequisite +* Linux Prerequisite + ```bash sudo apt-get install -y lcov python -m pip install --upgrade -r ./pip-requirements.txt stuart_ci_build -c .pytool/CISettings.py -t NOOPT TOOL_CHAIN_TAG=GCC5 -p MdeModulePkg Open Build/coverage.xml ``` - - How to see code coverage data on IDE Visual Studio Code - ``` + + * How to see code coverage data on IDE Visual Studio Code + + ```bash Download plugin "Coverage Gutters" Press Hot Key "Ctrl + Shift + P" and click option "Coverage Gutters: Display Coverage" ``` - ### Important Note This works on both Windows and Linux but is currently limited to x64 architectures. Working on getting others, but we @@ -1611,7 +1611,7 @@ Non-Host-Based (PEI/DXE/SMM/Shell) Tests for a Functionality or Feature | Simi GeneralPurposeLib/ # Host-Based Test for any implementation of GeneralPurposeLib GeneralPurposeLibTest.c - GeneralPurposeLibHostUnitTest.inf + GeneralPurposeLibHostUnitTest Mock/ Include/ @@ -1630,14 +1630,15 @@ Non-Host-Based (PEI/DXE/SMM/Shell) Tests for a Functionality or Feature | Simi ### Future Locations in Consideration -We don't know if these types will exist or be applicable yet, but if you write a support library or module that matches the following, please make sure they live in the correct place. +We don't know if these types will exist or be applicable yet, but if you write a support library or module that matches +the following, please make sure they live in the correct place. Code/Test | Location --------- | -------- Host-Based Library Implementations | Host-Based Implementations of common libraries (eg. MemoryAllocationLibHost) should live in the same package that declares the library interface in its .DEC file in the `*Pkg/HostLibrary` directory. Should have 'Host' in the name. Host-Based Mocks and Stubs | Mock and Stub libraries should live in the `UefiTestFrameworkPkg/StubLibrary` with either 'Mock' or 'Stub' in the library name. -### If still in doubt... +### If still in doubt Hop on GitHub and ask @corthon, @mdkinney, or @spbrogan. ;)