如何运行 Appsmith Cypress 集成测试：配置账号、run 模式与 RAPID

如何运行 Appsmith Cypress 集成测试：配置账号、run 模式与 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

本文解决的问题是：在本地把 Appsmith 的 Cypress 集成测试真正跑起来，并完成账号配置、选择 run/open 两种执行模式、用 RAPID_MODE 加速调试。Cypress 测试套件位于app/client/cypress，测试 spec 必须放在app/client/cypress/e2e目录下；默认配置在 app/client/cypress.config.ts。适用前提是：已按 contributions/ClientSetup.md 完成本地客户端环境搭建（Docker、mkcert证书、/etc/hosts中添加dev.appsmith.com、yarn等），或者打算用仓库自带的 setup 脚本拉起本地 Docker 服务栈。跑通后你会得到一个可以在命令行无头执行、并能在调试时跳过重复环境准备步骤的测试环境。

准备条件

仓库已 clone 到本地，且依赖可用。按 contributions/ClientSetup.md 的要求，开发机需要：Docker、mkcert（用于生成本地 HTTPS 证书）、envsubst、全局yarn（npm install -g yarn）。
测试请求的目标地址由cypress.config.ts中的baseUrl决定，默认是https://dev.appsmith.com/。如果你本地按文档用start-https.sh起前端代理，需要保证该地址可访问；临时更换 baseUrl 可以直接改 app/client/cypress.config.ts（setup 脚本启动时会读取该值并提示你核对是否正确）。
app/client下依赖已安装：
```
cd app/client yarn install
```

配置测试账号

Cypress 测试通过USERNAME/PASSWORD环境变量登录被测系统。文档给出的配置位置是cypress.config.ts的env字段（见 TestAutomation.md）：

{ "USERNAME": "Enter username", "PASSWORD": "Enter password" }

其中Enter username、Enter password替换为你本地测试环境的真实账号。仓库中app/client/cypress.config.ts里的env默认值是占位内容（"xxxx"/"xxx"），需要替换后才能登录。

另外，仓库提供的 setup 脚本会在app/client/cypress.env.json不存在时自动创建该文件，并写入一套默认测试账号（testUser@test.com/testPass及 viewer、developer 两套子账号，见 cypress-local-setup.js）。如果你用本地 Docker 服务栈跑测试，通常用这套默认账号即可，再按需修改。

补充规则（来自 TestAutomation.md）：.env文件中的所有 ENV 变量、以及process.env中所有APPSMITH_*变量，都可以在测试里通过Cypress.env()读取；给套件新增环境变量时，应同时更新cypress.config.ts和该文档。

初始化本地测试环境

仓库提供了一个交互式 setup 脚本（cypress-local-setup.js），从仓库根目录运行：

cd app/client/cypress/scripts yarn install yarn run setup

脚本会依次做以下事情，注意其中会拉取并启动 Docker 容器、修改本地app/client依赖，运行前确认本机 Docker 可用：

读取cypress.config.ts中的baseUrl并打印提示，让你核对。
询问是否用 Docker 拉起本地服务：Do you wish to continue without setting up the local server with docker? (yes/no)。选no会在deploy/docker目录执行docker-compose up -d（基于appsmith-ce:release镜像的服务栈），并轮询docker-compose ps直到服务显示Up；选yes则跳过本地服务搭建。
检测https://dev.appsmith.com是否可访问，不可访问时询问是否继续（no会直接退出进程）。
在app/client执行yarn install，并创建app/client/cypress.env.json（若不存在）。
询问是否拉取并运行 TED（TestEventDriver）容器：docker run --name ted --rm -d --pull always -p 2022:22 -p 5001:5001 -p 3306:3306 -p 28017:27017 -p 5433:5432 -p 25:25 -p 4200:4200 appsmith/test-event-driver。选no则本地不创建 TED 环境。
结束时打印后续命令提示（npx cypress open、npx cypress run --spec <specpath> --browser chrome）。

脚本输出中INFO: Local server is up and running.表示本地服务栈已就绪。

运行测试：run 模式与 open 模式

