YOLO Vision 2026：

CI/测试工作流 🧪#

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

CI 动作 🔄#

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

CI 测试#

运行单元测试、代码检查（linting）和全面测试的主要 CI 测试。

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 查看完整的覆盖率详情。

理解覆盖率#

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

在本地运行测试 🖥️#

安装开发依赖项#

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()
  • 单个断言：每个函数测试一件事
  • 快速测试：使用小型模型/数据集
  • 夹具 (Fixtures)：使用 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/

文档字符串格式化#

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

CI 故障排除 🔧#

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

常见原因：

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

CI 运行缓慢#

解决方案：

  • 为昂贵的测试使用 @pytest.mark.slow
  • 模拟外部依赖项
  • 减小测试数据集大小
  • 使用 pytest-xdist 进行并行化

不稳定测试 (Flaky Tests)#

修复方法：

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

性能基准 📈#

CI 跟踪关键指标：

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

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

  1. 验证更改是否符合预期
  2. 在 PR 中记录原因
  3. 获得维护者的批准

CI 状态 📋#

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

主仓库徽章#

CI Docker Links PyPI codecov

跳过 CI 检查 ⚠️#

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

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

仅用于：

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

资源 📚#

贡献者
GLglenn-jocher6FCfcakyon1BOBorda1