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

\==单测覆盖率==，通过单测结果报告，计算单测覆盖率结果，并上报徽章数据。

可以在仓库的 `洞察` 页面以图表的形式按分支查看
最近 100 个 Commit 的覆盖率徽章数据上报结果。

::::tip
Pull Request 相关事件（除了 `pull_request.merged`）触发的流水线报告的覆盖率数据，
要查看单元测试洞察曲线，需要切换到合并请求视图。
::::

* [适用事件](#testing-coverage-applicable-events)
* [全量覆盖率](#testing-coverage-full-coverage)
* [增量覆盖率](#testing-coverage-incremental-coverage)
* [参数](#testing-coverage-parameters)
* [输出结果](#testing-coverage-output)
* [配置样例](#testing-coverage-configuration-examples)

## 适用事件 {#testing-coverage-applicable-events}

[所有事件](../../trigger-rule.md#trigger-event)

## 全量覆盖率 {#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)

从本地覆盖率报告文件解析而来，目前可识别以下格式的报告：

* `json(js)`（推荐使用）
* `json-summary`
* `lcov`（推荐使用）
* `jacoco`
* `golang`

## 增量覆盖率 {#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)

## 参数 {#testing-coverage-parameters}

以下列表先概览 `testing:coverage` 的全部参数。

* [key](#testing-coverage-parameters-key)：覆盖率数据 key，用于区分多类覆盖率数据
* [name](#testing-coverage-parameters-name)：覆盖率数据名称，展示在徽章中，与 `key` 对应
* [pattern](#testing-coverage-parameters-pattern)：Glob 格式指定报告文件位置
* [lines](#testing-coverage-parameters-lines)：全量覆盖率红线，低于则阻断流水线
* [diffLines](#testing-coverage-parameters-diffLines)：增量覆盖率红线，低于则阻断流水线
* [allowExts](#testing-coverage-parameters-allowExts)：参与覆盖率计算的代码文件类型白名单
* [lang](#testing-coverage-parameters-lang)：报告为 `golang` 时指定 `go`，避免计算误差
* [breakIfNoCoverage](#testing-coverage-parameters-breakIfNoCoverage)：未找到报告文件时是否抛错终止

各参数详细说明如下。

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

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

覆盖率数据 key 值，用于区分不同类型的覆盖率数据，
例如 frontend、backend 等。如果仓库仅包含一种覆盖率数据，则可以忽略此参数。

* 最多 `256` 个字符
* 同一仓库最多支持 `30` 个不同的 key
* 指定 key 后，覆盖率数据仅写入 meta 的 map 中，不再记录一级 value（默认全量/增量覆盖率），
  未指定 key 时才会记录默认覆盖率数据

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

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

覆盖率数据名称，用于展示在徽章中，
和覆盖率数据 key 一一对应，key 不存在时，name 将被忽略。

例如：`key: frontend`, `name: 前端覆盖率`

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

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

Glob 格式，指定覆盖率报告文件位置，相对于当前工作目录。
缺省时，将尝试查找当前目录（包括子目录）下的以下文件：
coverage.json、jacoco\*.xml、lcov.info、\*.lcov。

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

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

指定全量覆盖率红线，判断如果全量覆盖率百分比小于该值，阻断工作流退出流水线。

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

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

指定增量覆盖率红线，判断如果增量覆盖率百分比小于该值，阻断工作流退出流水线。
`pull_request`、`pull_request.update`、`pull_request.target` 事件
支持计算增量覆盖率结果，其他事件只计算全量覆盖率。

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

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

参与覆盖率计算的代码文件类型白名单，逗号分隔，如：`.json`, `.ts`, `.js`。
缺省时报告中的文件都会参与计算。

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

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

当覆盖率结果报告目标格式为 `golang` 时，
请指定此参数为 `go`，否则会出现计算误差。其他情况可忽略该参数。

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

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

没有找到覆盖率报告文件时，是否抛出错误终止流程。

## 输出结果 {#testing-coverage-output}

```json
{
  // 代码行覆盖率，例如 100，计算出错时值为 NA
  "lines": 100,
  // 代码增量行覆盖率，例如 100，计算出错时值为 NA
  "diff_pct": 100
}
```

## 配置样例 {#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
```