Skip to main content
在 GitHub 上编辑 (EN)

CI/测试工作流 🧪

持续集成（CI）对于通过尽早发现问题来维护高质量代码至关重要。本指南介绍了针对 Ultralytics 项目的 CI 测试和质量检查。

CI 操作 🔄

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

CI 测试

主要持续集成测试，包括单元测试、代码检查和全面测试。

Docker 部署

使用 Docker 验证部署，确保 Dockerfile 及相关脚本运行正常。

链接失效

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

CodeQL 分析

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

PyPI

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

平台测试 🖥️

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

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

代码覆盖率 📊

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

覆盖范围整合

Codecov 集成提供：

  • 详细的覆盖情况分析
  • 提交之间的覆盖率比较
  • 代码上的视觉叠加层，用于显示被覆盖的行
  • 覆盖率为 ultralytics 包

查看完整报道详情，请访问 codecov.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

撰写测试 ✍️

测试结构

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()
  • 单一断言: 每个函数只测试一项
  • 快速检测: 使用小型模型/数据集
  • 赛程: 使用 pytest 固定装置进行初始化和清理
  • 标记: @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("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/

Docstring 格式化

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

CI 故障排除 🔧

测试在本地通过，但在持续集成中失败

常见原因：

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

CI 运行缓慢

解决方案：

  • 使用 @pytest.mark.slow 用于昂贵的检测
  • 模拟外部依赖项
  • 缩小测试数据集的规模
  • 使用……进行并行化 pytest-xdist

不稳定的测试

修复内容：

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

性能基准 📈

CI 追踪关键指标：

  • 推理速度（FPS）
  • 内存使用情况
  • 模型大小
  • 导出时间

显著的回归会阻碍数据合并。如果指标发生变化：

  1. 请确认此更改是预期的
  2. 在拉取请求中说明原因
  3. 获得维护者的批准

CI 状态 📋

查看所有 Ultralytics 仓库的 CI 状态，请访问 docs.ultralytics.com/help/CI.

主仓库徽章

CI Docker 链接 PyPI codecov

跳过 CI 检查 ⚠️

添加 [skip ci] 提交信息中需注明跳过持续集成（请谨慎使用）：

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

仅限：

  • 仅文档变更
  • 非代码文件的更新
  • 紧急热修复程序（经批准）

资源 📚