---
url: /en/build/internal-steps/testing/coverage.md
---
`testing:coverage`

\==Unit Test Coverage==, calculates the coverage based on unit test result reports and reports badge data.

You can view the coverage badge data of the latest 100 commits by branch in the repository's `Insights` page in the
form of charts.

::::tip
For coverage data reported by pipelines triggered by events related to Pull Requests (except `pull_request.merged`),
switch to the pull request view to see the unit test insights curve.
::::

* [Applicable Events](#testing-coverage-applicable-events)
* [Full Coverage](#testing-coverage-full-coverage)
* [Incremental Coverage](#testing-coverage-incremental-coverage)
* [Parameters](#testing-coverage-parameters)
* [Output Results](#testing-coverage-output)
* [Configuration Examples](#testing-coverage-configuration-examples)

## Applicable Events {#testing-coverage-applicable-events}

[All Events](../../trigger-rule.md#trigger-event)

## Full Coverage {#testing-coverage-full-coverage}

![coverage](//cnb.cool/svg/badge/coverage?message=18.67%25\&color=l2)
![coverage](//cnb.cool/svg/badge/coverage?message=38.67%25\&color=l3)
![coverage](//cnb.cool/svg/badge/coverage?message=58.67%25\&color=l4)
![coverage](//cnb.cool/svg/badge/coverage?message=78.67%25\&color=l5)

Parsed from local coverage report files, currently recognizing the following report formats:

* `json(js)` (recommended)
* `json-summary`
* `lcov` (recommended)
* `jacoco`
* `golang`

## Incremental Coverage {#testing-coverage-incremental-coverage}

![coverage-pr](//cnb.cool/svg/badge/coverage%20%40pr?message=18.67%25\&color=l2)
![coverage-pr](//cnb.cool/svg/badge/coverage%20%40pr?message=38.67%25\&color=l3)
![coverage-pr](//cnb.cool/svg/badge/coverage%20%40pr?message=58.67%25\&color=l4)
![coverage-pr](//cnb.cool/svg/badge/coverage%20%40pr?message=78.67%25\&color=l5)

## Parameters {#testing-coverage-parameters}

The list below gives an overview of all `testing:coverage` parameters.

* [key](#testing-coverage-parameters-key): Coverage data key used to distinguish multiple coverage sets
* [name](#testing-coverage-parameters-name): Coverage name shown in the badge; pairs with `key`
* [pattern](#testing-coverage-parameters-pattern): Glob pattern to locate report files
* [lines](#testing-coverage-parameters-lines): Full-coverage threshold; fails the pipeline if below
* [diffLines](#testing-coverage-parameters-diffLines): Incremental-coverage threshold; fails the pipeline if below
* [allowExts](#testing-coverage-parameters-allowExts):
  Whitelist of file extensions included in the coverage calculation
* [lang](#testing-coverage-parameters-lang): Set to `go` for `golang` reports to avoid calculation errors
* [breakIfNoCoverage](#testing-coverage-parameters-breakIfNoCoverage):
  Whether to fail when no coverage report is found

Detailed descriptions for each parameter are provided below.

### key {#testing-coverage-parameters-key}

* type: `String`
* required: `false`

Coverage data key values, used to distinguish between different types of coverage data, such as frontend, backend, etc.

* Up to `256` characters
* Up to `30` different keys per repository
* When a key is specified, the coverage data is only written into the meta map,
  and the top-level value (default full/incremental coverage) is no longer recorded.
  The default coverage data is only recorded when no key is specified.

### name {#testing-coverage-parameters-name}

* type: `String`
* required: `false`

Coverage data names, used for display in badges, correspond one-to-one with coverage data keys.
When a key does not exist, the name will be ignored.

For example: `key: frontend`, `name: frontend coverage`

### pattern {#testing-coverage-parameters-pattern}

* type: `String`
* required: `false`

In Glob format, specifies the location of the coverage report file relative to the current working directory.
If not provided, it will try to find the following files in the current directory (including subdirectories):
coverage.json, jacoco\*.xml, lcov.info,\*.lcov.

### lines {#testing-coverage-parameters-lines}

* type: `Number`
* required: `false`

Specifies the full coverage red line. If the full coverage percentage is less than this value,
the workflow will be blocked from exiting the pipeline.

### diffLines {#testing-coverage-parameters-diffLines}

* type: `Number`
* required: `false`

Specifies the incremental coverage red line. If the incremental coverage percentage is less than this value,
the workflow will be blocked from exiting the pipeline. Events like `pull_request`, `pull_request.update`,
`pull_request.target` support calculating incremental coverage results, while other events only calculate full coverage.

### allowExts {#testing-coverage-parameters-allowExts}

* type: `String`
* required: `false`

Whitelist of code file types to be included in coverage calculation, separated by commas, e.g., `.json`, `.ts`, `.js`.
If not provided, all files in the report will be included in the calculation.

### lang {#testing-coverage-parameters-lang}

* type: `String`
* required: `false`

When the coverage report target format is `golang`, specify this parameter as `go` to avoid calculation errors.
This parameter can be ignored in other cases.

### breakIfNoCoverage {#testing-coverage-parameters-breakIfNoCoverage}

* type: `Boolean`
* required: `false`

Whether to throw an error and terminate the process if no coverage report file is found.

## Output Results {#testing-coverage-output}

```json
{
  // Code line coverage, e.g., 100. Value is NA if calculation fails.
  "lines": 100,
  // Incremental code line coverage, e.g., 100. Value is NA if calculation fails.
  "diff_pct": 100
}
```

## Configuration Examples {#testing-coverage-configuration-examples}

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: coverage
          type: testing:coverage
          options:
            breakIfNoCoverage: false
          exports:
            lines: LINES
        - name: result
          script: echo $LINES
```