Meet YOLO26: next-gen vision AI.

Link to this sectionCI/测试工作流 🧪#

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

Link to this sectionCI 操作 🔄#

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

Link to this sectionCI 测试#

主要 CI 测试，运行单元测试、Lint 检查以及全面测试。

Link to this sectionDocker 部署#

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

Link to this section失效链接#

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

Link to this sectionCodeQL 分析#

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

Link to this sectionPyPI 发布#

验证项目是否可以打包并无误地发布到 PyPI。

Link to this section平台测试 🖥️#

测试在多种环境下运行：

  • OS: Ubuntu, Windows, macOS
  • Python: 3.8, 3.9, 3.10, 3.11, 3.12

Link to this section代码覆盖率 📊#

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

Link to this section覆盖率集成#

Codecov 集成提供了：

  • 详细的覆盖率洞察
  • 提交之间的覆盖率对比
  • 在代码上展示已覆盖行的可视化叠加层
  • ultralytics 软件包的覆盖率百分比

查看完整的覆盖率详情，请访问 codecov.io/github/ultralytics/ultralytics。

Link to this section理解覆盖率#

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

Link to this section本地运行测试 🖥️#

Link to this section安装开发依赖#

pip install -e ".[dev]"

Link to this section运行所有测试#

pytest tests/

Link to this section运行特定测试#

# 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

Link to this section运行并查看覆盖率#

pytest --cov=ultralytics tests/

Link to this section并行测试#

# Install pytest-xdist
pip install pytest-xdist

# Run tests in parallel
pytest -n auto

Link to this section编写测试 ✍️#

Link to this section测试结构#

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()

Link to this section最佳实践#

  • 描述性名称：使用 test_export_onnx_format() 而非 test_1()
  • 单次断言：每个函数只测试一件事
  • 快速测试：使用小型模型/数据集
  • Fixtures：使用 pytest fixtures 进行安装/卸载
  • Markers：使用 @pytest.mark.slow 标记长时间运行的测试

Link to this section测试组织#

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

Link to this section测试标记#

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)

Link to this section代码质量检查 🎯#

Link to this section使用 Ruff 进行格式化#

# Check formatting
ruff check ultralytics/

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

# Format code
ruff format ultralytics/

在我们的 开发工作流 中了解更多有关代码标准的信息。

Link to this section类型检查#

# Run mypy (where configured)
mypy ultralytics/

Link to this section文档字符串格式化#

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

Link to this sectionCI 故障排除 🔧#

Link to this section测试在本地通过但在 CI 中失败#

常见原因：

  • 特定平台问题：在目标 OS 上进行测试
  • Python 版本差异：检查版本兼容性
  • 缺少依赖：验证 CI 配置
  • 时序/并发问题：增加重试次数或延长超时时间

Link to this sectionCI 运行缓慢#

解决方案：

  • 对耗时测试使用 @pytest.mark.slow
  • 模拟外部依赖
  • 减小测试数据集大小
  • 使用 pytest-xdist 进行并行化

Link to this section不稳定测试 (Flaky Tests)#

修复方法：

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

Link to this section性能基准 📈#

CI 追踪关键指标：

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

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

  1. 验证变化是否符合预期
  2. 在 PR 中记录原因
  3. 获取维护者批准

Link to this sectionCI 状态 📋#

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

Link to this section主仓库徽章#

CI Docker Links PyPI codecov

Link to this section跳过 CI 检查 ⚠️#

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

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

仅适用于：

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

Link to this section资源 📚#

贡献者
GLglenn-jocher6FCfcakyon1BOBorda1