Qodo Cover 的目标是通过自动生成高质量的测试用例来扩展代码覆盖率，从而高效提升代码覆盖率。Qodo Cover 可以在你的 GitHub CI 工作流中运行，也可以作为 CLI 工具在本地使用。

目录

• 新闻与更新
• 概述
• 安装与使用
• 贡献
• 文档
• 路线图

新闻与更新

2025-06-15

⚠️ 此仓库已不再维护。如果您希望继续开发或在自己的项目中使用，请将其 fork。

2024-12-04:

新增模式 - 在你的 GitHub CI 工作流中运行 Qodo Cover Pro。目前处于预览阶段，限时免费提供给 Python 项目使用，支持你从心仪的 LLM 提供商处获取并使用自己的 LLM API 密钥。这是一种切实可行的方式，可以提升代码质量和可靠性。更多详情请联系 Qodo 团队。

2024-11-05:

新增模式 - 扫描整个代码库，自动识别测试文件，自动收集每个测试文件的上下文，并通过新增测试用例扩展测试套件。 更多详情请参见 这里。

Qodo-Cover

欢迎来到 Qodo-Cover。该项目专注于利用生成式 AI 自动化并优化测试用例的生成（目前主要为单元测试），旨在简化开发流程。Qodo-Cover 可通过终端运行，并计划集成到主流的 CI 平台中。

我们诚邀社区共同协作，帮助扩展 Qodo Cover 的功能，持续将其打造为自动化单元测试生成领域的前沿解决方案。同时，我们也希望激励研究人员利用这一开源工具探索新的测试生成技术。

概述

该工具是更广泛的软件自动化单元测试生成工具集的一部分。它利用先进的生成式 AI 模型，旨在简化和加速测试过程，确保高质量的软件开发。系统由多个组件组成：

1. 测试运行器： 执行命令或脚本以运行测试套件并生成代码覆盖率报告。
2. 覆盖率解析器： 验证随着测试用例的增加，代码覆盖率是否提升，确保新测试确实提高了整体测试效果。
3. 提示构建器： 从代码库中收集必要数据，并构建传递给大型语言模型（LLM）的提示。
4. AI 调用器： 与 LLM 交互，根据提供的提示生成测试用例。

安装与使用

需求

在开始之前，请确保您已具备以下条件：

• 在环境变量中设置 OPENAI_API_KEY，这是调用 OpenAI API 所必需的。
• 代码覆盖率工具：工具正常运行需要 Cobertura XML 格式的代码覆盖率报告。
  • 例如，在 Python 中可以使用 pytest-cov。运行 Pytest 时添加 --cov-report=xml 选项即可。
  • 注意：我们正在积极支持更多类型的覆盖率格式，但欢迎您提交 PR 并参与 cover_agent/CoverageProcessor.py 的开发。

如果直接从仓库运行，您还需要：

• 系统上已安装 Python。
• 安装 Poetry 来管理 Python 包依赖。Poetry 的安装说明可在 https://python-poetry.org/docs/ 查阅。

独立运行

Qodo Cover 可以作为 Python Pip 包安装，也可以作为独立可执行文件运行。

Python Pip

要直接通过 GitHub 安装 Python Pip 包，请运行以下命令：

pip install git+https://github.com/qodo-ai/qodo-cover.git

二进制文件

二进制文件无需在您的系统上安装任何 Python 环境即可运行（例如，在不包含 Python 的 Docker 容器中）。您可以前往项目的 发布页面 下载适用于您系统的版本。

代码库设置

运行以下命令以安装所有依赖项并从源码运行项目：

poetry install

运行代码

下载可执行文件或安装 Pip 包后，您可以运行 Cover Agent 来生成和验证单元测试。通过以下命令在命令行中执行：

