OpenObserve 前端 UI 自动化测试实战Playwright 端到端测试框架完全指南【免费下载链接】openobserveOpen source observability platform for logs, metrics, traces, RUM, Session replay, pipelines, SLO and LLM observability. A sophisticated, simple and highly performant alternative to Datadog, Splunk, and Elasticsearch with 140x lower storage costs and single binary deployment.项目地址: https://gitcode.com/GitHub_Trending/op/openobserve导读OpenObserve 作为一款覆盖日志、指标、追踪、RUM、管道、SLO 与 LLM 可观测性的开源平台其 Web 控制台功能庞杂、页面众多如何保证每一次代码改动都不破坏既有功能本指南围绕仓库 tests/ui-testing/README.md 中定义的 Playwright UI 测试方案完整讲解从安装、运行到环境配置的完整流程并结合仓库内真实的 Playwright 配置、全局登录/数据注入脚本与 CI 分片矩阵源码带你掌握这套端到端测试框架的安装方式、执行命令、环境变量体系、核心配置项与 CI 集成原理。读完本文你可以直接在本地或 CI 中搭建并运行 OpenObserve 的 UI 自动化测试套件并理解其单文件配置驱动、全局一次登录、并行分片执行的工程化设计。一、框架定位这是一套怎样的 UI 测试体系OpenObserve 的 UI 自动化测试位于 tests/ui-testing 目录是一套完整的Playwright 端到端E2E测试套件项目内部代号为 zinc-observe-ui-automation源自早期 zincsearch 时代的命名见 package.json 中的name: zincsearch。从目录结构看这套体系包含五个核心组成部分组成部分路径职责测试配置playwright.config.js、playwright-alpha1.config.js浏览器、超时、重试、报告器、CI 行为测试用例playwright-tests/按功能域组织的 spec 文件Alerts、Dashboards、Logs、Metrics、Traces、Pipelines、SLO 等页面对象pages/Page Object 模式封装每个功能域对应一个页面对象目录工具函数playwright-tests/utils/登录、数据注入、指标/追踪/RUM 数据生成、等待与断言助手CI 矩阵ci-matrix/驱动 GitHub Actions 的测试分片清单Playwright 测试用到的真实日志样例数据位于 tests/test-data/logs_data.json全局 Setup 会将其注入到名为e2e_automate的测试流中供各测试用例查询与断言见 global-setup.js。二、环境准备与安装2.1 依赖安装进入测试目录并安装依赖cd tests/ui-testing npm install依赖清单见 package.json核心 devDependencies 包括playwright/test版本 1.55.1测试框架本体dotenv^17.2.1从.env文件加载环境变量types/nodeTypeScript 类型支持。此外测试还依赖winston日志、pixelmatchpngjs像素级图片对比用于截图类断言、googleapis邮件/云服务集成、uuid、date-fns等运行时依赖。2.2 对目标实例的要求这套 UI 测试面向已部署运行中的 OpenObserve 实例本地或远端均可通过ZO_BASE_URL指定目标地址并非内置 mock 服务。测试运行前请确保实例已启动且可访问并有可用的根用户账号。三、运行测试三种方式3.1 方式一Playwright Runner UI推荐原文档推荐使用专用的 Runner 界面进行可视化操作与调试cd playwright-runner npm start启动后打开 http://localhost:3000 即可访问测试运行器界面在 Web 界面中查看用例列表、选择要运行的测试并通过界面设置环境变量详见下文环境配置。3.2 方式二命令行# 运行全部测试 npx playwright test # 按标签运行指定测试-g 后跟 grep 表达式可匹配标题/标签 npx playwright test -g alertsImportExport # 有头模式运行可观察浏览器操作过程便于调试 npx playwright test --headed # 运行单个测试文件 npx playwright test Alerts/alerts-import.spec.js各参数说明参数作用-g grep按测试标题或标签如alertsImportExport过滤用例--headed有头模式打开真实浏览器窗口--configfile指定配置文件如--configplaywright-alpha1.config.js--workersN指定并行 worker 数仓库还内置了若干 npm scripts见 package.jsonnpm test # 等价于 npx playwright test npm run test:poc # 使用 POC 独立配置运行 npm run test:poc:headed # POC 配置 有头模式 npm run test:poc:debug # 输出 Playwright 协议调试日志 npm run report # 打开 POC 的 HTML 报告3.3 测试目录与归档排除所有 spec 文件位于 playwright-tests/ 下按功能域分子目录组织Alerts/、Cloud/、Dashboards/、Logs/、Metrics/、Traces/、Pipelines/、SLO/、RUM/、Workflows/、Reports/、Functions/、Streams/、Infra/等。归档或废弃的用例test-archives/**与*_old.js会被配置自动排除不参与运行见 playwright.config.js。四、环境变量与配置体系原文档明确指出测试可通过Playwright Runner UIWeb 界面设置或环境变量终端或.env文件两种方式配置。以下是仓库源码中实际使用到的完整环境变量体系4.1 必备环境变量playwright.config.js 在加载配置时会主动校验以下三个变量缺失时打印告警变量含义ZO_BASE_URLOpenObserve 实例地址同时作为baseURL供page.goto(/)使用ZO_ROOT_USER_EMAIL根用户邮箱用于登录ZO_ROOT_USER_PASSWORD根用户密码4.2 常用可选环境变量变量含义依据ORGNAME组织标识登录时通过?org_identifier参数建立组织上下文global-setup.jsINGESTION_URL数据注入使用的 API 地址默认回退到ZO_BASE_URLglobal-setup.jsCI置为 true 时启用 CI 专属行为重试 3 次、blob 报告、截图/视频留存等playwright.config.jsSLOW_MO_TESTSTEST_SHARD为 Pipelines 分片启用slowMo: 1000缓解部署环境同步问题playwright.config.jsSKIP_INGESTION置为true时跳过全局数据注入仅登录global-setup.jsZO_RUM_PURGE_STREAM_DATA置为true时在 teardown 阶段清理 RUM 流中 24 小时前的数据global-teardown.js4.3 .env 文件加载机制配置加载流程见 playwright.config.js引入dotenv并执行dotenv.config()自动读取测试目录下的.env文件若 dotenv 不可用回退到系统环境变量加载完成后校验必备变量缺失时在控制台输出告警信息。4.4 从 CI 工作流一键提取环境变量仓库提供了 env.sh 脚本可从.github/workflows/playwright.yml中提取env:段并导出为本地环境变量避免手工维护两份配置source env.sh # 导出到当前 shell ./env.sh # 仅预览将要导出的变量脚本逻辑优先使用yq解析 YAML 的env段并生成export语句若yq不可用则用正则手工解析env:段支持去除引号两种方式都不依赖额外配置维护。五、playwright.config.js 核心配置深度解析playwright.config.js 是整个测试套件的单一事实来源以下逐项拆解其关键决策5.1 超时体系多层超时配置项本地CI说明timeout3 分钟5 分钟单个测试用例超时expect.timeout10 秒30 秒断言expect超时navigationTimeout30 秒90 秒页面导航超时actionTimeout15 秒45 秒动作点击、输入等超时globalTimeout无40 分钟整个测试运行的总时间上限CI 环境下所有超时均显著放宽这是对部署实例网络延迟与页面渲染波动的工程化妥协。5.2 重试与并行retriesCI 下失败用例自动重试3 次本地0 次workers固定5本地与 CI 一致fullyParallel: true不同测试文件之间完全并行forbidOnly: !!process.env.CICI 下若代码中残留test.only会直接构建失败防止误提交调试代码。5.3 报告器ReporterCI 与本地采用完全不同的报告策略CI使用blob报告器输出到blob-report/便于多分片结果合并并挂载自定义的retry-banner-reporter.js——它在用例重试时向 stdout 打印醒目标志弥补 blob 报告不输出日志导致的重试不可见问题本地输出html报告playwright-results/html-report默认不自动打开与json报告playwright-results/report.json供下游报告消费方使用。5.4 浏览器项目与产物留存默认仅启用chromium项目Desktop Chrome 设备配置视口固定1500x1024并授予剪贴板读写权限CI 下 Chromium 以--no-sandbox --disable-setuid-sandbox启动容器环境无用户命名空间失败诊断产物CI 下开启screenshot: only-on-failure与video: retain-on-failuretrace: on-first-retry会在首次重试时收集 Playwright Tracewebkit、移动端、Edge 等项目已注释保留可按需启用。六、全局 Setup / Teardown一次登录、全局注入数据测试套件通过globalSetup与globalTeardown钩子实现运行前统一准备、运行后统一清理。6.1 全局 Setup 流程global-setup.js整个套件只执行一次的初始化包含四大步骤建立组织上下文登录跳转${ZO_BASE_URL}?org_identifier${ORGNAME}优先点击[data-testlogin-as-internal-user]内部用户登录再填写[data-testlogin-user-id-field]、[data-testlogin-password-field]并点击[data-testlogin-sign-in]。值得注意的是代码注释明确指出OInput 组件的外层包装携带data-testname而真正的输入元素携带data-testname-fieldPlaywright 的fill()只能作用于可填充元素因此必须选择带-field后缀的选择器——这是与 OpenObserve 前端组件约定深度绑定的关键细节。登录成功校验等待[data-testnavbar-main-nav]主导航栏出现即视为登录成功并保存认证状态到playwright-tests/utils/auth/user.json后续所有测试上下文复用该 storageState避免每个用例重复登录。全局日志数据注入通过POST ${INGESTION_URL}/api/${ORGNAME}/e2e_automate/_json接口Basic Auth将 tests/test-data/logs_data.json 中的日志批量注入到e2e_automate流返回非 200 即判定失败。追踪与 RUM 数据注入注入 20 条测试追踪数据ingestTraces与 3 类 RUM 错误数据ingestRumErrors。指标数据已从全局 Setup 移除改为在各用例的beforeAll中注入以避免实例指标端点未就绪时产生 404。此外脚本支持两种跳过场景仅运行cleanup.spec.js正则精确匹配文件名或设置SKIP_INGESTIONtrue时跳过全部数据注入。6.2 全局 Teardown 流程global-teardown.jsTeardown 相对轻量核心是可选的 RUM 数据清理OpenObserve 没有按谓词删除的能力RUM 数据流测试会持续向共享的_rumdata/_rumlog/_sessionreplay流写入真实行长期运行会导致数据膨胀。因此当ZO_RUM_PURGE_STREAM_DATAtrue时Teardown 会在所有用例结束后一次性清理 24 小时前的数据ZO_RUM_PURGE_OLDER_THAN_HOURS可调。清理为尽力而为失败不会导致整个运行报错。注意Teardown 刻意不删除user.json因为并行测试文件运行期间删除认证文件会引发竞态条件——这正是全局状态生命周期设计的细节体现。七、云端 / Alpha 环境专项配置playwright-alpha1.config.js 是面向 OpenObserve 云端Alpha 环境的独立配置与本地配置形成互补登录方式不同使用 Dex Continue with Email 登录流环境变量改用ALPHA1_USER_EMAIL/ALPHA1_USER_PASSWORD并自动回填为ZO_ROOT_USER_*供既有 spec 与工具模块复用全局 Setup 不同使用global-setup-alpha1.js登录后执行 UI 组织切换使 Pinia store 绑定目标组织并写出包含 ingest passcode 的cloud-config.json容器化 Chromium 优化启动参数加入--disable-dev-shm-usage容器默认仅 64MB/dev/shm5 个 worker 并行时 Chromium 会耗尽共享内存导致渲染进程崩溃、表现为 runner lost communication以及--no-sandbox --disable-setuid-sandbox --disable-gpu资源竞争策略Alerts 类重型 spec 在共享云组织下并发争抢慢速列表接口通过页面对象层的有界重试 套件级retries: 2吸收抖动且仅失败用例重试不影响通过用例固定超时统一timeout: 5 * 60 * 1000因为 multi-panel 类 spec 在登录与数据注入后本身就需要 2.4~3.0 分钟。若需要运行云端测试ZO_BASE_URLhttps://your-alpha-instance \ ALPHA1_USER_EMAILemail \ ALPHA1_USER_PASSWORDpassword \ ORGNAMEorg \ npx playwright test --configplaywright-alpha1.config.js八、测试组织、Page Object 与常量体系8.1 Page Object 模式pages/ 目录按功能域封装页面对象alertsPages/、dashboardPages/、logsPages/、metricsPages/、tracesPages/、pipelinesPages/、sloPages/、rumPages/等通过 page-manager.js 统一管理配合 commonActions.js 沉淀跨页面公共操作。测试用例只与页面对象交互不直接操作 DOM 细节降低前端结构变更对用例的冲击。8.2 测试常量与最佳实践test-constants.js 集中管理测试数据、字段名与等待时间。特别值得注意其代码注释中的工程主张固定waitForTimeout是 Playwright 中的反模式anti-pattern仅在动画过渡、无法修复的竞态、无加载状态的第三方组件场景下使用。优先的等待方式依次为await page.waitForLoadState(networkidle); // 网络空闲 await element.waitFor({ state: visible }); // 元素可见 await expect(element).toBeVisible(); // 断言式等待 await page.waitForSelector([data-testelement]); // 选择器等待该文件还沉淀了流名常量e2e_automate、e2e_matchall、Kubernetes 语义字段名kubernetes_pod_name、kubernetes_namespace等、SQL 查询模板SUBQUERY / CTE / GROUP_BY与测试优先级 P0/P1/P2。8.3 可视化辅助工具utils/ 中还有一批值得复用的工程化助手MonacoEditorHelper.js操作查询编辑器、webhook-capture.js捕获 Webhook 请求用于告警链路断言、slack-reporter.jsSlack 通知、zip-builder.js、mail-sink.js等支撑了告警、管道、报告等复杂链路的端到端验证。九、CI 分片矩阵测试规模的工程化管控当测试用例达到数百个playwright-tests/ 下共有 330 余个 spec 文件单 job 串行执行已不可行。ci-matrix/README.md 说明了分片方案ci_matrix.json 是 OSS 与 Enterprise 双仓库 Playwright 工作流共享的唯一分片清单CI 通过build-ci-matrix.js在运行时生成矩阵。分片shard字段说明字段含义testfolder分片标签成为 job 名e2e / testfolder须唯一actual_folderplaywright-tests/下的真实目录browser浏览器chromerun_files该分片运行的 spec 文件名列表disabled有意关闭的用例保留记录可 git 追溯quick_mode_enabled以ZO_QUICK_MODE_ENABLED启动该分片服务ingest_allowed_upto允许回溯注入的小时数默认 5 小时SLO-Measurement设为 240因为 SLO 度量 7 天滚动窗口workers固定该分片的--workersN如SLO-Measurement因 SLO 回填 job 并发为 1 而钉死workers: 1管理规格的工程约定包括禁用用例不删除而是移入disabled数组并附原因同一 spec 不能同时出现在run_files与disabled中构建会失败_前缀键被忽略可用于自由备注。十、从零开始运行一套 UI 测试的完整清单综合以上全部内容在本地跑通一套 OpenObserve UI 自动化测试的最小步骤# 1. 安装依赖 cd tests/ui-testing npm install # 2. 配置环境变量任选一种 # 方式 A写入 .env 文件 cat .env EOF ZO_BASE_URLhttp://localhost:5080 ZO_ROOT_USER_EMAILrootexample.com ZO_ROOT_USER_PASSWORDrootpass ORGNAMEdefault EOF # 方式 B从 CI 工作流导出若存在 .github/workflows/playwright.yml source env.sh # 方式 C命令行内联 # ZO_BASE_URL... ZO_ROOT_USER_EMAIL... ZO_ROOT_USER_PASSWORD... ORGNAME... npx playwright test # 3. 运行 npx playwright test # 全量 npx playwright test -g alertsImportExport # 按标签 npx playwright test --headed Alerts/alerts-import.spec.js # 单个文件 有头调试 # 4. 查看报告 npx playwright show-report playwright-results/html-report运行过程中你可以观察全局 Setup 会先自动登录并注入日志/追踪/RUM 测试数据e2e_automate流随后各分片并行执行用例失败时可在 CI 产物中获取截图、视频与 Trace 进行根因分析。这套体系将 OpenObserve 前端数百个页面的功能回归、数据链路验证与 CI 质量门禁统一收口到了 playwright.config.js 一份配置驱动的可重复流程中是理解并扩展 OpenObserve 前端质量保障体系的入口。【免费下载链接】openobserveOpen source observability platform for logs, metrics, traces, RUM, Session replay, pipelines, SLO and LLM observability. A sophisticated, simple and highly performant alternative to Datadog, Splunk, and Elasticsearch with 140x lower storage costs and single binary deployment.项目地址: https://gitcode.com/GitHub_Trending/op/openobserve创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考