Appsmith Cypress 测试套件贡献指南从环境搭建、用例规范到 Rapid Mode 高效调试【免费下载链接】appsmithPlatform to build admin panels, internal tools, and dashboards. Integrates with 25 databases and any API.项目地址: https://gitcode.com/GitHub_Trending/ap/appsmith导读本文基于 contributions/docs/TestAutomation.md 展开系统讲解如何为 Appsmith 的 Cypress 端到端测试套件贡献测试用例从本地环境搭建、cypress目录布局与 spec 放置规范到cypress.config.ts环境变量配置、run/open 两种执行模式再到用于快速调试的 Rapid Mode快速模式加速技巧以及维护者如何在 CI 中登记机密型环境变量。读完本文你将能独立编写、运行并高效调试覆盖 Appsmith 前端功能的 Cypress 测试。背景Appsmith 用 Cypress 驱动端到端回归测试Appsmith 是一个用于快速构建管理后台、内部工具与数据面板的低代码平台其客户端功能复杂数十种 Widget、多种数据源绑定、Git 同步、布局引擎等因此维护了一套规模庞大、层次分明的 Cypress 端到端测试套件用于在每次改动后验证核心链路不被破坏。整套测试位于仓库的 app/client/cypress 目录下配套的 Cypress 版本与相关依赖统一声明在 app/client/package.json当前为cypress: 13.13.0。在开始编写测试之前请务必先完成本地开发环境的搭建见下文因为套件中的大量测试会真实驱动浏览器并调用 Appsmith 的 API 来完成应用创建、DSL 注入、数据校验等操作。第一步搭建本地环境让全部依赖就绪按 contributions/ClientSetup.md 在本地把 Appsmith 跑起来前端开发服务器 后端服务并熟读 Appsmith 产品文档理解被测对象的预期行为。环境就绪后执行依赖安装yarn install。Cypress 等测试依赖会随app/client/package.json一并安装。注意安装完成后会触发postinstall脚本见 app/client/package.json 中的postinstall: node cypress/apply-patches.js yarn init-husky其中cypress/apply-patches.js负责对部分第三方 Cypress 相关代码应用本地补丁补丁文件位于 app/client/cypress/patches确保测试运行时行为与套件预期一致。完成以上两步后node_modules/.bin/cypress与所有辅助库如cypress-wait-until、cypress-xpath、cypress-file-upload、cypress-real-events等即已就绪可以开始本地执行测试。测试套件目录布局速览Cypress 测试整体集中在 app/client/cypress其内部结构大致如下均为本仓库真实存在的目录e2e/测试用例spec的唯一存放位置按被测领域分子目录。fixtures/测试固定数据包括大量 DSL 快照如TableV2NewDsl.json、formWidgetdsl.json、各类真实样本数据Excel/CSV/图片/视频等。locators/控件定位器常量按页面/组件归类。support/Cypress 支持文件与自定义命令例如 commands.js数百个Cypress.Commands.add封装、e2e.js全局before/beforeEach钩子与登录/建应用流程、RapidMode.ts快速模式配置读取。plugins/、scripts/插件与辅助脚本。snapshots/视觉回归image snapshot基线图片。顶层配置与脚本cypress.config.ts、tags.js、test.sh、setup-test-ci.sh等。e2e 目录spec 的唯一归宿仓库对用例放置位置有硬性约束所有测试 spec必须放在app/client/cypress/e2e目录内可以在app/client/cypress下创建其他辅助目录但用例文件本身不能放在 e2e 之外e2e下的子目录名代表被测领域例如app/client/cypress/e2e/Regression回归测试主战场其下又按Apps/、ClientSide/、Enterprise/、ServerSide/进一步划分Sanity/、Smoke/冒烟与健全性验证如Smoke中的登录冒烟GSheet/Google Sheets 插件相关的专项用例。这一约定与 cypress.config.ts 中的扫描规则相呼应specPattern: cypress/e2e/**/*.{js,ts}只收集 e2e 目录下的 JS/TS 用例同时excludeSpecPattern: cypress/e2e/**/spec_utility.ts会排除作为公共工具存在的 spec如cypress/e2e/Regression/ClientSide/Widgets/...下共享的spec_utility.ts避免被当作独立用例执行。配置测试环境变量USERNAME / PASSWORD绝大多数用例需要真实登录因此套件依赖环境变量USERNAME与PASSWORD。默认配置写在 app/client/cypress.config.ts 的e2e.env段{ USERNAME: Enter username, PASSWORD: Enter password }仓库中该文件当前给出的占位值如下env中同时开启了 grep 过滤相关开关env: { USERNAME: xxxx, PASSWORD: xxx, grepFilterSpecs: true, grepOmitFiltered: true, },环境变量注入的补充说明结合仓库现状官方文档规定凡是测试用到的新环境变量都应登记到app/client/cypress.config.ts的env中并同步更新本文所依据的 contributions/docs/TestAutomation.md 中对应章节保证“配置可被查阅”从项目实现看见 e2e.js、commands.js 中大量Cypress.env(...)调用.env文件里的全部变量以及process.env中以APPSMITH_开头的变量都可直接通过Cypress.env()访问。此外 RapidMode.ts 头部注释提示可将 RAPID_MODE 配置放进app/client/cypress.env.json文件说明该文件同样是可用的环境变量注入通道如需在 run/open 时临时覆盖变量也可采用 Cypress 标准做法命令行--env keyvalue或系统环境变量CYPRESS_keyvalue。运行测试的两种模式Open 与 Run配置就绪后即可开始运行。运行前先进入客户端目录cd app/clientCypress 提供两种执行模式可根据场景选用。1. Open 模式交互式调试Open 模式会启动 Cypress 图形客户端方便你边看执行过程边迭代用例$(npm bin)/cypress open启动后选择浏览器Cypress 支持 Chrome / Firefox / Electron再点选具体的 spec 观察用例执行与断言结果。项目还在 app/client/package.json 里提供了封装脚本cytest它会先用测试模式拉起前端开发服务器REACT_APP_TESTINGTESTING、REACT_APP_ENVIRONMENTDEVELOPMENT再打开 Cypressyarn cytest该脚本非常适合“本地起服务 交互式跑测”的开发场景。2. Run 模式命令行无头执行Run 模式用于在命令行中无头headless批量执行适合本地回归验证与 CI。文档给出的标准命令是$(npm bin)/cypress run --headless --browser chrome --spec cypress/e2e/Regression/*/*其中--spec的 glob 与cypress.config.ts的specPattern相互配合。你也可以直接调用 npm 提供的二进制等效命令npx cypress run --headless --browser chrome --spec cypress/e2e/Regression/**/*按标签过滤用例套件通过cypress/grep插件在 cypress.config.ts 的setupNodeEvents中注册并开启grepFilterSpecs: true支持按功能标签筛选。全部可用标签以数组形式维护在 app/client/cypress/tags.js覆盖tag.AccessControl、tag.Table、tag.Git、tag.Sanity、tag.Smoke等数十个领域。因此编写用例时建议在描述中附带对应的tag.*标签方便在大量用例中快速圈定范围。CI 脚本入口app/client/package.json 中的test/test:ci脚本会调用 app/client/cypress/test.sh本地目标默认以 chromium 无头方式执行--envci目标则启用--record --parallel的 CI 并行录制模式需配置CYPRESS_RECORD_KEY与BUILD_ID。注意该脚本为历史遗留入口其内部 spec glob 指向旧目录cypress/integration/Regression_TestSuite/**/*.js而当前 cypress.config.ts 的specPattern已迁至cypress/e2e/**/*.{js,ts}本地新增用例请以 e2e 目录为准。撰写用例的入口支持编写用例时不必从零封装底层操作。套件已在 support/commands.js 中注册了大量领域命令从LoginFromAPI、SignupFromAPI、CreateNewAppInNewWorkspace到addDsl、DeleteAppByApi、各类 Widget 操作命令均有覆盖常用常量与工具位于 support/Constants.js 等文件。以 DSL 注入命令addDsl见 commands.js为例它会从当前 URL 或 Rapid Mode 配置中解析 page id → 查询布局 →PUT /api/v1/layouts/{layoutId}/pages/{pageId}?applicationId...写入 DSL → 再刷新/跳转到编辑器页并等待getWorkspace路由。理解这类封装能显著降低编写用例时对 API 细节的心智负担。需要强调的是测试用例的书写语法遵循标准 Cypress 体系若对某个 API如cy.intercept、cy.request、自定义断言用法不熟建议先参照套件内同类既有用例的写法例如Regression/ClientSide下各 Widget 的用例再结合官方文档逐一确认。Rapid Mode加速调试与用例编写它解决什么问题正常情况下e2e.js 的全局before钩子会为每个测试会话执行一套繁琐的初始化清空 IndexedDB → 访问/setup/welcome→ 通过 API 创建超级用户与多个测试用户 → 逐一登录登出 → 在全新 Workspace 中新建应用。这套流程对首次环境初始化是必要的但在调试单条用例或反复编写用例时纯属浪费时间。为此套件提供Rapid Mode快速模式开关。启用后e2e.js 会跳过上述整套初始化改为仅做轻量准备。文档明确它可跳过以下步骤不再每次新建测试应用传入已存在的应用 id 复用应用避免反复创建新应用跳过重复登录若上一次运行会话已持有SESSIONCookie见 e2e.js 对 Cookie 的判断则不再执行登录跳过对 Workspace 页面的多次访问当用例使用 DSL 注入时若命中 Rapid Mode 的复用分支addDsl可直接使用配置中给定的pageID见 commands.js写完 DSL 后直接cy.visit(RapidMode.url())进入编辑器而非每次重新访问 Workspace 再进入。如何开启在 app/client/cypress.config.ts 的env或按 RapidMode.ts 头部注释所述放入app/client/cypress.env.json中增加RAPID_MODE配置块RAPID_MODE: { enabled: true, appName: 5f8e1666, pageName: page-1, pageID: 64635173cc2cee025a77f489, url: https://dev.appsmith.com/app/5f8e1666/page1-64635173cc2cee025a77f489/edit, usesDSL: true }各字段含义如下字段类型说明enabledboolean是否启用快速模式true启用调试完成应改回falseappNamestring复用应用的名称示例值5f8e1666pageNamestring复用页面的名称示例值page-1pageIDstring复用页面的 Page ID示例值64635173cc2cee025a77f489urlstring可选的完整编辑页 URL一旦提供将优先于上面逐项参数拼接的结果usesDSLboolean用例是否使用 DSL 注入使用 DSL 且置为true时可跳过多次访问 Workspaceurl 的两种提供方式从 RapidMode.ts 的实现可以清晰看到两种用法二选一传完整url直接返回配置中的 URL传appName/pageName/pageID内部自动拼出形如app/{appName}/{pageName}-{pageID}/edit的编辑器地址再交由cy.visit使用。因此调试阶段只需把当前正在编辑的应用三项信息抄进配置或直接粘贴浏览器地址栏里的编辑页 URLRapid Mode 即可让后续每次用例运行都落在“现成应用”上把宝贵的迭代时间花在断言与用例逻辑本身。从源码看 Rapid Mode 的实际生效位置以下三处可印证其工作原理均为仓库真实实现RapidMode.ts单例类构造时读取Cypress.env(RAPID_MODE)缺省为空对象提供url()生成访问地址e2e.js全局before中若RapidMode.config.enabled为真则只启动服务端路由拦截、按需登录、并在usesDSL为假时访问一次RapidMode.url()后即返回而正常模式对应的完整初始化逻辑e2e.js会被跳过commands.jsaddDsl在 Rapid Mode 且usesDSL为真时直接采用配置中的pageID完成 DSL 注入与页面跳转免去 URL 解析与 Workspace 往返。提醒Rapid Mode 只适合“复用已有数据”的调试/开发场景它跳过新应用创建与完整登录注册流程因此不建议在正式的回归/冒烟 CI 运行中开启。维护者专属为 CI 登记机密型环境变量部分测试需要访问 CI 中才存在的机密凭据如第三方服务 token。这类变量只有项目维护者能添加普通贡献者如需新增应先联系维护者协助完成。整体流程如下前往 GitHub 仓库的Settings → Secrets → Actions页面点击 “New Repository Secret”填入 Secret 的名称与值并保存这些值即使被日志打印也会在 CI 输出中被打码在.github/workflows/client.yml中找到 “Setting up the cypress tests” 与 “Run the cypress test” 两个 step——它们分别负责 Cypress 测试环境的准备与用例执行在对应 step 的环境变量中按以下形式引用刚创建的 SecretYOUR_SECRET_KEY: ${{ secrets.APPSMITH_YOUR_SECRET_KEY }}提交并推送.github/workflows/client.yml到默认分支release。注意对构建/工作流文件的改动只有在合并到默认分支后才会生效。对普通功能型环境变量非机密则走本地路径即可加入 cypress.config.ts 的e2e.env同时更新 contributions/docs/TestAutomation.md保持“配置项可被团队查阅”。给贡献者的小结给 Appsmith 贡献一条 Cypress 用例的推荐动线是按 contributions/ClientSetup.md 完成本地环境与依赖准备在 app/client/cypress/e2e 下选择/创建与被测功能匹配的领域目录编写 spec复用 support/commands.js 的既有命令与 fixtures 中的 DSL/数据将USERNAME/PASSWORD配入 cypress.config.ts先用cypress open交互调试再以cypress run --headless验证稳定调试高频迭代时开启RAPID_MODE跳过环境重复初始化涉及新环境变量时登记配置并同步 contributions/docs/TestAutomation.md涉及 CI 机密变量时交由维护者按 Secrets client.yml流程处理。这样既能保证用例位置的规范性也能让本地调试与 CI 执行保持一致最终交付稳定、可维护、可快速定位的端到端回归测试。【免费下载链接】appsmithPlatform to build admin panels, internal tools, and dashboards. Integrates with 25 databases and any API.项目地址: https://gitcode.com/GitHub_Trending/ap/appsmith创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
