企业官网建设流程全解析

OpenSRE 端到端测试规范：无 Mock 的真实环境测试原则与 Live E2E 工程实践

【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre

本文解读 OpenSRE 仓库中 tests/e2e/AGENTS.md 所确立的端到端（E2E）测试设计原则，并结合tests/e2e/目录下的真实实现（Grafana Cloud 遥测验证、Live 安装器金丝雀、Docker 部署健康检查、incident.io / PostHog 真实 API 调用等）展开纵深分析。读完本文，你将掌握 OpenSRE 如何在不使用 Mock 的前提下验证 AI SRE Agent 与生产级基础设施的集成行为，理解"环境门控 + 大声跳过"的 CI 策略，并能在本地复现这些 Live E2E 用例。

一、背景：AGENTS.md 在 E2E 测试体系中的定位

tests/e2e/AGENTS.md是一份篇幅精炼但语义清晰的测试规范声明，它开宗明义地指出：

Principles fortests/e2e/live end-to-end tests. Real fixtures in this directory are the canonical usage examples — this file states the rules, not the code.

即：该文件只陈述规则，而目录内的真实测试夹具（fixtures）才是权威的用法示例。因此，理解这份规范必须回到源码，看规则是如何被落地执行的。

从工程配置看，tests/e2e/在默认测试体系中是被刻意隔离的。在 pytest.ini 中可以看到：

• norecursedirs = tests/e2e .git __pycache__ ...：默认 pytest 收集排除整个tests/e2e目录，避免在无外部凭据的普通 CI 中执行 Live 测试；
• 自定义 markers 明确了语义边界：e2e: requires live infrastructure or external credentials (skip in offline CI)、live_install: hits real install.opensre.com / GitHub / Homebrew (opt-in or e2e path)。

这构成了全文三条原则的工程基础：这些测试默认不跑、需要显式选择、并且只在使用真实环境时才跑。

二、原则一：真实端到端测试，禁止 Mock

AGENTS.md 第一条原则要求：测试必须调用真实服务与真实基础设施——Live 安装脚本、Grafana Cloud、PostHog、incident.io、Docker 构建等，不得使用模拟服务或伪造响应。理由非常直接：Mock 只能验证 Agent 对"人工构造的假数据"的响应，而无法验证对生产环境实际产出的行为。

2.1 真实 Grafana Cloud 遥测验证

tests/e2e/grafana_validation/ 是这条原则最完整的落地点。其中 grafana_validation.py 提供了validate_grafana_telemetry()工具：等待遥测传播后，通过integrations.grafana.tools中的query_grafana_logs/query_grafana_traces真实查询 Grafana Cloud，统计日志条数与 trace span 数，并支持传入expected_spans校验指定 span 是否全部出现：

result = validate_grafana_telemetry( service_name="prefect-etl-pipeline", execution_run_id="abc-123", wait_seconds=10, ) print(f"Logs found: {result['logs_found']}") print(f"Traces found: {result['traces_found']}")

返回的字典包含logs_found、traces_found、total_logs、total_traces、pipeline_spans、error_logs、passed等字段，整体判定逻辑为passed = logs_found or traces_found。同文件还提供validate_and_report()与print_grafana_validation_report()，将验证结果格式化为可读报告；作为 CLI 运行时支持--service、--run-id、--wait参数，并以退出码 0/1 表达通过/失败。

而 tests/e2e/grafana_validation/test_grafana_cloud_queries.py 则对三个数据源分别做了真实查询冒烟：Loki 日志查询{service_name=~".+"}、Mimir 指标查询vector(1)、Tempo trace 查询grafana-smoke-test——这些都是打向真实 Grafana 实例的请求，没有任何模拟响应。

2.2 真实 Live 安装器（CDN / GitHub / Homebrew）

tests/e2e/install/test_live_installers.py 的文件头注释写得很直白："Real CDN / GitHub / Homebrew (no curl shim)"。它验证的是用户真实首次安装路径：

• test_live_cdn_serves_install_sh：curl -fsSL https://install.opensre.com必须返回真实 bash 安装脚本；
• test_live_install_sh_main_to_temp_dir：在隔离的临时目录中真实执行bash install.sh --main，随后运行--version校验，并断言不会破坏仓库.venv/bin/opensre的 editable 安装；
• test_live_install_sh_release_channel：模拟真实用户curl -fsSL https://install.opensre.com | bash -s -- --release，并断言安装器输出中包含校验和验证证据（assert_checksum_verified要求输出中出现 "verifying checksum" 且不出现 "missing checksum asset"）；
• test_live_brew_tap_and_fetch/test_live_brew_install_and_version：真实执行brew tap、brew fetch、brew install，并检查 PyInstaller 打包布局（_internal目录）与--version输出。

