EDK2压缩包(edk2.tar.gz)

# Unit Test Framework Package ## About This package provides unit test frameworks capable of building tests for multiple contexts including the UEFI shell environment and host-based environments. It allows for unit test development to focus on the tests and leave error logging, result formatting, context persistence, and test running to the framework. The unit test framework works well for low level unit tests as well as system level tests and fits easily in automation frameworks. ### Framework The first unit test framework is called **Framework** and is implemented as a set of EDK II libraries. The Framework supports both host-based unit tests and target-based unit tests that share the same source style, macros, and APIs. In some scenarios, the same unit test case sources can be built for both host-based unit test execution and target-based unit test execution. Host-based unit tests that require mocked interfaces can use the mocking infrastructure provided by [cmocka](https://api.cmocka.org/) that is included in the UnitTestFrameworkPkg as a submodule. ### GoogleTest The second unit test framework supported by the UnitTestFrameworkPkg is [GoogleTest](http://google.github.io/googletest/) and can be used to implement host-based unit tests. [GoogleTest on GitHub](https://github.com/google/googletest) is included in the UnitTestFrameworkPkg as a submodule. Use of GoogleTest for target-based unit tests of EDK II components is not supported. Host-based unit tests that require mocked interfaces can use the mocking infrastructure included with GoogleTest called [gMock](https://github.com/google/googletest/tree/main/googlemock). Note that the gMock framework does not directly support mocking of free (C style) functions, so the FunctionMockLib (containing a set of macros that wrap gMock's MOCK_METHOD macro) was created within the UnitTestFrameworkPkg to enable this support. The details and usage of these macros in the FunctionMockLib are described later. GoogleTest requires less overhead to register test suites and test cases compared to the Framework. There are also a number of tools that layer on top of GoogleTest that improve developer productivity. One example is the VS Code extension [C++ TestMate](https://marketplace.visualstudio.com/items?itemName=matepek.vscode-catch2-test-adapter) that may be used to implement, run, and debug unit tests implemented using GoogleTest. If a component can be tested with host-based unit tests, then GoogleTest is recommended. The MdePkg contains a port of the BaseSafeIntLib unit tests in the GoogleTest style so the differences between GoogleTest and Framework unit tests can be reviewed. The paths to the BaseSafeIntLib unit tests are: * `MdePkg/Test/UnitTest/Library/BaseSafeIntLib` * `MdePkg/Test/GoogleTest/Library/BaseSafeIntLib` Furthermore, the SecurityPkg contains unit tests for the SecureBootVariableLib using mocks in both the Framework/cmocka and GoogleTest/gMock style so the differences between cmocka and gMock can be reviewed. The paths to the SecureBootVariableLib unit tests are: * `SecurityPkg/Library/SecureBootVariableLib/UnitTest` * `SecurityPkg/Library/SecureBootVariableLib/GoogleTest` ## Framework and GoogleTest Feature Comparison | Feature | Framework | GoogleTest | |:----------------------------|:---------:|:----------:| | Host Based Unit Tests | YES | YES | | Target Based Unit Tests | YES | NO | | Unit Test Source Language | C | C++ | | Register Test Suite | YES | Auto | | Register Test Case | YES | Auto | | Death/Expected Assert Tests | YES | YES | | Setup/Teardown Hooks | YES | YES | | Value-Parameterized Tests | NO | YES | | Typed Tests | NO | YES | | 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 The main "framework" library. The core of the framework is the Framework object, which can have any number of test cases and test suites registered with it. The Framework object is also what drives test execution. The Framework also provides helper macros and functions for checking test conditions and reporting errors. Status and error info will be logged into the test context. There are a number of Assert macros that make the unit test code friendly to view and easy to understand. Finally, the Framework also supports logging strings during the test execution. This data is logged to the test context and will be available in the test reporting phase. This should be used for logging test details and helpful messages to resolve test failures. ### UnitTestPersistenceLib Persistence lib has the main job of saving and restoring test context to a storage medium so that for tests that require exiting the active process and then resuming state can be maintained. This is critical in supporting a system reboot in the middle of a test run. ### UnitTestResultReportLib Library provides function to run at the end of a framework test run and handles formatting the report. This is a common customization point and allows the unit test framework to fit its output reports into other test infrastructure. In this package simple library instances have been supplied to output test results to the console as plain text. ## Framework Samples There is a sample unit test provided as both an example of how to write a unit test and leverage many of the features of the framework. This sample can be found in the `Test/UnitTest/Sample/SampleUnitTest` directory. The sample is provided in PEI, SMM, DXE, and UEFI App flavors. It also has a flavor for the HOST_APPLICATION build type, which can be run on a host system without needing a target. ## Framework Usage This section is built a lot like a "Getting Started". We'll go through some of the components that are needed when constructing a unit test and some of the decisions that are made by the test writer. We'll also describe how to check for expected conditions in test cases and a bit of the logging characteristics. Most of these examples will refer to the `SampleUnitTestUefiShell` app found in this package. ### Framework Requirements - INF In our INF file, we'll need to bring in the `UnitTestLib` library. Conveniently, the interface header for the `UnitTestLib` is located in `MdePkg`, so you shouldn't need to depend on any other packages. As long as your DSC file knows where to find the lib implementation that you want to use, you should be good to go. See this example in `SampleUnitTestUefiShell.inf`... ``` [Packages] MdePkg/MdePkg.dec [LibraryClasses] UefiApplicationEntryPoint BaseLib DebugLib UnitTestLib PrintLib ``` 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`... ``` [Defines] BASE_NAME = SampleUnitTestUefiShell ``` ### Framework Requirements - DSC In our DSC file, we'll need to bring in the INF file that was just created into the `[Components]` section so that the unit tests will be built. See this example in `UnitTestFrameworkPkg.dsc`... ``` [Components] UnitTestFrameworkPkg/Test/UnitTest/Sample/SampleUnitTest/SampleUnitTestUefiShell.inf ``` Also, based on the type of tests that are being created, the associated DSC include file from the UnitTestFrameworkPkg for Host or Target based tests should also be included at the top of the DSC file