Using Code Coverage | Code Coverage | 0.2.3-preview
docs.unity3d.com
    Show / Hide Table of Contents

    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.

    2. 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 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>
    -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
    In This Article
    • Enable Code Coverage
    • Using Code Coverage in batchmode
      • Example
      • Generate combined report from EditMode and PlayMode tests
    • Using Code Coverage with Burst compiler
    • Using Code Coverage with Code Optimization
    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023