Coveragepy 配置详解：从入门到精通

Coveragepy 配置详解：从入门到精通

coveragepy The code coverage tool for Python 项目地址: https://gitcode.com/gh_mirrors/co/coveragepy

概述

Coveragepy 是 Python 生态中广泛使用的代码覆盖率工具，它能够帮助开发者了解测试用例对代码的覆盖情况。本文将深入解析 coveragepy 的配置文件系统，帮助开发者掌握如何通过配置文件定制覆盖率检测行为。

配置文件基础

配置文件的作用

Coveragepy 的配置文件主要用于：

• 持久化保存覆盖率检测的设置
• 统一团队成员的覆盖率检测标准
• 配置一些仅通过 API 可用的高级选项
• 支持子进程的覆盖率检测

配置文件的位置与优先级

Coveragepy 支持多种配置文件格式和位置：

1. 专用配置文件：

   • 默认名称：.coveragerc
   • 推荐位置：项目根目录
   • 推荐做法：纳入版本控制系统

2. 其他配置文件：

   • setup.cfg
   • tox.ini
   • pyproject.toml（需要 Python 3.11+ 或安装 toml 扩展）

3. 优先级：

   • 首先查找 .coveragerc
   • 若不存在，则按上述顺序查找其他配置文件
   • 找到第一个包含 coveragepy 配置的文件即停止搜索

指定配置文件

可通过以下方式指定配置文件：

• 命令行参数：--rcfile=FILE
• 环境变量：COVERAGE_RCFILE

配置文件语法

INI 语法

INI 格式是传统的配置文件格式：

• 使用 [section] 定义节
• 使用 name = value 格式定义选项
• 支持 # 和 ; 开头的注释
• 多行值通过缩进表示
• 布尔值支持：on/off、true/false、1/0

在 setup.cfg 或 tox.ini 中，节名需要添加 coverage: 前缀，例如 [coverage:run]。

TOML 语法

TOML 是较新的配置文件格式：

• 使用显式的列表和引号
• 布尔值为 true 或 false
• 配置必须位于 [tool.coverage] 节下
• 环境变量扩展仅在引号字符串内可用

环境变量扩展

配置文件支持环境变量扩展：

• 基本形式：$VAR 或 ${VAR}
• 特殊形式：
  • ${VAR?}：变量未定义时报错
  • ${VAR-default}：变量未定义时使用默认值
• 转义美元符号：$$

配置示例

以下是典型的 coveragepy 配置文件示例：

INI 格式 (.coveragerc)

[run]
branch = True

[report]
; 排除不需要覆盖的代码行
exclude_also =
    ; 调试代码
    def __repr__
    if self\.debug

    ; 防御性断言
    raise AssertionError
    raise NotImplementedError

    ; 不可运行代码
    if 0:
    if __name__ == .__main__.:

    ; 抽象方法
    @(abc\.)?abstractmethod

ignore_errors = True

[html]
directory = coverage_html_report

TOML 格式 (pyproject.toml)

[tool.coverage.run]
branch = true

[tool.coverage.report]
# 排除不需要覆盖的代码行
exclude_also = [
    # 调试代码
    "def __repr__",
    "if self\\.debug",

    # 防御性断言
    "raise AssertionError",
    "raise NotImplementedError",

    # 不可运行代码
    "if 0:",
    "if __name__ == .__main__.:",

    # 抽象方法
    "@(abc\\.)?abstractmethod",
]

ignore_errors = true

[tool.coverage.html]
directory = "coverage_html_report"

核心配置详解

[run] 节配置

branch

• 类型：布尔值
• 默认：False
• 作用：是否测量分支覆盖率（除语句覆盖率外）

command_line

• 类型：字符串
• 作用：指定运行程序的命令行（不带 coverage 选项）

concurrency

• 类型：多字符串
• 默认："thread"
• 作用：指定并发库（如 multiprocessing、gevent 等）

cover_pylib

• 类型：布尔值
• 默认：False
• 作用：是否测量 Python 标准库

data_file

• 类型：字符串
• 默认：".coverage"
• 作用：指定数据文件位置

source

• 类型：多字符串
• 作用：指定要测量的源文件或目录

[report] 节配置

exclude_also

• 类型：多字符串
• 作用：添加额外的排除模式（保留默认排除）

exclude_lines

• 类型：多字符串
• 作用：完全替换排除模式（会覆盖默认排除）

ignore_errors

• 类型：布尔值
• 默认：False
• 作用：是否忽略报告过程中的错误

[paths] 节配置

用于指定等效路径，在合并不同环境收集的数据时特别有用：

[paths]
source =
    src/
    /jenkins/build/*/src
    c:\myproj\src

• 第一个路径必须是报告机器上的实际路径
• 其他路径可以是模式或绝对/相对路径
• 合并时会尝试按顺序匹配路径

最佳实践

1. 版本控制：将 .coveragerc 纳入版本控制，确保团队一致
2. 路径映射：在多环境开发时，合理配置 [paths] 节
3. 排除策略：优先使用 exclude_also 而非 exclude_lines 以保留默认排除
4. 分支覆盖：项目成熟后考虑启用 branch = True
5. 并发支持：使用并发库时务必配置 concurrency

通过合理配置 coveragepy，开发者可以获得更准确、更有意义的代码覆盖率数据，从而有效指导测试工作的改进。

coveragepy The code coverage tool for Python 项目地址: https://gitcode.com/gh_mirrors/co/coveragepy