cover-agent \
  --source-file-path "<源文件路径>" \
  --test-file-path "<测试文件路径>" \
  --project-root "<项目根目录>" \
  --code-coverage-report-path "<覆盖率报告路径>" \
  --test-command "<要运行的测试命令>" \
  --test-command-dir "<运行测试命令的目录>" \
  --coverage-type "<覆盖率报告类型>" \
  --desired-coverage <期望的覆盖率，范围为0到100> \
  --max-iterations <LLM的最大迭代次数> \
  --included-files "<可选的要包含的文件列表>"

您可以使用下面的示例代码来试用 Cover Agent。 （请注意，usage_examples 文件提供了更详细的 Cover Agent 使用示例）

Python

按照 templated_tests/python_fastapi/ 目录下的 README.md 文件中的步骤设置环境，然后返回到仓库根目录，运行以下命令为 python fastapi 示例添加测试：

cover-agent \
  --source-file-path "templated_tests/python_fastapi/app.py" \
  --test-file-path "templated_tests/python_fastapi/test_app.py" \
  --project-root "templated_tests/python_fastapi" \
  --code-coverage-report-path "templated_tests/python_fastapi/coverage.xml" \
  --test-command "pytest --cov=. --cov-report=xml --cov-report=term" \
  --test-command-dir "templated_tests/python_fastapi" \
  --coverage-type "cobertura" \
  --desired-coverage 70 \
  --max-iterations 10

Go

对于使用 go 的示例，进入 templated_tests/go_webservice 目录，按照 README.md 设置项目。 为了使用覆盖率报告功能，您需要安装 gocov 和 gocov-xml。运行以下命令安装这些工具：

go install github.com/axw/gocov/gocov@v1.1.0
go install github.com/AlekSi/gocov-xml@v1.1.0

然后运行以下命令：

cover-agent \
  --source-file-path "app.go" \
  --test-file-path "app_test.go" \
  --code-coverage-report-path "coverage.xml" \
  --test-command "go test -coverprofile=coverage.out && gocov convert coverage.out | gocov-xml > coverage.xml" \
  --test-command-dir $(pwd) \
  --coverage-type "cobertura" \
  --desired-coverage 70 \
  --max-iterations 1

Java

对于使用 java 的示例，进入 templated_tests/java_gradle 目录，按照 README.md 设置项目。 为了使用 jacoco 覆盖率报告功能，请遵循 README.md 中的“要求”部分： 然后运行以下命令：

cover-agent \
  --source-file-path="src/main/java/com/davidparry/cover/SimpleMathOperations.java" \
  --test-file-path="src/test/groovy/com/davidparry/cover/SimpleMathOperationsSpec.groovy" \
  --code-coverage-report-path="build/reports/jacoco/test/jacocoTestReport.csv" \
  --test-command="./gradlew clean test jacocoTestReport" \
  --test-command-dir=$(pwd) \
  --coverage-type="jacoco" \
  --desired-coverage=70 \
  --max-iterations=1

录制与回放功能

为了节省 LLM 服务费用，提供响应录制模式。起点是一个组哈希值，由每次测试运行中使用的源文件和测试文件的哈希值生成。如果任一文件发生变化，相应的 LLM 响应都应重新录制。 运行以下命令以启用 LLM 响应录制模式执行所有测试：

poetry run python tests_integration/run_test_all.py --record-mode

如果您不带 --record-mode 标志运行相同命令：

poetry run python tests_integration/run_test_all.py

它将使用已录制的响应生成测试，而无需调用 LLM；如果未录制，则会调用 LLM 来运行测试。

您也可以从单独的测试运行中录制 LLM 响应。像平常一样运行测试，并在命令中添加 --record-mode 标志：

poetry run python tests_integration/run_test_with_docker.py \
  --docker-image "embeddeddevops/python_fastapi:latest" \
  --source-file-path "app.py" \
  --test-file-path "test_app.py" \
  --code-coverage-report-path "coverage.xml" \
  --test-command "pytest --cov=. --cov-report=xml --cov-report=term" \
  --coverage-type "cobertura" \
  --model "gpt-4o-mini" \
  --record-mode

下表说明了测试运行程序的行为，取决于是否设置了 --record-mode 标志以及是否已存在录制文件：

