CI/测试工作流 🧪
持续集成 (CI) 对于尽早发现问题以保持高质量代码至关重要。本指南涵盖了 Ultralytics 项目的 CI 测试和质量检查。
CI 操作 🔄
所有 PR 在合并前都必须通过自动化的 CI 检查。我们的 CI 流水线包括：
CI 测试
主要 CI 测试，运行单元测试、Lint 检查以及全面测试。
Docker 部署
使用 Docker 验证部署，确保 Dockerfile 和相关脚本工作正常。
失效链接
扫描代码库以查找 Markdown 和 HTML 文件中的失效或死链接。
CodeQL 分析
GitHub 的语义分析工具，用于发现潜在的安全漏洞并维护代码质量。
PyPI 发布
验证项目是否可以打包并无误地发布到 PyPI。
平台测试 🖥️
测试在多种环境下运行：
- OS: 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 fixtures 进行安装/卸载
- Markers：使用
@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 中失败
常见原因：
- 特定平台问题：在目标 OS 上进行测试
- Python 版本差异：检查版本兼容性
- 缺少依赖：验证 CI 配置
- 时序/并发问题：增加重试次数或延长超时时间
CI 运行缓慢
解决方案：
- 对耗时测试使用
@pytest.mark.slow - 模拟外部依赖
- 减小测试数据集大小
- 使用
pytest-xdist进行并行化
不稳定测试 (Flaky Tests)
修复方法：
- 为网络相关测试增加重试机制
- 为慢速操作增加超时时间
- 修复异步代码中的竞态条件
- 使用确定性的随机种子
性能基准 📈
CI 追踪关键指标：
- 推理速度 (FPS)
- 内存占用
- 模型大小
- 导出耗时
显著的回归会阻止合并。如果指标发生变化：
- 验证变化是否符合预期
- 在 PR 中记录原因
- 获取维护者批准
CI 状态 📋
在 docs.ultralytics.com/help/CI 查看所有 Ultralytics 仓库的 CI 状态。
主仓库徽章
跳过 CI 检查 ⚠️
在提交信息中添加 [skip ci] 以跳过 CI（请谨慎使用）：
git commit -m "Update README [skip ci]"仅适用于：
- 仅文档修改
- 非代码文件更新
- 紧急热修复（需经批准）
资源 📚
- 官方 CI 指南 - 完整的 CI 文档
- 开发工作流 - PR 流程和代码标准
- GitHub Actions 文档 - CI 配置
- pytest 文档 - 测试框架
- Codecov - 覆盖率报告