Cypress 支持两种执行模式，测试文件统一放在app/client/cypress/e2e（spec 默认匹配cypress/e2e/**/*.{js,ts}）。子目录名表示测试所属领域，例如回归测试都在app/client/cypress/e2e/Regression。

run 模式（无头执行，走命令行）：

cd app/client npx cypress run --spec <spec path> --browser chrome

把<spec path>换成具体 spec 文件路径。例如要跑Regression下的全部测试，TestAutomation.md 给出的示例是：

$(npm bin)/cypress run --headless --browser chrome --spec "cypress/e2e/Regression/*/*"

open 模式（打开 Cypress 客户端，可视化运行）：

cd app/client npx cypress open

Cypress 支持 Chrome / Firefox / Electron，在客户端里选择浏览器后即可查看测试状态。

结果验证方式：open 模式下直接在客户端查看每个用例的状态；run 模式使用 HTML 报告，报告输出目录由cypress.config.ts的reporterOptions.reportDir配置，默认写入results目录（html: true），运行结束后打开其中的 HTML 报告核对用例通过情况。

RAPID_MODE 加速调试

完整跑一遍用例时，套件每次都会做重复的环境准备（新建测试 app、登录、多次访问 workspace 页）。调试或编写新测试时，可以启用 rapid mode 跳过其中几步（见 TestAutomation.md）：

复用指定 app，不再每次创建新测试 app（传入 app id）；
上一次测试会话已登录时跳过登录；
测试使用 DSL 加载 fixture 时，跳过多次访问 workspace 页。

配置块示例（来自 RapidMode.ts 头部的样例配置）：

{ "RAPID_MODE": { "enabled": true, "appName": "5f8e1666", "pageName": "page-1", "pageID": "64635173cc2cee025a77f489", "url": "https://dev.appsmith.com/app/5f8e1666/page1-64635173cc2cee025a77f489/edit", "usesDSL": true } }

上面的appName、pageName、pageID、url均为文档示例值，必须替换成你自己的 app 信息。两个要点：

url与appName/pageName/pageID二选一：填了完整url就直接使用它；不填url时，测试侧会按app/${appName}/${pageName}-${pageID}/edit自行拼出地址。
usesDSL：测试不用 DSL 时设为false；用 DSL 时设为true，即可跳过多次访问 workspace 页。

关于放置位置，两份文档的说法需要对照着看：TestAutomation.md 说把该配置加到cypress.config.ts；而 RapidMode.ts 的头部注释写的是“append toapp/client/cypress.env.json”，setup 脚本也正是生成app/client/cypress.env.json。由于 Cypress 的 env 合并机制，两个位置都能被Cypress.env("RAPID_MODE")读到（见 RapidMode.ts 第 19 行），可按自己的习惯任选其一，但两处不要各写一份互相冲突的值。

限制与排查要点

Git 用例：要在本地跑 Git 相关测试，需要在app/server/.env中添加APPSMITH_GIT_ROOT=./container-volumes/git-storage，并且本地运行服务端（而不是走 Docker 容器）。
baseUrl 不可达：setup 脚本和测试都以baseUrl为目标，默认https://dev.appsmith.com。本地前端必须用 https 且不带 3000 端口的该地址访问（/etc/hosts中需有127.0.0.1 dev.appsmith.com，可用cat /etc/hosts | grep appsmith确认，注意 IP 与域名之间不能丢空格）。
spec 目录：spec 只能在app/client/cypress/e2e下，放在其他目录（如cypress/fixtures）不会被执行；cypress/e2e/**/spec_utility.ts是被排除的工具文件，不是可跑的 spec。
重试：cypress.config.ts中retries.runMode为 0，run 模式失败不会自动重试，报告里的失败状态即为最终结果。
WSL 环境：若在 Windows WSL2 下无法访问dev.appsmith.com，需把域名加到 Windows 的C:\Windows\System32\drivers\etc\hosts，并确认 Windows 侧能访问http://127.0.0.1:3000（不通时重启 WSL 通常可解决）。

下一步如果你要新增用例，参考 TestAutomation.md 中对 spec 目录组织的约定：新建领域子目录，把 spec 放入app/client/cypress/e2e下对应目录即可被默认 specPattern 拾取。

【免费下载链接】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），仅供参考