录制的响应存储在 stored_responses 文件夹中。文件名基于测试名称以及一个依赖于源文件和测试文件内容的哈希值。

<测试名称>_responses_<哈希值>.yml

# 例如：
python_fastapi_responses_a9d9de927a82a7d776889738d2880bec7166c5f69d3518837183a20ef48b2a37.yml

与同一源文件和测试文件组哈希值对应的响应文件会在每次录制会话中更新，添加新的提示哈希条目。 要从头重新生成该文件，您可以删除现有的响应文件并开始新的录制会话。

输出

一些调试文件将在仓库本地输出（这些文件包含在 .gitignore 中）：

• run.log：记录器的副本，会转储到您的 stdout；
• test_results.html：结果表格，包含每个生成测试的以下信息：
  • 测试状态
  • 失败原因（如适用）
  • 退出代码
  • stderr
  • stdout
  • 生成的测试

您可以使用 --suppress-log-files 标志来抑制日志输出。这将阻止创建 run.log、test_results.html 以及测试结果的 db 文件。

额外的日志记录

如果您设置环境变量 WANDB_API_KEY，提示、响应以及其他附加信息将会被记录到 Weights and Biases 上。

使用其他大模型

本项目使用 LiteLLM 与 OpenAI 及其他托管的大模型进行通信（目前已支持 100 多种大模型）。要使用除 OpenAI 默认模型之外的其他模型，您需要：

1. 导出受支持大模型所需的任何环境变量 按照 LiteLLM 的说明。
2. 在调用 Cover Agent 时，使用 --model 选项指定模型名称。

例如（如 LiteLLM 快速入门指南 所示）：

export VERTEX_PROJECT="hardy-project"
export VERTEX_LOCATION="us-west"

cover-agent \
  ...
  --model "vertex_ai/gemini-pro"

OpenAI 兼容端点

export OPENAI_API_KEY="<您的 API 密钥>" # 如果 <您的 API 基础地址> 需要 API 密钥，请设置此值。

cover-agent \
  ...
  --model "openai/<您的模型名称>" \
  --api-base "<您的 API 基础地址>"

Azure OpenAI 兼容端点

export AZURE_API_BASE="<您的 API 基础地址>" # Azure API 基础地址
export AZURE_API_VERSION="<您的 API 版本>" # Azure API 版本（可选）
export AZURE_API_KEY="<您的 API 密钥>" # Azure API 密钥

cover-agent \
  ...
  --model "azure/<您的部署名称>"

贡献

有关如何为本项目做出贡献的更多信息，请参阅 Contributing。

文档

• 向 CoverageProcessor 类添加另一种保险类型的方法
• 在 Cover Agent 中使用测试数据库
• Cover Agent 功能标志
• 仓库覆盖率
• 顶层序列图
• 使用示例

路线图

以下是计划功能的路线图及当前实现状态：

• 自动为您的软件项目生成单元测试，利用先进的人工智能模型确保全面的测试覆盖和质量保证。（类似于 Meta）
  • 能够为不同编程语言生成测试
  • 能够应对各种复杂的测试场景
  • 对被测代码进行行为分析，并据此生成测试
  • 检查测试的不稳定性，例如按照 TestGen-LLM 的建议运行 5 次
• 解决更多测试生成方面的痛点
  • 生成专注于 PR 变更集的新测试
  • 遍历整个代码库并尝试增强所有现有的测试套件
• 提升易用性
  • 与 GitHub Actions、Jenkins、CircleCI、Travis CI 等集成
  • 集成数据库、API、OpenTelemetry 等数据源，以提取用于测试生成的相关输入输出
  • 添加配置文件

QodoAI

QodoAI 的使命是帮助繁忙的开发团队提升并持续维护代码质量。 我们提供多种工具，包括开源工具的“Pro”版本，这些版本专为企业级代码复杂度设计，并能感知多仓库代码库。

立即试用 Qodo Cover 的 GitHub Action Pro 版本!

Qodo-Cover 快速上手指南

