RedisInsight E2E 测试框架完全指南基于 Playwright 的 Chromium 与 Electron 端到端测试【免费下载链接】RedisInsightRedis GUI by Redis项目地址: https://gitcode.com/GitHub_Trending/re/RedisInsight本指南系统讲解 RedisInsight 开源仓库中独立的 Playwright E2E 测试套件位于tests/e2e-playwright/涵盖从环境搭建、配置管理、测试编写到并行/串行执行策略的完整实战路径。读完本文你将掌握如何在本仓库中为 RedisInsight 的 Web 界面Chromium与桌面客户端Electron编写、调试和运行可靠的端到端测试并理解其基于 Page Object Model、项目Project分层与 fixture 体系的底层设计原理。测试套件定位与文档体系RedisInsight 的 E2E 测试经历了从旧版向新版演进的历程tests/e2e-playwright/下的 README 明确将其定义为 RedisInsight E2E Tests v2即独立的 Playwright E2E 测试套件Standalone Playwright E2E test suite与仓库根目录下另一套基于 Jest 的redisinsight/test/api测试可参考 test/api/README.md形成互补API 测试聚焦后端逻辑而本套件聚焦真实 UI 交互与桌面端行为。该目录的 README 同时承担了「入口导航」职责它维护了两份关键配套文档文档用途tests/e2e-playwright/TEST_PLAN.md测试覆盖状态与优先级清单按功能区域数据库管理、Browser、Workbench、CLI、Pub/Sub、Analytics、Settings、Vector Search、Cloud、Sentinel、RDI 等组织用 ✅已实现/ 未实现/ ⏳进行中/ ⏸️跳过标记每个用例的进度.ai/skills/e2e-testing/SKILL.md编写测试的标准与模式约定编码规范、命名、断言风格等是新增测试前必读的规范文档TEST_PLAN.md不仅是状态清单还直接映射到测试文件——例如 Vector Search 部分为每个用例标注了对应 spec 文件路径如tests/serial/vector-search/query/query-editor.spec.ts测试用例标题要求与 spec 文件中的实际测试标题完全一致便于按图索骥。内置 AI 命令Augment AIREADME 提供两个与 Augment AI 配合使用的命令用于生成与修复测试命令说明e2e-generate url [focus]借助 Playwright MCP 探索 UI 并生成测试e2e-fix test-pattern运行测试并修复失败示例e2e-generate http://localhost:8080/browser add key e2e-fix Analytics Slow Log这两个命令在 .ai/commands/e2e-generate.md 与 .ai/commands/e2e-fix.md 中有完整定义e2e-generate通过 Playwright MCP 的browser_navigate_Playwright/browser_snapshot_Playwright/browser_click_Playwright逐步探索页面优先利用data-testid、元素 role、占位符等可访问性信息生成选择器e2e-fix则使用npx playwright test --grep pattern --reporterlist运行目标测试读取test-results/test-folder/error-context.md含页面快照、错误信息、调用日志进行诊断修复后强制要求通过npm run lint npx tsc --noEmit才能收尾。环境准备Prerequisites1. 启动 Redis 测试环境RTE所有项目共用同一套 Redis 测试环境RTE使用 Docker Compose 一键拉起cd tests/e2e docker-compose -f rte.docker-compose.yml up -d该 Compose 文件tests/e2e/rte.docker-compose.yml会拉起多种 Redis 拓扑实例包括不同版本的 standalone、cluster、sentinel、TLS 实例等端口与 tests/e2e-playwright/example.env 中的OSS_STANDALONE_*、OSS_CLUSTER_*、OSS_SENTINEL_*配置一一对应例如 standalone 默认在127.0.0.1:8100cluster 在127.0.0.1:8200sentinel 在127.0.0.1:28100。2. /etc/hosts 配置本地运行一次性设置Cluster 测试尤其依赖 host 解析。集群节点通过cluster-announce-hostname向客户端通告主机名API 需要在你的宿主机上解析这些名字因此本地运行时必须追加以下条目127.0.0.1 host.docker.internal 127.0.0.1 master-hostname-7-1 master-hostname-7-2 master-hostname-7-3若不配置集群测试在创建数据库时会失败报500/errorCode 12500Server closed the connection.。两个易踩的坑README 特别强调每一行必须是独立的行且上一行末尾要换行否则会拼成127.0.0.1 existing-entry127.0.0.1 host.docker.internal这样的错误行配置后可用grep -n host.docker.internal\|master-hostname /etc/hosts验证。值得一提的是这个问题的根源在源码中有据可查tests/e2e-playwright/helpers/api.ts 的注释指出Docker 任务中曾出现的长时卡顿正是因为应用无法解析集群通告的主机名最终通过在 Compose 文件中修复而非延长重试等待解决。3. 项目特定启动方式项目启动命令运行测试Chromiumnpm run dev:apinpm run dev:ui两个终端npm run test:chromiumElectronnpm run package:prodnpm run test:electron启动命令在仓库根目录执行测试命令在tests/e2e-playwright/目录内执行。Chromium 模式需要同时跑起 API默认http://localhost:5540与 UI默认http://localhost:8080Electron 模式则需要先打包出可执行产物测试时由 Playwright 直接拉起桌面应用。安装依赖cd tests/e2e-playwright npm install npx playwright install chromium该目录是独立 npm 包见 tests/e2e-playwright/package.json核心依赖包括playwright/test^1.61.1、faker-js/faker^10.5.0用于测试数据生成、fishery^2.4.0用于声明式数据工厂、dotenv环境变量加载并集成了eslint、prettier、huskylint-staged的完整质量门禁提交前自动 lint/format 变更的.ts文件。配置环境变量与多环境支持复制模板并修改为本机环境cp example.env .env核心环境变量如下变量说明默认值RI_CLIENT_URLRedisInsight UI 地址http://localhost:8080RI_API_URLRedisInsight API 地址http://localhost:5540RI_ELECTRON_API_URLElectron 内嵌 API 地址http://localhost:5530见 config/app.tsELECTRON_EXECUTABLE_PATHElectron 可执行文件路径可覆盖默认值平台相关见下文表格OSS_STANDALONE_*standalone Redis 连接信息含 V5/V7/V8/8.8.0/空库/TLS 等多实例127.0.0.1:8100等OSS_CLUSTER_*cluster Redis 连接信息含 hostname 通告实例127.0.0.1:8200等OSS_SENTINEL_*Sentinel 连接信息含密码与主从组名127.0.0.1:28100等REDIS_SSH_*/SSH_*SSH 隧道配置可选注释状态无多环境支持ENV 变量框架通过ENV环境变量切换配置来源底层实现在 config/env.ts# 本地默认—— 加载 .env npm test # CI —— 加载 .env.ci ENVci npm test # Staging —— 加载 .env.staging ENVstaging npm test加载优先级为process.env .env.{ENV} .env先加载环境专属文件再以默认.env兜底且不覆盖已存在的值。currentEnv会导出当前环境名默认local。配套的getEnv/getEnvNumber/getEnvOptional帮助函数在变量缺失时抛出明确错误避免静默使用错误配置。运行测试命令速查package.json 中预置了完整的脚本族命令说明npm test运行全部测试所有项目npm run test:chromium仅运行 Chromium 浏览器测试parallel serialnpm run test:chromium:headed带可见浏览器窗口运行npm run test:chromium:debug打开 Playwright Inspector暂停并逐步执行npm run test:chromium:ui打开交互式 UI 测试面板npm run test:electron运行 Electron 桌面测试npm run test:electron:headed带可见 Electron 窗口运行npm run test:electron:debug带 Playwright Inspector 调试npm run test:report查看 HTML 测试报告playwright show-reportnpm run test:codegen录制操作并生成测试代码playwright codegen http://localhost:8080另有test:chromium:parallel、test:chromium:serial、test:electron:parallel、test:electron:serial用于单独运行某一项目serial 变体带--no-deps。Chromium 浏览器测试npm test # 运行全部测试 npm run test:chromium # 仅 Chromium 项目 npm run test:chromium:headed # 观察测试执行 npm run test:chromium:debug # 暂停并逐步调试 npm run test:chromium:ui # 交互式运行器Electron 桌面测试npm run test:electron # 运行全部 Electron 测试 npm run test:electron:headed # 观察应用 npm run test:electron:debug # 用 Inspector 调试自定义可执行文件路径需要覆盖默认路径例如自定义构建位置时ELECTRON_EXECUTABLE_PATH/path/to/your/app npm run test:electron各平台默认路径平台默认路径macOS arm64release/mac-arm64/Redis Insight.app/Contents/MacOS/Redis InsightmacOS x64release/mac-x64/Redis Insight.app/Contents/MacOS/Redis InsightLinuxrelease/linux-unpacked/redisinsightWindowsrelease/win-unpacked/Redis Insight.exeElectron 测试的关键差异单 workerElectron 测试固定以 1 个 worker 顺序执行因为只有一个应用实例更长的超时README 提到 Electron 测试默认 120s 超时浏览器为 60s不过从 playwright.config.ts 的当前配置看四个测试项目统一设置了timeout: 60000而 Electron 启动器本身在 fixtures/base.ts 中为electron.launch设置了timeout: 60000这意味着实际以配置文件为准README 数值可能对应历史版本——动手前请以仓库现状核对UI 驱动导航所有导航都通过 UI 点击完成保证浏览器与 Electron 行为一致同一套测试文件浏览器与 Electron 复用tests/parallel/与tests/serial/下完全相同的测试文件仅在运行项目层面区分。导航方法Navigation Methods为保证跨平台一致性所有导航均基于 UI 操作。BasePage提供基础导航await this.gotoHome(); // 点击 Redis logo → 数据库列表 await this.gotoDatabase(dbId); // 点击数据库 → Browser 页默认每个页面对象都有各自的goto()方法负责导航 等待await settingsPage.goto(); // 设置页 await browserPage.goto(dbId); // 数据库的 Browser 页 await workbenchPage.goto(dbId); // 数据库的 Workbench 页 await analyticsPage.goto(dbId); // 数据库的 Analytics 页 await pubSubPage.goto(dbId); // 数据库的 Pub/Sub 页InstancePage提供已连接数据库内的页签切换await browserPage.navigationTabs.gotoBrowser(); await browserPage.navigationTabs.gotoWorkbench(); await browserPage.navigationTabs.gotoAnalyze(); await browserPage.navigationTabs.gotoPubSub();目录结构总览tests/e2e-playwright/ ├── config/ # 环境配置app/env/databases ├── fixtures/ # 测试夹具页面对象、API 助手 ├── helpers/ # 工具函数ApiHelper、retry 等 ├── pages/ # Page Object Models组件化 │ └── databases/ │ ├── DatabasesPage.ts │ └── components/ │ ├── AddDatabaseDialog.ts │ └── DatabaseList.ts ├── test-data/ # 测试数据工厂 ├── tests/ # 测试文件按项目组织 │ ├── main/ # 主并行测试默认 │ │ ├── browser/ │ │ ├── workbench/ │ │ └── databases/ │ ├── auto-update/ # 自动更新测试串行、特殊环境 │ └── electron/ # Electron 专属测试 ├── types/ # TypeScript 类型定义 ├── setup/ # 各项目的全局 setup/teardown │ ├── browser.setup.ts │ ├── browser.teardown.ts │ ├── electron.setup.ts │ └── electron.teardown.ts └── playwright.config.tsPage Object 结构组件化 POM页面对象采用**组件化component-based**设计以提升可维护性BasePage (abstract) ├── DatabasesPage # 数据库列表页 ├── SettingsPage # 设置页 └── InstancePage (abstract) # 所有数据库实例页的基类 ├── instanceHeader # 数据库名、统计、面包屑 ├── navigationTabs # Browse / Workbench / Analyze / Pub/Sub ├── bottomPanel # CLI / Command Helper / Profiler └── BrowserPage # Browser 专属继承 InstancePage └── WorkbenchPage (future) └── AnalyzePage (future) └── PubSubPage (future)BasePage所有页面共用的导航方法InstancePage已连接数据库内部页面的基类提供共享的 header、页签与底部面板组件级 POMAddDatabaseDialog、KeyList等可复用的 UI 组件通过页面对象暴露await databasesPage.addDatabaseDialog.fillForm(config); await browserPage.keyList.selectKey(keyName); // InstancePage 提供通用组件 await browserPage.instanceHeader.getDatabaseName(); await browserPage.navigationTabs.gotoWorkbench(); await browserPage.bottomPanel.openCli();测试组织并行项目与串行项目测试按执行要求而非功能先分成项目文件夹再按功能细分tests/ ├── parallel/ # 默认 —— 可多 worker 安全并行 │ ├── browser/ │ │ ├── add-key/ │ │ └── key-details/ │ ├── databases/ │ │ ├── add-database/ │ │ └── edit-database/ │ └── workbench/ └── serial/ # 必须顺序执行共享 DB 状态、 │ # 危险命令、向量索引操作等 ├── cli/ ├── vector-search/ └── workbench/Playwright Projects项目定义测试所在文件夹决定了它的执行模式。每个浏览器平台都有一对「并行 串行」项目定义见 playwright.config.ts项目文件夹并行度用途chromium-paralleltests/parallel/并行4 workersChromium 浏览器标准测试chromium-serialtests/serial/串行1 workerChromium 浏览器顺序测试electron-paralleltests/parallel/串行1 worker*Electron 桌面应用标准测试electron-serialtests/serial/串行1 worker*Electron 桌面应用顺序测试* Electron 当前单 worker 运行因为只有一个应用实例。此外配置中还包含browser-setup/browser-teardown/electron-setup/electron-teardown四个生命周期项目通过dependencies与teardown字段挂接到各测试项目上。全局use配置启用了trace: retain-on-failure、screenshot: only-on-failure、video: retain-on-failure并设置 1920×1080 视口与expect.timeout 10000CI 环境下retries: 2、maxFailures: 20本地retries: 1。执行顺序与设计原因每个平台中serial 项目依赖 parallel 项目dependencies: [platform-parallel]因此执行顺序恒为platform-parallel先跑最多 N 个 workerplatform-serial后跑单 worker 逐个执行为何串行而非并发README 给出了三个明确理由串行测试会对共享 RTE Redis 执行破坏性操作FLUSHDB、宽泛的deleteAllIndexes、危险命令。若与并行测试同时运行并行测试可能在自身步骤之间观察到已被清空/擦除的数据库Electron 无法并发运行两个项目桌面应用把内嵌 API 绑定在固定端口5530两个应用实例会冲突。这也印证了 config/app.ts 中electronApiUrl固定指向http://localhost:5530的设计保持心智模型简单Chromium 与 Electron 采用同一执行模型——文件夹位置直接映射到运行顺序。README 还给出前瞻性建议若串行套件膨胀到让该顺序成为 CI 瓶颈正确方向是给串行测试分配专属 Redis 实例或拆成独立 CI 任务而不是回退并发。运行指定项目# 完整平台运行parallel serial npx playwright test --projectchromium-parallel --projectchromium-serial npx playwright test --projectelectron-parallel --projectelectron-serial # 只跑 parallel npx playwright test --projectchromium-parallel # 只跑 serial —— 必须加 --no-deps否则会先触发其依赖的 parallel 项目 # --no-deps 同时跳过 browser-setup所以本地需确保应用已在运行 npx playwright test --projectchromium-serial --no-deps npx playwright test # 全部项目何时该把测试放进tests/serial/测试通过beforeAll共享数据库状态与其他 worker 并发会竞态测试执行危险命令或修改全局应用状态测试覆盖天然串行的流程如环境开关、单资源索引操作。编写测试规范与示例测试按功能区域组织每个测试文件应遵循使用描述性的测试名称遵循AAA 模式Arrange 准备 / Act 执行 / Assert 断言使用Page Object Model进行 UI 交互使用faker生成测试数据使用test-data/中的测试数据工厂在afterEach中通过API清理创建的数据更快更可靠。典型示例来自 READMEimport { test, expect } from ../../../fixtures/base; import { getStandaloneConfig } from ../../../test-data/databases; test.describe(Add Database Standalone, () { test.afterEach(async ({ apiHelper }) { // 通过 API 清理所有测试数据库快速 await apiHelper.deleteTestDatabases(); }); test(should add standalone database, async ({ databasesPage }) { const config getStandaloneConfig(); await databasesPage.goto(); await databasesPage.addDatabase(config); await expect(databasesPage.databaseList.getRow(config.name)).toBeVisible(); }); });注意测试从../../../fixtures/base导入test——这正是自定义 fixture 体系的入口见下文而不是 Playwright 默认的playwright/test。测试数据工厂test-data/databases/index.ts 使用fishery的Factory.define声明式定义各类型连接配置例如export const TEST_DB_PREFIX test-; export const StandaloneConfigFactory Factory.defineAddDatabaseConfig(() ({ host: redisConfig.standalone.host, port: redisConfig.standalone.port, name: ${TEST_DB_PREFIX}standalone-${faker.string.alphanumeric(8)}, }));关键设计所有测试数据库名必须以test-前缀开头TEST_DB_PREFIX这是清理逻辑识别测试数据库的依据——browser.setup.ts中会调用apiHelper.deleteTestDatabases()删除上一轮遗留数据保证每次运行从干净状态开始。faker.string.alphanumeric(8)生成的随机后缀用于避免并行运行时不同 worker 间的命名冲突。API Helper快速搭建与清理apiHelperfixture 用于通过 API 完成测试的搭建/清理比 UI 操作快得多。其核心实现在 tests/e2e-playwright/helpers/api.tstest(should work with pre-created database, async ({ databasesPage, apiHelper }) { // 通过 API 创建数据库快速 const db await apiHelper.createDatabase(getStandaloneConfig()); // 测试 UI 行为 await databasesPage.goto(); await expect(databasesPage.getDatabaseRow(db.name)).toBeVisible(); // 通过 API 清理 await apiHelper.deleteDatabase(db.id); });源码中值得注意的实现细节createDatabase内置了最多 4 次、指数退避2s 起的重试retry工具见 helpers/retry.ts因为创建数据库时应用会先对目标建立 Redis 连接做校验瞬时连接故障会整体失败且应用把这类故障报告为404 Cannot POST /api/databases与真正的路由缺失无法区分因此不能依赖状态码决定是否重试同时为避免「服务端已创建成功但客户端读响应失败」导致的重试重复建库第二次尝试起会先按「名称 host port」匹配采纳已有库因为重名是被允许的请求上下文设置了ignoreHTTPSErrors: trueElectron 测试使用自签名证书以及 Electron 场景下携带X-Window-Id头用于 API 鉴权。深入底层fixture 体系与 setup/teardown自定义 fixturefixtures/base.tsfixtures/base.ts 通过base.extendFixtures, WorkerFixtures扩展出整套测试基础设施这是整套框架的枢纽apiHelperAPI 助手含 EULA 自动接受与销毁featureFlags功能开关覆盖通过路由拦截GET /api/features注入指定标志状态例如test.use({ featureFlags: { vectorSearchV2: true } })即可在测试中启用某功能开关——对应TEST_PLAN.md中 Vector Set 测试需开启dev-vectorSet标志的用法electronAppworker 级当electronExecutablePath被设置时启动 Electron 应用处理 splash 首屏等待、窗口windowId提取X-Window-Id鉴权来源、API 就绪轮询等page根据模式从浏览器或 Electron 应用获取页面并统一执行「跳过 onboarding」通过localStorage.setItem(onboardingStep, null)比等待 UI 更快与功能开关路由拦截一批页面对象 fixturebrowserPage、databasesPage、cliPanel、profilerPanel、vectorSearchPage、typeToConfirmModal等按需实例化。全局 setup / teardown以 setup/browser.setup.ts 为例它在测试前完成两件事健康检查分别请求RI_CLIENT_URLGET /与 APIgetDatabases()任一失败立即报错并提示「请确认 RedisInsight 已运行在对应地址」避免在应用未启动时盲目跑完全套测试遗留数据清理删除上一轮残留的test-前缀数据库打印清理数量。对应地browser.teardown.ts/electron.setup.ts/electron.teardown.ts负责各自的收尾与准备全部通过 Playwright 的dependencies/teardown机制挂载自动在测试前后执行。从零开始跑通第一轮测试实操清单综合以上内容一份可直接照做的步骤清单拉起测试环境cd tests/e2e docker-compose -f rte.docker-compose.yml up -d配置 hosts本地首次按上文追加两行并grep验证启动应用Chromium仓库根目录分别跑npm run dev:api与npm run dev:uiElectron仓库根目录npm run package:prod并按平台设置ELECTRON_EXECUTABLE_PATH安装测试依赖cd tests/e2e-playwright npm install npx playwright install chromium配置环境cp example.env .env按需调整连接信息运行npm run test:chromium浏览器或npm run test:electron桌面调试用test:chromium:debug/test:chromium:ui单项目运行记得处理--no-deps与项目依赖关系查看报告npm run test:report打开 HTML 报告结合 trace/video/screenshot 定位失败。小结RedisInsight 的 E2E 测试套件是一个「单套代码、双端复用」的成熟实践以组件化 POM 抽象 UI、以项目分层隔离并行/串行风险、以自定义 fixture 打通 API 与 Electron 鉴权、以ENV多环境配置适配本地/CI/Staging。理解它的目录约定tests/parallel/vstests/serial/、执行顺序约束与 API 优先的搭建/清理策略你就能稳定地为 RedisInsight 的任意功能模块贡献高质量 E2E 测试。若需深入可继续研读 tests/e2e-playwright/TEST_PLAN.md 的覆盖矩阵以及 .ai/skills/e2e-testing/SKILL.md 的编码标准。【免费下载链接】RedisInsightRedis GUI by Redis项目地址: https://gitcode.com/GitHub_Trending/re/RedisInsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考