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)。这构成了全文三条原则的工程基础这些测试默认不跑、需要显式选择、并且只在使用真实环境时才跑。二、原则一真实端到端测试禁止 MockAGENTS.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_nameprefect-etl-pipeline, execution_run_idabc-123, wait_seconds10, ) print(fLogs found: {result[logs_found]}) print(fTraces 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 / Homebrewtests/e2e/install/test_live_installers.py 的文件头注释写得很直白Real CDN / GitHub / Homebrew (no curl shim)。它验证的是用户真实首次安装路径test_live_cdn_serves_install_shcurl -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 assettest_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_WRITEBACK1且提供测试 incident ID 时执行真实的事故摘要回写append_summary_updatetests/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(namegeneric, keywords[secret]), _make_rule(namespecific, keywords[secret_key]), ] ) result evaluator.apply(export secret_keyhunter2) 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.pytests/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_idNone)按账户归一化选择 token/实例变量名默认账户tracerbio对应GRAFANA_READ_TOKENGRAFANA_INSTANCE_URL其他账户对应GRAFANA_ACCOUNT_READ_TOKENGRAFANA_ACCOUNT_INSTANCE_URL随后以同样方式跳过。这两类门控覆盖了写遥测与读查询两种能力需求且命名上区分GCLOUD_*写入侧与GRAFANA_*读取侧职责清晰。4.2 大声跳过的完整语义分层test_grafana_cloud_queries.py 把skip loudly演绎成了精细的失败分类表——只有当结果是确定性失败时才pytest.fail其余情况都以带明确原因的 skip 退出场景判定处理凭据缺失GRAFANA_READ_TOKEN等前置门控skip列出缺失变量凭据被拒绝401 / 403 / unauthorized / forbidden配置问题skip注明 credentials were rejected网络瞬时故障timed out / connection reset环境抖动skip注明 transient network failureTempo 后端瞬时异常too many unhealthy instances in the ring / live-store is starting后端抖动skip注明 transient backend failuredatasource UID 不可用Unable to find datasource发现超时skip注明 datasource UID not available其余查询失败确定性失败pytest.fail_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_INSTALL1 to run live installer e2ePOSIX 侧还因sys.platform win32跳过、Homebrew 用例因brew不存在而跳过Docker 部署RUN_DEPLOY_DOCKER_TESTS1与docker info可用性双重门控incident.io / PostHog分别以INCIDENT_IO_API_KEY、POSTHOG_PERSONAL_API_KEYPOSTHOG_PROJECT_ID的存在与否做模块级 skip回写类用例还需显式INCIDENT_IO_E2E_WRITEBACK1才执行写操作默认关。4.4 CI 侧的自动化Installer Canary真实安装路径的 Live 验证由 .github/workflows/installer-canary.yml 编排发布后通过repository_dispatchinstaller-release-published触发并辅以每日 cron 与手动触发可传tag参数固定版本。工作流在 Linux / macOS arm64 / Windows 三平台矩阵上设置OPENSRE_LIVE_INSTALL1与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_URLhttps://tracerbio.grafana.net # 可选有默认值 # 业务侧校验工具验证指定服务遥测是否入库 python3 tests/e2e/grafana_validation/validate_grafana_cloud.py5.2 Live 安装器发布后金丝雀路径# POSIXLinux/macOS OPENSRE_LIVE_INSTALL1 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_TAGv0.1.2026.6.26测试会真实请求install.opensre.com、GitHub release 解析与 Homebrew tap并要求安装器输出校验和验证证据assert_checksum_verified以及二进制冒烟--version/-h/_package-smoke。5.3 Docker 部署验证RUN_DEPLOY_DOCKER_TESTS1 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 的三条原则提炼为可执行的工程清单真实优先凡是外部集成优先打真实服务Mock 只允许出现在纯编排逻辑的窄边界内绝不能替代对生产载荷的验证。业务与编排分离验证工具应可被业务侧独立复用如validate_grafana_telemetry测试文件只负责门控、组织与断言反模式是把测试插桩混入业务实现。前置声明 分类跳过每个 Live 套件在入口处声明所需凭据把配置缺失 / 凭据被拒 / 瞬时网络 / 后端抖动归为带理由的 skip只对确定性失败fail——让无密钥 CI 常绿同时让有凭据的运行不掩盖真实失败。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考