Windows 侧的 test_live_installers_windows.py 对等覆盖install.ps1的发布通道：Invoke-RestMethod -Uri 'https://install.opensre.com' | Invoke-Expression，同样要求校验和证据与二进制冒烟（-h、--version、_package-smoke）。这些测试把"安装器是否真的可用"从假设变成了可重复验证的事实。

2.3 真实 Docker 构建与部署健康检查

tests/e2e/deploy/conftest.py 在 session 级 fixture 中真实执行docker build仓库根目录的 Dockerfile，生成带随机 tag 的镜像并在 teardown 时清理；test_dockerfile_builds.py 用docker image inspect验证构建产物确实存在。更进一步，test_health_endpoint.py 会真实启动容器（映射随机空闲端口到容器内 2024 端口），通过 infrastructure/deployment/ec2/health_poll.py 的poll_deployment_health()轮询健康端点，直到GET /ok返回{"ok": true}；配套的失败用例则验证对不可达目标会抛出带 "timed out" 的TimeoutError。

2.4 真实第三方 API 集成

• test_incident_io_e2e.py：在INCIDENT_IO_API_KEY存在时，用make_incident_io_client连接真实 incident.io，执行list_incidents列表查询，并在显式开启INCIDENT_IO_E2E_WRITEBACK=1且提供测试 incident ID 时，执行真实的事故摘要回写（append_summary_update）；
• tests/e2e/posthog/test_orchestrator.py：在POSTHOG_PERSONAL_API_KEY与POSTHOG_PROJECT_ID存在时，通过posthog_config_from_env()+validate_posthog_config()对真实 PostHog 项目 API做配置校验。

为何坚持不 Mock？源码中的注释给出了答案：Mock 会让测试"针对人造载荷验证 Agent"，而不是"针对生产实际产生的载荷"。对于 AI SRE Agent 这类与外部观测、告警、协作系统深度耦合的软件，真实集成测试是唯一能发现"契约漂移"（如 API 字段变更、datasource UID 丢失、Tempo 后端启动异常）的手段。

三、原则二：关注点分离，纯业务逻辑

第二条原则要求：测试所驱动的任何业务工作负载代码必须与测试编排/可观测性代码隔离。被测试的代码应当看起来像真实客户代码，从而验证的是"面向生产级系统的行为"，而不是"面向被插桩系统的行为"。其反模式是：把测试基础设施混进业务逻辑。

3.1 工具函数与测试用例分离

在tests/e2e/grafana_validation/中，这一原则体现为清晰的职责分层：

• grafana_validation.py 是可复用的验证工具（可被业务侧脚本 import，也可作为 CLI 独立运行），它只负责"查询真实遥测并给出结论"，不关心 pytest 的组织方式；
• test_grafana_cloud_queries.py 是测试编排层，负责环境门控、fixture 构建、成功/跳过/失败判定。

业务代码通过from tests.e2e.grafana_validation.grafana_validation import validate_grafana_telemetry这种普通 import 方式使用工具函数，验证逻辑本身对 pytest 零依赖——这正是"看起来像真实代码"的体现。

3.2 确定性种子数据：Tempo 本地注入

tests/e2e/tempo/local_seed.py 展示了"业务侧可观测性数据"与"测试编排"分离的另一个角度：它向本地 Grafana Tempo 的 OTLP/HTTP 端点（http://127.0.0.1:4318/v1/traces）注入一条确定性的 trace——固定traceId、checkout-service服务名、POST /checkoutspan、HTTP 500 状态与"seeded failure"状态信息。而 test_local_seed.py 只对载荷结构做断言（服务名、traceId、span 名、2 秒持续时间、status code 500），并不关心 Tempo 内部实现。业务侧可以依赖这条可复现的故障 trace 做后续检索验证，测试与业务负载互不纠缠。

3.3 进程内完整链路的 E2E 验证

