OpenHands 源码解析系列
第 16 讲:测试架构与 CI/CD
基于 OpenHands 源码 · 2026-08-12
一、测试体系全景
OpenHands 的测试体系覆盖了后端 Python、前端 React/TypeScript、企业版模块、Docker 镜像构建以及发布流水线。整个仓库包含:
🔹 114 个 Python 后端单元测试 (tests/unit/)
🔹 178 个 企业版测试 (enterprise/tests/)
🔹 299 个 前端测试文件 (frontend/)
🔹 26 个 GitHub Actions 工作流
测试金字塔
OpenHands 遵循经典的三层测试策略:前端 Playwright E2E → 后端 pytest 单元 → 代码质量 Lint/类型检查,每层独立并行执行。
二、pytest 测试框架配置
OpenHands 的测试依赖通过 Poetry 的 test 依赖组管理。让我们看 pyproject.toml 中的配置:
📄 pyproject.toml (第 124-135 行)
test = [
"gevent==25.9.1",
"pandas",
"pytest==9.0.3",
"pytest-asyncio==1.3.0",
"pytest-cov==7.1.0",
"pytest-forked==1.6.0",
"pytest-playwright==0.7.2",
"pytest-timeout==2.4.0",
"pytest-xdist==3.8.0",
"reportlab==4.4.10",
]关键插件解读:
| 插件 | 作用 | 为什么需要 |
|---|---|---|
| pytest-asyncio | 异步测试支持 | OpenHands 大量使用 FastAPI + async/await |
| pytest-cov | 覆盖率收集 | PR 覆盖率评论 + 质量门禁 |
| pytest-forked | 隔离测试进程 | 避免全局状态污染(如 Docker、环境变量) |
| pytest-xdist | 并行执行 | -n auto 利用多核加速 |
| pytest-playwright | 浏览器自动化 | E2E 测试前端 UI |
| pytest-timeout | 超时保护 | 防止 CI 阻塞 |
三、CI 流水线架构
每个 PR 和 main 分支推送都会触发以下流水线:
1. Python 测试流水线 (py-tests.yml)
📄 .github/workflows/py-tests.yml (第 59-60 行)
- name: Run Unit Tests
run: PYTHONPATH=".:$PYTHONPATH" poetry run pytest \
--forked -n auto -s ./tests/unit \
--cov=openhands --cov-branch执行策略:
🔹 --forked:每个测试在独立进程中运行,避免 Docker/K8s 测试污染全局状态
🔹 -n auto:自动使用所有 CPU 核心并行执行
🔹 --cov-branch:分支级别覆盖率(不仅是行覆盖率)
🔹 覆盖率文件通过 actions/upload-artifact 上传,后续合并
2. 企业版测试 (py-tests.yml test-enterprise)
📄 .github/workflows/py-tests.yml (第 90-92 行)
- name: Run Unit Tests
run: PYTHONPATH=".:$PYTHONPATH" poetry run --project=enterprise \
pytest --forked -n auto -s -p no:ddtrace \
-p no:ddtrace.pytest_bdd -p no:ddtrace.pytest_benchmark \
./enterprise/tests/unit --cov=enterprise --cov-branch注意:企业版测试显式禁用了 ddtrace 插件(Datadog APM),避免 CI 环境中遥测干扰。
3. 覆盖率评论 (coverage-comment job)
📄 .github/workflows/py-tests.yml (第 102-125 行)
coverage-comment:
name: Coverage Comment
if: github.event_name == 'pull_request'
needs: [test-on-linux, test-enterprise]
steps:
- uses: actions/download-artifact@v8
with:
pattern: coverage-*
merge-multiple: true
- name: Coverage comment
uses: py-cov-action/python-coverage-comment-action@v3
with:
GITHUB_TOKEN: ${{ github.token }}
MERGE_COVERAGE_FILES: truePython 后端和企业版覆盖率合并后自动发布到 PR 评论,Reviewer 可以直接看到变更的覆盖率影响。
四、Lint 与代码质量门禁
1. Pre-commit Hooks
📄 dev_config/python/.pre-commit-config.yaml (第 1-67 行)
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: debug-statements
- repo: local
hooks:
- id: warn-appmode-oss
name: "Warn on AppMode.OSS in backend"
entry: bash -lc 'if rg -n "\\bAppMode\\.OSS\\b" \
openhands tests/unit; then ...; fi'
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.12.5
hooks:
- id: ruff
args: [--fix, --unsafe-fixes]
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.15.0
hooks:
- id: mypy
entry: mypy --config-file dev_config/python/mypy.ini openhands/四层质量检查:
🔹 基础检查:trailing-whitespace、end-of-file-fixer、check-yaml、debug-statements
🔹 业务规则:warn-appmode-oss 禁止在 OSS 代码中使用 AppMode.OSS(统一用 AppMode.OPENHANDS)
🔹 Ruff lint + format:替代 flake8 + black + isort,单一工具完成 lint 和格式化
🔹 Mypy 类型检查:对 openhands/ 目录做严格的静态类型检查
2. Ruff 规则配置
📄 pyproject.toml (第 308-322 行)
[tool.ruff]
exclude = [ "enterprise/" ]
format.quote-style = "single"
lint.select = [
"ASYNC", # 异步代码最佳实践
"B", # flake8-bugbear (常见 bug 检测)
"E", # pycodestyle errors
"F", # pyflakes
"I", # isort (import 排序)
"Q", # 引号风格
"UP006", # 类型注解现代化
"UP007", # Union[X, Y] → X | Y
"UP008", # True/False 类型注解
"W", # pycodestyle warnings
]
lint.ignore = [
"ASYNC109", "ASYNC110", "ASYNC220", "ASYNC221",
"ASYNC230", "ASYNC251", "B003",
]设计亮点:Ruff 排除了 enterprise/ 目录(企业版有独立的 lint 配置),启用了 ASYNC 规则族确保异步代码的正确性。
五、测试策略深度解析
1. Fixture 模式 — 企业版 conftest.py
📄 enterprise/tests/unit/conftest.py (第 47-57 行)
@pytest.fixture(autouse=True)
def allow_short_context_windows():
old = os.environ.get('ALLOW_SHORT_CONTEXT_WINDOWS')
os.environ['ALLOW_SHORT_CONTEXT_WINDOWS'] = 'true'
try:
yield
finally:
if old is None:
os.environ.pop('ALLOW_SHORT_CONTEXT_WINDOWS', None)
else:
os.environ['ALLOW_SHORT_CONTEXT_WINDOWS'] = oldautouse fixture:每个企业版测试自动设置环境标志,测试结束后恢复原值。这是典型的"环境隔离"模式。
数据库 Fixture:
📄 enterprise/tests/unit/conftest.py (第 80-128 行)
@pytest.fixture(scope='function')
def db_path(tmp_path):
"""Create a unique temp file path for each test."""
return str(tmp_path / 'test.db')
@pytest.fixture
def engine(db_path):
engine = create_engine(
f'sqlite:///{db_path}', connect_args={'check_same_thread': False}
)
Base.metadata.create_all(engine)
return engine
@pytest.fixture
def async_engine(db_path):
"""Create an async engine using the SAME file-based database."""
async_engine = create_async_engine(
f'sqlite+aiosqlite:///{db_path}',
connect_args={'check_same_thread': False},
)
# ... 自动建表
return async_engine每个测试使用 tmp_path 创建独立的 SQLite 文件,测试间完全隔离,无共享状态。
2. Mock 模式 — 中间件测试
📄 tests/unit/server/test_middleware.py (第 1-45 行)
@pytest.fixture
def app():
"""Create a test FastAPI application."""
app = FastAPI()
@app.get('/test')
def test_endpoint():
return {'message': 'Test endpoint'}
return app
def test_localhost_cors_middleware_init_with_config():
mock_config = MagicMock()
mock_config.permitted_cors_origins = [
'https://example.com', 'https://test.com',
]
with patch(
'openhands.app_server.middleware.get_global_config',
return_value=mock_config
):
app = FastAPI()
middleware = LocalhostCORSMiddleware(app)
assert 'https://example.com' in middleware.allow_origins
assert len(middleware.allow_origins) == 2测试模式:通过 patch 替换全局配置,用 FastAPI + TestClient 模拟 HTTP 请求,验证 CORS 中间件行为。
3. 参数化测试 — 环境变量验证
📄 tests/unit/app_server/utils/test_env_var_validation.py (第 12-31 行)
class TestIsValidEnvVarName:
@pytest.mark.parametrize(
'name',
[
'MY_VAR', 'my_var', 'MyVar', '_PRIVATE',
'_', '__', 'A', 'a', 'VAR123', '_123',
'API_KEY', 'DATABASE_URL', 'GITHUB_TOKEN',
],
)
def test_valid_names(self, name: str):
assert is_valid_env_var_name(name) is True
@pytest.mark.parametrize(
'name',
[
'MY-VAR', 'MY VAR', 'MY.VAR', '123VAR',
'-VAR', 'MY@VAR', 'MY$VAR', 'MY#VAR',
# ... 30+ invalid cases
],
)
def test_invalid_names_special_chars(self, name: str):
assert is_valid_env_var_name(name) is False参数化测试:用 @pytest.mark.parametrize 将 13 个合法值和 30+ 非法值组合成两组测试,减少代码重复。
4. 异步测试 — GitHub Service
📄 tests/unit/integrations/github/test_github_service.py (第 18-88 行)
@pytest.mark.asyncio
async def test_github_service_token_handling():
token = SecretStr('test-token')
service = GitHubService(user_id=None, token=token)
assert service.token == token
headers = await service._get_headers()
assert headers['Authorization'] == 'Bearer test-token'
assert headers['Accept'] == 'application/vnd.github.v3+json'
@pytest.mark.asyncio
async def test_github_service_fetch_data():
mock_response = AsyncMock()
mock_response.status_code = 200
mock_response.json.return_value = {'login': 'test-user'}
mock_client = AsyncMock()
mock_client.get.return_value = mock_response
mock_client.__aenter__.return_value = mock_client
with patch('httpx.AsyncClient', return_value=mock_client):
service = GitHubService(user_id=None,
token=SecretStr('test-token'))
_ = await service._make_request(
'https://api.github.com/user')
mock_client.get.assert_called_once()异步 Mock 模式:用 AsyncMock 模拟 httpx.AsyncClient,用 __aenter__/__aexit__ 模拟异步上下文管理器,完全在内存中验证 API 调用逻辑。
六、前端测试体系
Vitest 单元 + Playwright E2E
📄 .github/workflows/fe-unit-tests.yml (第 44-46 行)
- name: Run tests and collect coverage
working-directory: ./frontend
run: npm run test:coverage📄 .github/workflows/fe-e2e-tests.yml (第 37-48 行)
- name: Install Playwright browsers
working-directory: ./frontend
run: npx playwright install --with-deps chromium
- name: Run Playwright tests
working-directory: ./frontend
run: npx playwright test --project=chromium
- name: Upload Playwright report
if: always()
with:
name: playwright-report
path: frontend/playwright-report/前端测试双轨制:
🔹 Vitest:299 个测试文件,覆盖组件、工具函数、翻译完整性
🔹 Playwright:真实 Chromium 浏览器 E2E 测试,报告自动上传为 CI 制品
🔹 TypeScript 编译检查:npm run build 作为 CI 门禁,确保类型安全
七、Docker 构建与发布流水线
多架构镜像构建
📄 .github/workflows/_build-image.yml (第 47-95 行)
build:
strategy:
matrix:
arch: [amd64, arm64]
steps:
- name: Build and push
uses: docker/build-push-action@v7
with:
platforms: linux/${{ matrix.arch }}
cache-from: |
type=registry,ref=${{ inputs.image }}:buildcache-*
cache-to: type=registry,...,mode=max
provenance: ${{ inputs.provenance }}
sbom: ${{ inputs.sbom }}
merge:
needs: build
steps:
- name: Merge manifests
with:
base-tags: ${{ steps.meta_base.outputs.tags }}
archs: "amd64 arm64"构建策略:
🔹 并行构建:amd64 和 arm64 同时构建,分别推送到 GHCR
🔹 Registry 缓存:buildcache 标签实现跨 CI 运行的构建缓存
🔹 Manifest 合并:构建完成后合并为多架构镜像
🔹 Enterprise 额外安全:provenance + SBOM 签名(仅企业版镜像)
Release-please 自动化版本管理
📄 .github/workflows/release.yml (第 15-31 行)
jobs:
openhands-app:
uses: OpenHands/release-actions/.github/workflows/
release-please.yml@main
cloud:
uses: OpenHands/release-actions/.github/workflows/
release-please.yml@main
with:
config-file: release-please-config.cloud.json
manifest-file: .release-please-manifest.cloud.json双发布线:OpenHands App (X.Y.Z) 和 OpenHands Cloud (cloud-X.Y.Z) 独立版本管理,基于 conventional commit 自动计算版本号。
八、测试目录结构总览
tests/
├── unit/ # 114 个 Python 测试
│ ├── app_server/ # App Server 测试
│ │ ├── utils/ # 工具函数
│ │ │ ├── logger/ # 日志系统
│ │ │ ├── test_jsonpatch_compat.py
│ │ │ └── test_env_var_validation.py
│ │ ├── analytics/ # 分析模块
│ │ └── file_store/ # 文件存储
│ ├── server/ # 服务端测试
│ │ ├── routes/ # API 路由
│ │ │ ├── test_skills_api.py
│ │ │ └── test_mcp_routes.py
│ │ ├── test_middleware.py
│ │ └── test_openapi_schema_generation.py
│ ├── integrations/ # 集成测试
│ │ ├── github/ # GitHub 集成
│ │ ├── gitlab/ # GitLab 集成
│ │ ├── bitbucket/ # Bitbucket 集成
│ │ ├── bitbucket_data_center/ # BBD C 集成
│ │ └── protocols/ # 协议层
│ ├── storage/ # 存储测试
│ │ ├── settings/ # 设置存储
│ │ └── data_models/ # 数据模型
│ ├── utils/ # 工具测试
│ │ ├── test_llm_utils.py
│ │ ├── test_git.py
│ │ └── ... (8 个文件)
│ ├── mcp/ # MCP 集成测试
│ ├── frontend/ # 前端翻译测试
│ └── enterprise/ # 企业迁移测试
└── (无 conftest.py — 测试完全自包含)
enterprise/tests/
└── unit/ # 178 个企业版测试
├── conftest.py # DB Fixture + autouse 环境
├── server/routes/conftest.py # 路由专用 Fixture
└── integrations/ # 企业集成 (Jira, Jira DC)九、CI/CD 流水线全景图
PR 推送 ──────────────────────────────────────────────┐
│
├── Lint (lint.yml) │
│ ├── lint-frontend (ESLint + TSC + i18n) │
│ ├── lint-python (pre-commit + ruff + mypy) │
│ └── lint-enterprise (独立 pre-commit) │
│ │
├── Python Tests (py-tests.yml) │
│ ├── test-on-linux (--forked -n auto --cov) │
│ ├── test-enterprise (--forked -n auto --cov) │
│ └── coverage-comment (合并 + PR 评论) │
│ │
├── FE Unit Tests (fe-unit-tests.yml) │
│ └── vitest + coverage │
│ │
├── FE E2E Tests (fe-e2e-tests.yml) │
│ └── Playwright Chromium │
│ │
├── Docker Build (ghcr-build.yml) │
│ ├── build_app (amd64 + arm64) │
│ ├── build_enterprise (provenance + SBOM) │
│ └── update_pr_description │
│ │
└── PR Title Check (pr.yml) │
└── Conventional Commits 校验 │
│
Main 推送 ────────────────────────────────────────────┤
├── Release-please (release.yml) │
│ ├── openhands-app (X.Y.Z) │
│ └── cloud (cloud-X.Y.Z) │
├── Docker 自动构建 (同上) │
└── PyPI Release (pypi-release.yml) │
│
Fork PR 保护 ─────────────────────────────────────────┤
├── Docker 构建跳过 fork │
├── pr.yml 使用 pull_request_target (fork-safe) │
└── 无 secrets: inherit │十、关键设计总结
| 设计决策 | 实现方式 | 效果 |
|---|---|---|
| 进程隔离 | --forked + tmp_path DB | Docker/K8s 测试不污染全局 |
| 并行加速 | -n auto xdist | 114+178 个测试分钟级完成 |
| 覆盖率门禁 | cov-branch + PR 评论 | Reviewer 实时看到覆盖率变化 |
| 类型安全 | mypy + TypeScript | 前后端全栈类型检查 |
| 统一 Lint | Ruff 替代 flake8+black+isort | 单工具快 10x,配置集中 |
| 构建缓存 | Registry buildcache | 跨 PR 复用 Docker 层 |
| Fork 安全 | pull_request_target + 条件跳过 | Fork PR 不触发 Docker 构建 |
| 自动版本 | Release-please + poetry-dynamic-versioning | Conventional commit 驱动版本 |
📌 预告
下一讲深入 性能优化与缓存策略——OpenHands 如何在 Agent 对话、LLM 调用、文件存储等环节做性能优化,包括 LiteLLM 路由缓存、SQLite 查询优化、以及 Docker 构建缓存策略。
📚 系列导航
← 第 15 讲:错误处理与日志系统
→ 第 17 讲:性能优化与缓存策略
关注公众号「AI技术推荐官」获取更多源码解析内容
夜雨聆风