Using Code Coverage
Enable Code Coverage
Go to Edit > Preferences > General and check Enable Code Coverage.
This will enable access to the interface for the code coverage data that Mono exposes. For more information, see the documentation on Coverage API. Enabling Code Coverage adds some overhead to the editor and lowers the performance, so it is not recommended to leave it on if you are not performing coverage testing.
Restart Unity.
Using Code Coverage in batchmode
There are 3 arguments that can be passed in batchmode:
-enableCodeCoverage, to enable code coverage.
-coverageResultsPath (optional), to set the location where the coverage results and report will be saved to. The default location is the project's path.
-coverageOptions (optional), to pass extra options. This is semicolon separated.
Coverage Option | Description |
---|---|
enableCyclomaticComplexity |
Add this to enable the Cyclomatic Complexity calculation for each method. See the Risk Hotspots section for more information about Cyclomatic Complexity. |
generateHtmlReport |
Add this to generate a coverage HTML report. |
generateBadgeReport |
Add this to generate a coverage summary badge. |
assemblyFilters |
Add this to specify the assemblies that should be included or excluded in the coverage calculation and/or report. This is a comma separated string. Prefix assemblies with + to include them and with - to exclude them. Globbing can be used to filter the assemblies.Examples: assemblyFilters:+my.assembly will only include code from the assembly called my.assembly assemblyFilters:+unity.* will include code from any assembly whose name starts with unity.assemblyFilters:-*unity* will exclude code from all assemblies that contain the word unity in their namesassemblyFilters:+my.assembly.*,-my.assembly.tests will include code from any assembly whose name starts with my.assembly., but will explicitly exclude code from the assembly called my.assembly.testsassemblyFilters:+my.locale.?? will only inlcude code from assemblies whose names match this format, e.g. my.locale.en, my.locale.99, etcassemblyFilters:+my.assembly.[a-z][0-9] will only inlcude code from assemblies whose names match this format, e.g. my.assembly.a1, my.assembly.q7, etc |
pathFilters |
Add this to specify the paths that should be included or excluded in the coverage calculation and/or report. This is a comma separated string. Prefix paths with + to include them and with - to exclude them. Globbing can be used to filter the paths.Examples: pathFilters:+C:/MyProject/Assets/MyClass.cs will only include the MyClass.cs filepathFilters:-C:/MyProject/Assets/AutoGenerated/* will exclude all files under the C:/MyProject/Assets/AutoGenerated folderpathFilters:+*/Assets/Editor/* will include just the files that have /Assets/Editor/ in their pathpathFilters:+C:/MyProject/Assets/**/MyClass.cs will include any file named MyClass.cs that is under the C:/MyProject/Assets folder and any of its subfolderspathFilters:+C:/MyProject/*,-*/Packages/* will only include files under C:/MyProject/ folder and exclude all files under any Packages folderpathFilters:+*/MyGeneratedClass_??.cs will include only files with filenames that match this format, i.e. MyGeneratedClass_01.cs, MyGeneratedClass_AB.cs, etcpathFilters:+*/MyClass_[A-Z][0-9].cs will include only files with filenames that match this format, i.e. MyClass_A1.cs, MyClass_Q7.cs, etc |
Example
Unity.exe -projectPath <path-to-project> -batchmode -testPlatform editmode -runTests -testResults
<path-to-results-xml> -debugCodeOptimization -enableCodeCoverage -coverageResultsPath <path-to-coverage-results>
-coverageOptions enableCyclomaticComplexity;generateHtmlReport;generateBadgeReport;
assemblyFilters:+my.assembly.*,-UnityEditor*;pathFilters:-*Packages*
The example above will open the project at <path-to-project>, run the EditMode tests and produce an HTML coverage report and Badge in <path-to-coverage-results>. The report will include code from any assembly whose name starts with my.assembly., will explicitly exclude code from any assembly whose name starts with UnityEditor and will exclude files that have Packages in their path (i.e. all the packages under the Packages folder).
Note: -debugCodeOptimization
is passed above to ensure Code optimization is set to Debug mode. See Using Code Coverage with Code Optimization
Generate combined report from EditMode and PlayMode tests
To get coverage information for both EditMode and PlayMode tests, run the editor three times as shown in the example below.
Unity.exe -projectPath <path-to-project> -batchmode -testPlatform editmode -runTests -debugCodeOptimization -enableCodeCoverage -coverageResultsPath <path-to-coverage-results>
-coverageOptions enableCyclomaticComplexity;assemblyFilters:+my.assembly.*
Unity.exe -projectPath <path-to-project> -batchmode -testPlatform playmode -runTests -debugCodeOptimization -enableCodeCoverage -coverageResultsPath <path-to-coverage-results>
-coverageOptions enableCyclomaticComplexity;assemblyFilters:+my.assembly.*
Unity.exe -projectPath <path-to-project> -batchmode -debugCodeOptimization -enableCodeCoverage -coverageResultsPath <path-to-coverage-results>
-coverageOptions generateHtmlReport;generateBadgeReport -quit
The first will generate the coverage results for the EditMode tests, the second will generate the coverage results for the PlayMode tests and the third will generate the coverage report and summary badge based on both coverage results.
Using Code Coverage with Burst compiler
If you use the Burst package and have jobs compiled with Burst, you will need to disable Burst compilation in order to get full coverage. To disable Burst compilation you can do one of the following:
- Uncheck Enable Compilation under Jobs > Burst > Enable Compilation
- Pass
-burst-disable-compilation
to the command line
Using Code Coverage with Code Optimization
Code Optimization was introduced in 2020.1. Code Optimization mode defines whether Unity Editor compiles scripts in Debug or Release mode. Debug mode enables C# debugging and it is required in order to obtain accurate code coverage. To ensure Code optimization is set to Debug mode you can do one of the following:
- Switch to Debug mode in the Editor (bottom right corner, select the Bug icon > Switch to debug mode)
- Using the CompilationPipeline api, set
CompilationPipeline.codeOptimization = CodeOptimization.Debug
- Pass
-debugCodeOptimization
to the command line