Skip to content

Commit

Permalink
UnitTestFrameworkPkg: Fix markdownlint issues
Browse files Browse the repository at this point in the history 
Fixes markdownlint issues introduced from edk2 cherry-picks.

Signed-off-by: Michael Kubacki <[email protected]>
  • Loading branch information
@makubacki @kenlautner
makubacki authored and kenlautner committed Jul 3, 2024
1 parent cf1862f commit 90b8379
Showing 1 changed file with 36 additions and 35 deletions.
71 changes: 36 additions & 35 deletions UnitTestFrameworkPkg/ReadMe.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -124,7 +119,7 @@ you should be good to go.

See this example in `SampleUnitTestUefiShell.inf`...

```
```inf
[Packages]
MdePkg/MdePkg.dec
Expand All @@ -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
```
Expand All @@ -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
```
Expand All @@ -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
```

Expand All @@ -170,7 +165,7 @@ they should be added in the \<LibraryClasses\> sub-section for the INF file in t

See this example in `SecurityPkgHostTest.dsc`...

```
```inf
[Components]
SecurityPkg/Library/SecureBootVariableLib/UnitTest/SecureBootVariableLibUnitTest.inf {
<LibraryClasses>
Expand Down Expand Up @@ -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/
<https://api.cmocka.org/>
## GoogleTest Libraries
Expand Down Expand Up @@ -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
Expand All @@ -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)`
Expand All @@ -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)`
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
```
Expand All @@ -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
```
Expand All @@ -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
Expand Down Expand Up @@ -974,7 +971,7 @@ you should be good to go.

See this example in `SampleGoogleTestHost.inf`...

```
```text
[Packages]
MdePkg/MdePkg.dec
UnitTestFrameworkPkg/UnitTestFrameworkPkg.dec
Expand All @@ -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
```
Expand All @@ -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
```
Expand All @@ -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
```

Expand All @@ -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 {
<LibraryClasses>
Expand Down Expand Up @@ -1469,15 +1466,15 @@ 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=<absolute or relative path to output 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:<absolute or relative path to output file>
```

Expand All @@ -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
Expand Down Expand Up @@ -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/
Expand All @@ -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. ;)
Expand Down

0 comments on commit 90b8379

Please sign in to comment.