Qodo-Cover 是一款利用生成式 AI 自动编写单元测试以提升代码覆盖率的开源工具。它支持在本地 CLI 或 GitHub CI 工作流中运行，目前主要支持 Python、Go 和 Java 等项目。

⚠️ 重要提示：根据官方最新公告（2025-06-15），该仓库已不再维护。如需继续使用或开发，请自行 Fork 该项目。

环境准备

在开始之前，请确保满足以下前置条件：

1. 系统与环境

• Python: 已安装 Python 环境（若使用 Pip 安装或源码运行）。
• Poetry: 若从源码运行，需安装 Poetry 用于依赖管理。
• API Key: 必须设置环境变量 OPENAI_API_KEY（或其他支持的 LLM Provider Key），用于调用大模型服务。

2. 代码覆盖率工具

工具需要读取 Cobertura XML 格式的覆盖率报告。请根据你的编程语言安装相应工具：

• Python: 推荐使用 pytest-cov。运行测试时需添加 --cov-report=xml 参数。
• Go: 需安装 gocov 和 gocov-xml 将覆盖率转换为 XML 格式。
• Java: 需配置 Jacoco 生成覆盖率报告。

安装步骤

你可以选择通过 Pip 直接安装，或下载二进制文件运行。

方式一：通过 Pip 安装（推荐）

直接使用 GitHub 源安装最新版本的 Python 包：

pip install git+https://github.com/qodo-ai/qodo-cover.git

方式二：使用二进制文件

如果你希望在无 Python 环境（如精简版 Docker 容器）中运行，可前往项目的 Release 页面 下载对应系统的可执行文件。

方式三：源码运行（开发者模式）

克隆仓库并安装依赖：

git clone https://github.com/qodo-ai/qodo-cover.git
cd qodo-cover
poetry install

基本使用

安装完成后，使用 cover-agent 命令即可自动生成测试。你需要指定源文件、测试文件路径、测试命令以及期望的覆盖率目标。

通用命令格式

cover-agent \
  --source-file-path "<源文件路径>" \
  --test-file-path "<测试文件路径>" \
  --project-root "<项目根目录>" \
  --code-coverage-report-path "<覆盖率报告 XML 路径>" \
  --test-command "<运行测试的命令>" \
  --test-command-dir "<运行测试的目录>" \
  --coverage-type "<覆盖率类型，如 cobertura>" \
  --desired-coverage <目标覆盖率数值 0-100> \
  --max-iterations <最大 AI 迭代次数>

示例：Python 项目 (FastAPI)

假设你有一个 FastAPI 项目，想要为 app.py 生成测试并达到 70% 的覆盖率：

cover-agent \
  --source-file-path "templated_tests/python_fastapi/app.py" \
  --test-file-path "templated_tests/python_fastapi/test_app.py" \
  --project-root "templated_tests/python_fastapi" \
  --code-coverage-report-path "templated_tests/python_fastapi/coverage.xml" \
  --test-command "pytest --cov=. --cov-report=xml --cov-report=term" \
  --test-command-dir "templated_tests/python_fastapi" \
  --coverage-type "cobertura" \
  --desired-coverage 70 \
  --max-iterations 10

示例：Go 项目

对于 Go 项目，需先确保已安装 gocov 和 gocov-xml，然后运行：

cover-agent \
  --source-file-path "app.go" \
  --test-file-path "app_test.go" \
  --code-coverage-report-path "coverage.xml" \
  --test-command "go test -coverprofile=coverage.out && gocov convert coverage.out | gocov-xml > coverage.xml" \
  --test-command-dir $(pwd) \
  --coverage-type "cobertura" \
  --desired-coverage 70 \
  --max-iterations 1

运行结果

执行成功后，工具会在当前目录生成以下调试文件（除非使用 --suppress-log-files 禁用）：

• run.log: 运行日志。
• test_results.html: 包含生成的测试用例、状态、失败原因及输出信息的详细报表。

提示: 若需节省 LLM 调用成本，可使用 --record-mode 录制 AI 响应，后续相同代码变更时可重放记录而不消耗 Token。