需要说明的是，tests/e2e/目录内的真实夹具是规范"权威示例"，而目录内也包含少量进程内编排型用例（例如 tests/e2e/trello/test_orchestrator.py 对 Trello 配置校验与建卡编排的断言）。这类用例聚焦编排逻辑本身的正确性（如校验失败路径应返回 401 相关信息），与"无 Mock"原则针对的真实基础设施验证互为补充，二者共同构成 E2E 体系的两翼。

更有代表性的是 tests/e2e/test_bug_fixes.py：它验证 guardrail重叠关键字脱敏的完整scan → audit → redact管线，驱动的是 infrastructure/safety/guardrails/evaluator.py 中真实的GuardrailEvaluator（而非简化副本）。底层实现中，_redact()通过合并重叠ScanMatch区间生成_MergedSpan，并让宽度最大的源匹配赢得代表规则名——这正是"长关键字优先、不留_key/word残渣"的实现基础。例如：

evaluator = GuardrailEvaluator( [ _make_rule(name="generic", keywords=["secret"]), _make_rule(name="specific", keywords=["secret_key"]), ] ) result = evaluator.apply("export secret_key=hunter2") assert "_key" not in result # 长关键字必须整体胜出

这说明 OpenSRE 的 E2E 不止于"打外部 API"，也包括在真实生产组件之间贯穿关键链路——同样要求被测对象是未经简化的业务实现。

四、原则三：环境门控，大声跳过

第三条原则是整套 Live E2E 体系的可运维性基石：

Live suites declare their required credentials/environment up front and skip with a clear reason when they are absent, so CI without secrets stays green without hiding failures from runs that do have credentials.

即：套件前置声明所需凭据/环境；缺失时以明确理由跳过。这样，无密钥的 CI 保持绿色，同时持有凭据的运行中的失败也不会被掩盖。

4.1 门控实现：env_requirements.py

tests/e2e/grafana_validation/env_requirements.py 是"声明前置依赖"的模板实现：

• require_grafana_cloud_env()：收集GCLOUD_OTLP_ENDPOINT、GCLOUD_OTLP_AUTH_HEADER、GCLOUD_HOSTED_METRICS_ID/URL、GCLOUD_HOSTED_LOGS_ID/URL、GCLOUD_RW_API_KEY共 7 项，任何一项缺失即pytest.skip(f"...; missing env vars: {', '.join(missing)}")，跳过信息里精确列出缺了哪些变量；
• require_grafana_query_env(account_id=None)：按账户归一化选择 token/实例变量名，默认账户tracerbio对应GRAFANA_READ_TOKEN+GRAFANA_INSTANCE_URL，其他账户对应GRAFANA_<ACCOUNT>_READ_TOKEN+GRAFANA_<ACCOUNT>_INSTANCE_URL，随后以同样方式跳过。

这两类门控覆盖了"写遥测"与"读查询"两种能力需求，且命名上区分GCLOUD_*（写入侧）与GRAFANA_*（读取侧），职责清晰。

4.2 "大声跳过"的完整语义分层

test_grafana_cloud_queries.py 把"skip loudly"演绎成了精细的失败分类表——只有当结果是确定性失败时才pytest.fail，其余情况都以带明确原因的 skip 退出：

_grafana_client_or_skip()进一步说明：get_grafana_client会重抛传输层超时以便产品熔断器跳闸，而 Live 验证必须把同样的失败视为 skip 而非 ERROR——这是对"CI 无密钥保持绿色、有凭据不隐藏失败"两个目标的精确折中。该文件还用纯函数测试（如传入{"error": "403 Forbidden"}、Tempo ring 错误文本等）锁定了这套分类逻辑本身的行为。

4.3 其他套件的门控模式

• Live 安装器：模块级pytestmark用OPENSRE_LIVE_INSTALL != "1"跳过（提示 "Set OPENSRE_LIVE_INSTALL=1 to run live installer e2e"），POSIX 侧还因sys.platform == "win32"跳过、Homebrew 用例因brew不存在而跳过；
• Docker 部署：RUN_DEPLOY_DOCKER_TESTS=1与docker info可用性双重门控；
• incident.io / PostHog：分别以INCIDENT_IO_API_KEY、POSTHOG_PERSONAL_API_KEY+POSTHOG_PROJECT_ID的存在与否做模块级 skip，回写类用例还需显式INCIDENT_IO_E2E_WRITEBACK=1才执行（写操作默认关）。

4.4 CI 侧的自动化：Installer Canary

