Ultralytics YOLO27： 加入候补名单。
Get Started

CI/测试工作流 🧪#

持续集成 (CI) 对于维护高质量代码至关重要，因为它能及早发现问题。本指南介绍 Ultralytics 项目的 CI 测试和质量检查。

CI 操作 🔄#

所有 PR 在合并前都必须通过自动化 CI 检查。我们的 CI 流水线包括：

CI 测试#

主要 CI 测试会运行单元测试、代码检查和综合测试。

Docker 部署#

通过 Docker 验证部署，确保 Dockerfile 和相关脚本正常工作。

扫描代码库，查找 Markdown 和 HTML 文件中的失效或无效链接。

CodeQL 分析#

GitHub 的语义分析工具，用于查找潜在的安全漏洞并维护代码质量。

PyPI 发布#

验证项目能否无错误地打包并发布到 PyPI。

平台测试 🖥️#

测试会在多个环境中运行：

  • 操作系统：Ubuntu、Windows、macOS
  • Python：主要测试矩阵使用 3.13，此外还有用于兼容性测试的 3.8-3.12 任务

代码覆盖率 📊#

我们使用 Codecov 衡量并可视化代码覆盖率，了解测试对代码库的覆盖情况。

覆盖率集成#

Codecov 集成提供：

  • 详细的覆盖率信息
  • 不同提交之间的覆盖率对比
  • 在代码上以可视化叠加层显示已覆盖的行
  • ultralytics 包的覆盖率百分比

在 codecov.io/github/ultralytics/ultralytics 查看完整的覆盖率详情。

了解覆盖率#

代码覆盖率表示测试执行的代码占全部代码的百分比。覆盖率高说明代码经过了充分测试，但不能保证没有 bug。覆盖率有助于找出未经过测试、可能容易出错的部分。

在本地运行测试 🖥️#

安装开发依赖#

pip install -e ".[dev]"

运行所有测试#

pytest tests/

运行指定测试#

# Single file
pytest tests/test_engine.py

# Single test function
pytest tests/test_engine.py::test_export

# Tests matching pattern
pytest -k "export"

# Slow tests only
pytest --slow -m slow

运行测试并统计覆盖率#

pytest --cov=ultralytics tests/

并行测试#

# Install pytest-xdist
pip install pytest-xdist

# Run tests in parallel
pytest -n auto

编写测试 ✍️#

测试结构#

from pathlib import Path

from ultralytics import YOLO

def test_model_export():
    """Test ONNX model export."""
    model = YOLO("yolo26n.pt")
    model.export(format="onnx")
    assert Path("yolo26n.onnx").exists()

最佳实践#

  • 使用描述性名称：使用 test_export_onnx_format()，而不是 test_1()
  • 单个断言：每个函数只测试一件事
  • 快速测试：使用小型模型/数据集
  • Fixture：使用 pytest fixture 进行设置/清理
  • 标记：长时间运行的测试使用 @pytest.mark.slow

测试组织结构#

请参阅上游的 tests 目录，了解当前的测试组织结构。

测试标记#

import pytest

@pytest.mark.slow
def test_full_training():
    """Test full training run (slow)."""
    model = YOLO("yolo26n.pt")
    model.train(data="coco128.yaml", epochs=1)

代码质量检查 🎯#

使用 Ruff 格式化#

# Check formatting
ruff check ultralytics/

# Auto-fix issues
ruff check --fix ultralytics/

# Format code
ruff format ultralytics/

在我们的开发工作流中了解更多代码规范。

类型检查#

# Run mypy (where configured)
mypy ultralytics/

文档字符串格式#

pip install ultralytics-actions
# Auto-fix
ultralytics-actions-format-python-docstrings .

CI 故障排查 🔧#

测试在本地通过，但在 CI 中失败#

常见原因：

  • 特定平台的问题：在目标操作系统上测试
  • Python 版本差异：检查版本兼容性
  • 缺少依赖项：检查 CI 配置
  • 时序/并发问题：添加重试或延长超时时间

CI 运行缓慢#

解决方案：

  • 对耗时较长的测试使用 @pytest.mark.slow
  • 模拟外部依赖项
  • 缩小测试数据集
  • 使用 pytest-xdist 并行运行

不稳定的测试#

修复方法：

  • 为依赖网络的测试添加重试
  • 为耗时较长的操作延长超时时间
  • 修复异步代码中的竞态条件
  • 使用确定性的随机种子

性能基准测试 📈#

CI 会跟踪关键指标：

  • 推理速度 (FPS)
  • 内存使用量
  • 模型大小
  • 导出耗时

显著的性能回退会阻止合并。如果指标发生变化：

  1. 确认变更符合预期
  2. 在 PR 中说明原因
  3. 获得维护者批准

CI 状态 📋#

在 docs.ultralytics.com/help/CI 查看所有 Ultralytics 仓库的 CI 状态。

主仓库徽章#

CI Docker 链接 PyPI codecov

跳过 CI 检查 ⚠️#

在提交消息中添加 [skip ci] 以跳过 CI（谨慎使用）：

git commit -m "Update README [skip ci]"

仅适用于：

  • 仅涉及文档的更改
  • 非代码文件更新
  • 紧急热修复（需获得批准）

资源 📚#

贡献者
GLglenn-jocher6LAlaodouya1PDpderrenger1FCfcakyon1BOBorda1