Using Code Coverage

Enable Code Coverage

  1. Go to Edit > Preferences > General and check Enable Code Coverage.

    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 and since it is an Editor Preference, if left on it will be enabled in all your projects.

  2. Restart Unity.
    Note: This will not be required in Unity 2020.2 and later versions.

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.
-coverageHistoryPath (optional), to set the location where the coverage report history 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
generateHtmlReport Add this to generate a coverage HTML report.
generateHtmlReportHistory Add this to generate and include the coverage history in the HTML report.
generateBadgeReport Add this to generate coverage summary badges in SVG and PNG format.
generateAdditionalMetrics Add this to generate and include additional metrics in the HTML report. These currently include Cyclomatic Complexity and Crap Score calculations for each method. See the Risk Hotspots section for more information.
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. By default only the assemblies under the Assets folder are included.

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 names
assemblyFilters:+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.tests
assemblyFilters:+my.locale.?? will only inlcude code from assemblies whose names match this format, e.g. my.locale.en, my.locale.99, etc
assemblyFilters:+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 file
pathFilters:-C:/MyProject/Assets/AutoGenerated/* will exclude all files under the C:/MyProject/Assets/AutoGenerated folder
pathFilters:+*/Assets/Editor/* will include just the files that have /Assets/Editor/ in their path
pathFilters:+C:/MyProject/Assets/**/MyClass.cs will include any file named MyClass.cs that is under the C:/MyProject/Assets folder and any of its subfolders
pathFilters:+C:/MyProject/*,-*/Packages/* will only include files under C:/MyProject/ folder and exclude all files under any Packages folder
pathFilters:+*/MyGeneratedClass_??.cs will include only files with filenames that match this format, i.e. MyGeneratedClass_01.cs, MyGeneratedClass_AB.cs, etc
pathFilters:+*/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>
-coverageHistoryPath <path-to-coverage-history>
-coverageOptions generateAdditionalMetrics;generateHtmlReport;generateHtmlReportHistory;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 coverage summary badges in <path-to-coverage-results>. The report will include the coverage history, Cyclomatic Complexity and Crap Score calculations. The coverage history files will be saved in <path-to-coverage-history>. Additionally, 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 generateAdditionalMetrics;assemblyFilters:+my.assembly.*

Unity.exe -projectPath <path-to-project> -batchmode -testPlatform playmode -runTests -debugCodeOptimization -enableCodeCoverage -coverageResultsPath <path-to-coverage-results>
-coverageOptions generateAdditionalMetrics;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 badges 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