真实安装路径的 Live 验证由 .github/workflows/installer-canary.yml 编排：发布后通过repository_dispatch（installer-release-published）触发，并辅以每日 cron 与手动触发（可传tag参数固定版本）。工作流在 Linux / macOS arm64 / Windows 三平台矩阵上设置OPENSRE_LIVE_INSTALL=1与OPENSRE_LIVE_INSTALL_TAG，分别运行 POSIX 与 PowerShell 安装器用例，并上传失败日志诊断包；report任务在失败时自动打开（或持续更新、恢复后关闭）带installer-canary-failure标签的追踪 issue——"跳过是常态、失败要可见"的原则在发布后金丝雀中体现得淋漓尽致。

五、实操：本地如何运行这些 Live E2E 测试

由于默认 pytest 会排除tests/e2e，运行前必须显式打开开关并提供对应环境变量：

5.1 Grafana Cloud 遥测验证

# 前置：在 .env 或环境变量中配置 export GCLOUD_OTLP_ENDPOINT=... export GCLOUD_OTLP_AUTH_HEADER=... export GCLOUD_HOSTED_METRICS_ID=... export GCLOUD_HOSTED_METRICS_URL=... export GCLOUD_HOSTED_LOGS_ID=... export GCLOUD_HOSTED_LOGS_URL=... export GCLOUD_RW_API_KEY=... # 查询冒烟测试（凭据缺失或 401/403 时自动跳过） python3 -m pytest tests/e2e/grafana_validation/test_grafana_cloud_queries.py -v # 查询侧读取凭据（默认账户 tracerbio） export GRAFANA_READ_TOKEN=... export GRAFANA_INSTANCE_URL=https://tracerbio.grafana.net # 可选，有默认值 # 业务侧校验工具（验证指定服务遥测是否入库） python3 tests/e2e/grafana_validation/validate_grafana_cloud.py

5.2 Live 安装器（发布后金丝雀路径）

# POSIX（Linux/macOS） OPENSRE_LIVE_INSTALL=1 uv run pytest tests/e2e/install/ -q # Windows $env:OPENSRE_LIVE_INSTALL = "1"; uv run pytest tests/e2e/install/test_live_installers_windows.py -q # 可选：固定具体发布版本 export OPENSRE_LIVE_INSTALL_TAG=v0.1.2026.6.26

测试会真实请求install.opensre.com、GitHub release 解析与 Homebrew tap，并要求安装器输出校验和验证证据（assert_checksum_verified）以及二进制冒烟（--version/-h/_package-smoke）。

5.3 Docker 部署验证

RUN_DEPLOY_DOCKER_TESTS=1 uv run pytest tests/e2e/deploy/ -v

先真实构建镜像，再启动容器轮询健康端点直至GET /ok返回{"ok": true}。

5.4 第三方集成与本地 Tempo

# incident.io（写回需额外开关） export INCIDENT_IO_API_KEY=... uv run pytest tests/e2e/incident_io/ -v # PostHog export POSTHOG_PERSONAL_API_KEY=... POSTHOG_PROJECT_ID=... uv run pytest tests/e2e/posthog/ -v # 向本地 Tempo 注入确定性故障 trace（供链路验证） python3 tests/e2e/tempo/local_seed.py

六、实践要点小结

把 tests/e2e/AGENTS.md 的三条原则提炼为可执行的工程清单：

1. 真实优先：凡是外部集成，优先打真实服务；Mock 只允许出现在"纯编排逻辑"的窄边界内，绝不能替代对生产载荷的验证。
2. 业务与编排分离：验证工具应可被业务侧独立复用（如validate_grafana_telemetry），测试文件只负责门控、组织与断言；反模式是把测试插桩混入业务实现。
3. 前置声明 + 分类跳过：每个 Live 套件在入口处声明所需凭据；把"配置缺失 / 凭据被拒 / 瞬时网络 / 后端抖动"归为带理由的 skip，只对确定性失败fail——让无密钥 CI 常绿，同时让有凭据的运行不掩盖真实失败。
4. CI 编排闭环：用norecursedirs与自定义 marker 隔离默认测试；用独立工作流（如 Installer Canary）在发布后自动跑真实路径，失败自动开 issue 跟踪。

这套规范的本质是：把"真实环境"当作被测对象的一部分——AI SRE Agent 的价值恰恰在于对生产系统做出正确响应，只有不插桩的真实端到端验证，才能让这份承诺可被持续证明。

【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre