跳到内容

CI/测试工作流程 🧪

持续集成 (CI) 对于通过尽早发现问题来保持高质量代码至关重要。本指南涵盖了 Ultralytics 项目的 CI 测试和质量检查。

CI操作 🔄

所有 PR 必须通过自动 CI 检查才能合并。我们的 CI 流程包括：

CI 测试

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

Docker 部署

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

扫描代码库中 markdown 和 HTML 文件中的损坏或无效链接。

CodeQL 分析

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

PyPI 发布

验证项目是否可以打包并发布到 PyPI，且没有错误。

平台测试 🖥️

测试在多个环境中运行：

  • 操作系统: Ubuntu, Windows, macOS
  • Python: 3.8, 3.9, 3.10, 3.11, 3.12

代码覆盖率 📊

我们使用 Codecov 来衡量和可视化代码覆盖率，从而深入了解测试对代码库的执行情况。

覆盖率集成

Codecov 集成提供：

  • 详细的覆盖率见解
  • 提交之间的覆盖率比较
  • 代码上的可视化覆盖层，显示覆盖的行
  • 的覆盖率百分比 ultralytics 软件包

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

理解覆盖率

代码覆盖率显示了在测试期间执行的代码百分比。高覆盖率表明代码经过了充分的测试，但不能保证没有错误。覆盖率有助于识别可能容易出错的未经测试的区域。

在本地运行测试 🖥️

安装开发依赖项

pip install -e ".[dev]"

运行所有测试

pytest tests/

运行特定测试

# Single file
pytest tests/test_engine.py

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

# Tests matching pattern
pytest -k "export"

# Slow tests only
pytest -m slow

运行并生成覆盖率报告

pytest --cov=ultralytics tests/

并行测试

# Install pytest-xdist
pip install pytest-xdist

# Run tests in parallel
pytest -n auto

Pre-commit钩子 🪝

设置 pre-commit 钩子以在推送之前发现问题：

pip install pre-commit
pre-commit install

钩子自动运行：

  • Ruff（代码检查和格式化）
  • docformatter（文档字符串格式化）
  • 移除末尾空格
  • YAML 验证

手动运行：

pre-commit run --all-files

编写测试 ✍️

测试结构

from pathlib import Path

from ultralytics import YOLO


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

最佳实践

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

测试组织

tests/
├── test_engine.py      # Training, validation, prediction
├── test_nn.py          # Model architecture
├── test_data.py        # Dataset handling
├── test_utils.py       # Utility functions
└── test_exports.py     # Export formats

测试标记

import pytest


@pytest.mark.slow
def test_full_training():
    """Test full training run (slow)."""
    model = YOLO("yolo11n.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/

文档字符串格式化

# Check docstrings
docformatter --check ultralytics/

# Auto-fix
docformatter --in-place ultralytics/

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]"

仅适用于：

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

资源 📚



📅 1 个月前创建 ✏️ 9 天前更新
glenn-jocher