跳到内容

CI/Testing Workflow 🧪

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

CI Actions 🔄

所有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

编写测试 ✍️

测试结构

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() not test_1()
  • 单一断言：每个函数测试一件事
  • 快速测试：使用小型模型/数据集
  • Fixtures：使用 pytest fixtures 进行 setup/teardown
  • 标记: @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/

文档字符串格式化

pip install ultralytics-actions

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

CI故障排除 🔧

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

常见原因：

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

CI 运行缓慢

解决方案：

  • 使用 @pytest.mark.slow 用于开销大的测试
  • 模拟外部依赖项
  • 减少测试数据集大小
  • 使用以下方式并行化 pytest-xdist

不稳定的测试

修复：

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

性能基准测试 📈

CI tracks关键指标：

  • 推理速度 (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个月前 ✏️更新于1个月前
glenn-jocher