ToolJet Cypress 测试指南本地搭建、headed/headless 运行与环境变量配置【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本文是 ToolJet 仓库中 Cypress 测试指南 的深度实战解读。ToolJet 的前端端到端测试全部基于 Cypress 构建测试代码集中在仓库的cypress-tests目录。读完本文你将掌握如何在本地初始化 Cypress 测试环境、以headed有界面与headless无头两种模式运行全部或单个测试用例、通过命令行与配置文件注入pg_host、sso_password等环境变量并结合源码理解 ToolJet 测试套件的目录组织、配置项与自定义命令背后的实现原理。准备工作先完成 ToolJet 本地开发环境搭建端到端测试需要真实的前端与后端服务因此官方文档明确建议在运行 Cypress 测试之前先按照 macOS 本地搭建指南 完成 ToolJet 的本地开发环境配置。这也是 ToolJet 各版本文档中共用的搭建流程。本地搭建完成后ToolJet 服务默认监听在8082端口这与 cypress.config.js 中baseUrl: http://localhost:8082的配置一一对应。如果本地服务地址不同就需要同步修改该配置项详见下文配置文件解析一节。设置 Cypress 测试环境安装依赖进入cypress-tests目录并安装依赖cd cypress-tests npm install依赖安装完成后测试所需的依赖以devDependencies与dependencies两组形式声明在 cypress-tests/package.json 中核心测试框架cypress^15.18.0测试能力扩展cypress/code-coverage代码覆盖率、cypress/webpack-preprocessorWebpack 预处理、cypress-real-events真实用户事件模拟用于 hover 等场景、cypress-real-dnd基于 CDP 的真实 HTML5 拖拽专门解决 react-dnd 的拖拽自动化问题、cypress-mailhog配合 MailHog 验证邮件发送流程辅助工具faker-js/faker生成测试假数据、moment、node-xlsx解析 xlsx 断言导出文件、pdf-parse解析 PDF 断言导出内容、pgNode.js 侧直连 PostgreSQL 数据库执行查询、chrome-remote-interface通过 CDP 协议控制浏览器cypress-real-dnd与chrome-remote-interface的引入值得注意ToolJet 的 App Builder 大量依赖拖拽交互组件拖放、表格列排序等普通 DOM 事件无法触发 react-dnd 的 HTML5 后端因此测试套件在 cypress/support/e2e.js 中通过import cypress-real-dnd/commands注册了基于 CDPChrome DevTools Protocol的真实拖拽命令。这一点在仓库根目录的 CYPRESS_REAL_DND_FIX.md 中有专门说明。运行测试的两种模式Headed 模式交互式调试在cypress-tests目录下执行npm run cy:open该命令对应 package.json 中的脚本cypress open --browserchrome 103, --e2e它会启动 Cypress 的图形化 Test Runner。在此模式下你可以从左侧列表中选择任意测试 spec并单独运行实时观察每一步操作与断言结果配合 Cypress 的时间旅行Time Travel逐帧回放对单个用例进行it.only等调试操作后即时重跑。Headed 模式适合开发新测试或排查失败用例——失败瞬间浏览器会停留在出错现场并自动生成截图。Headless 模式批量执行与 CI在cypress-tests目录下执行npm run cy:run该命令对应 package.json 中的脚本cypress run --browserchrome 103, --headless适合在 CI 或本地批量回归场景使用。Headless 模式下 Cypress 直接按顺序执行全部匹配的 spec 并输出汇总报告不启动交互界面。运行单个测试用例Headless 模式支持通过--spec参数精确定位某个测试文件npm run cy:run -- --spec cypress/e2e/dashboard/multi-workspace/manageSSO.cy.jsnpm run cy:run --会把后面的参数透传给 Cypress CLI。spec 路径以cypress-tests目录为基准例如上文manageSSO.cy.js这类 SSO 管理用例实际位于 cypress-tests/cypress/e2e 之下。当前仓库的测试目录被重构为happyPath组织方式例如平台与用户管理cypress/e2e/happyPath/platform/含commonTestcases、eeTestcases、firstUser等子目录应用构建器cypress/e2e/happyPath/appbuilder/组件、多页面、代码高亮等数据源与插件cypress/e2e/happyPath/marketplace/工作流cypress/e2e/happyPath/workflows/因此按当前目录结构实际运行单个用例的写法通常是npm run cy:run -- --spec cypress/e2e/happyPath/platform/firstUser/firstUserOnboarding.cy.js从源码结构看spec 的命名遵循*.cy.js约定并广泛使用.skip.js后缀标记暂未启用的用例例如codehinter.skip.jsCypress 会跳过这些文件。部分用例还会在文件内通过describe与ifEnv(Enterprise)等条件区分 CE社区版与 EE企业版行为例如 firstUserOnboarding.cy.js 中的cy.ifEnv(Enterprise, ...)写法。环境变量注入不同数据源的测试凭据通过命令行传递环境变量部分测试用例依赖外部数据源PostgreSQL、Elasticsearch、MongoDB、Redis、SMTP 等或 SSO 账号凭据这些值通过 Cypress 的--env参数以 JSON 形式传入npm run cy:open -- --env{pg_host:localhost,pg_user:postgres, pg_password:postgres}在测试代码中通过Cypress.env(pg_host)读取。需要注意带空格的 JSON 必须用引号包裹否则 shell 会将其拆分为多个参数。通过配置文件注入环境变量除了命令行也可以在cypress.config.js中配置环境变量。ToolJet 仓库还提供了模板文件 cypress-tests/cypress.env.example其中罗列了测试套件可能用到的全部环境变量按数据源分组分组环境变量SSO / Git / 第三方账号sso_password、git_user、google_userPostgreSQLpg_host、pg_user、pg_passwordElasticsearchelasticsearch_host、elasticsearch_user、elasticsearch_passwordDynamoDBdynamodb_access_key、dynamodb_secret_keySMTPsmtp_host、smtp_port、smtp_user、smtp_passwordRedisredis_host、redis_port、redis_passwordMongoDBmongodb_connString、mongodb_host、mongodb_user、mongo_passwordBigQuery / Firestorebigquery_pvt_key、firestore_pvt_key对象MySQLmysql_host、mysql_user、mysql_passwordAWSaws_access、aws_secret应用数据库直连app_db对象user、host、database、password、port实际使用时可复制该文件为cypress.env.json并填入真实值。注意测试代码中还引用了Cypress.env(server_host)、Cypress.env(workspaceId)等运行时变量见 apiCommands.js用于拼接后端 API 地址与工作区标识。从源码看环境变量如何被消费环境变量的使用在测试代码中随处可见。以 apiCommands.js 为例cy.apiCreateApp通过Cypress.env(server_host)拼接/api/apps创建应用并以Tj-Workspace-Id请求头携带工作区 ID而app_db则被dbConnection这类任务消费。在 cypress-run.config.js 的setupNodeEvents中注册了dbConnection任务——它使用pg.Pool(dbconfig)建立连接并执行传入的 SQL例如测试中常见的cy.runSqlQueryOnDB(SELECT id FROM users WHERE emaildevtooljet.io;)用于在断言前查询数据库、在夹具阶段创建数据。配置文件解析理解 Cypress 的默认行为ToolJet 的 Cypress 默认配置集中在 cypress-tests/cypress.config.js核心项如下配置项值说明baseUrlhttp://localhost:8082前端服务地址与本地搭建后的默认端口一致specPatterncypress/e2e/happyPath/**/*.cy.js默认扫描的测试文件模式execTimeout180000030 分钟命令最长执行时间适配超长 E2E 场景defaultCommandTimeout/requestTimeout/pageLoadTimeout/responseTimeout30000各类超时均为 30 秒viewportWidth/viewportHeight1440 × 960默认视口尺寸chromeWebSecurityfalse关闭浏览器跨域安全限制便于测试跨域资源retries.runMode2Headless 模式下用例失败自动重试 2 次降低偶发失败干扰testIsolationtrue每个用例独立隔离状态video/videoUploadOnPassesfalse默认不录制视频screenshotOnRunFailuretrue失败自动截图存入cypress/screenshotsprojectIdca6324a0-...Cypress Cloud 项目标识experimentalMemoryManagementtrue开启实验性内存管理规避长跑用例内存膨胀setupNodeEvents依次加载了四个模块cypress/config/tasks自定义 Node 任务如 PDF/xlsx 解析、目录清理、数据库查询、cypress/config/browserConfig浏览器启动配置、cypress/code-coverage/task覆盖率收集以及cypress/plugins/index.js插件入口。这意味着即使不写任何代码测试运行也具备数据库断言、文件解析与覆盖率采集能力。除默认配置外仓库还按测试域拆分出多份专项配置通过--config-file指定CI 中由 cy-ci-run.js 的CONFIG_FILE环境变量驱动cypress-platform.config.js平台/用户/权限相关用例cypress-ee-platform.config.js企业版EE平台用例cypress-appbuilder.config.jsApp Builder 用例specPattern覆盖appbuilder/**/*.cy.jscypress-marketplace.config.js 与 cypress-gitsync.config.js市场插件与 Git 同步用例cypress-run.config.js通用运行配置cypress-run.config.js还演示了on(task, ...)的注册方式readPdf用pdf-parse提取 PDF 文本、readXlsx用node-xlsx解析表格、deleteFolder递归清理下载目录、dbConnection直连数据库。这些都是 E2E 中断言导出文件内容正确的关键手段。CI 场景模块化运行与结果汇总对于持续集成ToolJet 提供了 cy-ci-run.js——它不是简单调用cypress run而是通过 Cypress 的Module APIcypress.run()编程式驱动测试并输出机器可读的summary.jsonCELL当前 CI 单元的人类可读标签如Platform / eeCONFIG_FILE指定--config-file如cypress-ee-platform.config.jsCYPRESS_CONFIG以k1v1,k2v2形式覆盖配置等价于--config例如baseUrlhttp://localhost:4001,server_hosthttp://localhost:3000BROWSER指定浏览器脚本将结果tests、passes、failures、pending、skipped、duration写入summary.json供下游通知如 Slack消费Cypress 自身启动失败或存在失败用例时以非零码退出。这种设计让 CI 每个单元platform / appbuilder / marketplace / gitsync 等都能独立运行并汇总是官方文档运行测试一节在生产环境中的完整落地。常见问题与调试建议连接被拒绝ECONNREFUSED先确认前端服务是否已按本地搭建指南启动且监听8082端口再核对cypress.config.js中的baseUrl。外部数据源用例失败检查对应环境变量是否注入。优先使用--env传参变量较多时建议基于cypress.env.example创建cypress.env.json。拖拽类用例不稳定确认已安装并导入cypress-real-dnd通过 CDP 实现真实 HTML5 拖拽详见 CYPRESS_REAL_DND_FIX.md。偶发失败干扰本地调试默认retries.runMode: 2会自动重试本地可改用--config retries0关闭重试快速定位真实原因。只想跑一个用例headless 下用--spec指定单个*.cy.js文件或用it.only/describe.only临时聚焦再通过cy:open交互式验证。小结ToolJet 的 Cypress 测试体系围绕 cypress-tests 目录展开npm install完成依赖安装npm run cy:open进入 headed 交互模式npm run cy:run走 headless 批量执行并支持--spec定向运行涉及外部数据源的用例通过--envJSON 或配置文件注入凭据CI 场景则由cy-ci-run.js模块化驱动并产出summary.json。理解 cypress.config.js 及各专项配置的超时、重试、视口与任务注册机制再配合cypress/commands下的自定义命令API 创建应用、数据库直查、真实拖拽等你就能高效地为 ToolJet 编写、运行与调试端到端测试。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet Cypress 测试指南：本地搭建、headed/headless 运行与环境变量配置
ToolJet Cypress 测试指南本地搭建、headed/headless 运行与环境变量配置【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本文是 ToolJet 仓库中 Cypress 测试指南 的深度实战解读。ToolJet 的前端端到端测试全部基于 Cypress 构建测试代码集中在仓库的cypress-tests目录。读完本文你将掌握如何在本地初始化 Cypress 测试环境、以headed有界面与headless无头两种模式运行全部或单个测试用例、通过命令行与配置文件注入pg_host、sso_password等环境变量并结合源码理解 ToolJet 测试套件的目录组织、配置项与自定义命令背后的实现原理。准备工作先完成 ToolJet 本地开发环境搭建端到端测试需要真实的前端与后端服务因此官方文档明确建议在运行 Cypress 测试之前先按照 macOS 本地搭建指南 完成 ToolJet 的本地开发环境配置。这也是 ToolJet 各版本文档中共用的搭建流程。本地搭建完成后ToolJet 服务默认监听在8082端口这与 cypress.config.js 中baseUrl: http://localhost:8082的配置一一对应。如果本地服务地址不同就需要同步修改该配置项详见下文配置文件解析一节。设置 Cypress 测试环境安装依赖进入cypress-tests目录并安装依赖cd cypress-tests npm install依赖安装完成后测试所需的依赖以devDependencies与dependencies两组形式声明在 cypress-tests/package.json 中核心测试框架cypress^15.18.0测试能力扩展cypress/code-coverage代码覆盖率、cypress/webpack-preprocessorWebpack 预处理、cypress-real-events真实用户事件模拟用于 hover 等场景、cypress-real-dnd基于 CDP 的真实 HTML5 拖拽专门解决 react-dnd 的拖拽自动化问题、cypress-mailhog配合 MailHog 验证邮件发送流程辅助工具faker-js/faker生成测试假数据、moment、node-xlsx解析 xlsx 断言导出文件、pdf-parse解析 PDF 断言导出内容、pgNode.js 侧直连 PostgreSQL 数据库执行查询、chrome-remote-interface通过 CDP 协议控制浏览器cypress-real-dnd与chrome-remote-interface的引入值得注意ToolJet 的 App Builder 大量依赖拖拽交互组件拖放、表格列排序等普通 DOM 事件无法触发 react-dnd 的 HTML5 后端因此测试套件在 cypress/support/e2e.js 中通过import cypress-real-dnd/commands注册了基于 CDPChrome DevTools Protocol的真实拖拽命令。这一点在仓库根目录的 CYPRESS_REAL_DND_FIX.md 中有专门说明。运行测试的两种模式Headed 模式交互式调试在cypress-tests目录下执行npm run cy:open该命令对应 package.json 中的脚本cypress open --browserchrome 103, --e2e它会启动 Cypress 的图形化 Test Runner。在此模式下你可以从左侧列表中选择任意测试 spec并单独运行实时观察每一步操作与断言结果配合 Cypress 的时间旅行Time Travel逐帧回放对单个用例进行it.only等调试操作后即时重跑。Headed 模式适合开发新测试或排查失败用例——失败瞬间浏览器会停留在出错现场并自动生成截图。Headless 模式批量执行与 CI在cypress-tests目录下执行npm run cy:run该命令对应 package.json 中的脚本cypress run --browserchrome 103, --headless适合在 CI 或本地批量回归场景使用。Headless 模式下 Cypress 直接按顺序执行全部匹配的 spec 并输出汇总报告不启动交互界面。运行单个测试用例Headless 模式支持通过--spec参数精确定位某个测试文件npm run cy:run -- --spec cypress/e2e/dashboard/multi-workspace/manageSSO.cy.jsnpm run cy:run --会把后面的参数透传给 Cypress CLI。spec 路径以cypress-tests目录为基准例如上文manageSSO.cy.js这类 SSO 管理用例实际位于 cypress-tests/cypress/e2e 之下。当前仓库的测试目录被重构为happyPath组织方式例如平台与用户管理cypress/e2e/happyPath/platform/含commonTestcases、eeTestcases、firstUser等子目录应用构建器cypress/e2e/happyPath/appbuilder/组件、多页面、代码高亮等数据源与插件cypress/e2e/happyPath/marketplace/工作流cypress/e2e/happyPath/workflows/因此按当前目录结构实际运行单个用例的写法通常是npm run cy:run -- --spec cypress/e2e/happyPath/platform/firstUser/firstUserOnboarding.cy.js从源码结构看spec 的命名遵循*.cy.js约定并广泛使用.skip.js后缀标记暂未启用的用例例如codehinter.skip.jsCypress 会跳过这些文件。部分用例还会在文件内通过describe与ifEnv(Enterprise)等条件区分 CE社区版与 EE企业版行为例如 firstUserOnboarding.cy.js 中的cy.ifEnv(Enterprise, ...)写法。环境变量注入不同数据源的测试凭据通过命令行传递环境变量部分测试用例依赖外部数据源PostgreSQL、Elasticsearch、MongoDB、Redis、SMTP 等或 SSO 账号凭据这些值通过 Cypress 的--env参数以 JSON 形式传入npm run cy:open -- --env{pg_host:localhost,pg_user:postgres, pg_password:postgres}在测试代码中通过Cypress.env(pg_host)读取。需要注意带空格的 JSON 必须用引号包裹否则 shell 会将其拆分为多个参数。通过配置文件注入环境变量除了命令行也可以在cypress.config.js中配置环境变量。ToolJet 仓库还提供了模板文件 cypress-tests/cypress.env.example其中罗列了测试套件可能用到的全部环境变量按数据源分组分组环境变量SSO / Git / 第三方账号sso_password、git_user、google_userPostgreSQLpg_host、pg_user、pg_passwordElasticsearchelasticsearch_host、elasticsearch_user、elasticsearch_passwordDynamoDBdynamodb_access_key、dynamodb_secret_keySMTPsmtp_host、smtp_port、smtp_user、smtp_passwordRedisredis_host、redis_port、redis_passwordMongoDBmongodb_connString、mongodb_host、mongodb_user、mongo_passwordBigQuery / Firestorebigquery_pvt_key、firestore_pvt_key对象MySQLmysql_host、mysql_user、mysql_passwordAWSaws_access、aws_secret应用数据库直连app_db对象user、host、database、password、port实际使用时可复制该文件为cypress.env.json并填入真实值。注意测试代码中还引用了Cypress.env(server_host)、Cypress.env(workspaceId)等运行时变量见 apiCommands.js用于拼接后端 API 地址与工作区标识。从源码看环境变量如何被消费环境变量的使用在测试代码中随处可见。以 apiCommands.js 为例cy.apiCreateApp通过Cypress.env(server_host)拼接/api/apps创建应用并以Tj-Workspace-Id请求头携带工作区 ID而app_db则被dbConnection这类任务消费。在 cypress-run.config.js 的setupNodeEvents中注册了dbConnection任务——它使用pg.Pool(dbconfig)建立连接并执行传入的 SQL例如测试中常见的cy.runSqlQueryOnDB(SELECT id FROM users WHERE emaildevtooljet.io;)用于在断言前查询数据库、在夹具阶段创建数据。配置文件解析理解 Cypress 的默认行为ToolJet 的 Cypress 默认配置集中在 cypress-tests/cypress.config.js核心项如下配置项值说明baseUrlhttp://localhost:8082前端服务地址与本地搭建后的默认端口一致specPatterncypress/e2e/happyPath/**/*.cy.js默认扫描的测试文件模式execTimeout180000030 分钟命令最长执行时间适配超长 E2E 场景defaultCommandTimeout/requestTimeout/pageLoadTimeout/responseTimeout30000各类超时均为 30 秒viewportWidth/viewportHeight1440 × 960默认视口尺寸chromeWebSecurityfalse关闭浏览器跨域安全限制便于测试跨域资源retries.runMode2Headless 模式下用例失败自动重试 2 次降低偶发失败干扰testIsolationtrue每个用例独立隔离状态video/videoUploadOnPassesfalse默认不录制视频screenshotOnRunFailuretrue失败自动截图存入cypress/screenshotsprojectIdca6324a0-...Cypress Cloud 项目标识experimentalMemoryManagementtrue开启实验性内存管理规避长跑用例内存膨胀setupNodeEvents依次加载了四个模块cypress/config/tasks自定义 Node 任务如 PDF/xlsx 解析、目录清理、数据库查询、cypress/config/browserConfig浏览器启动配置、cypress/code-coverage/task覆盖率收集以及cypress/plugins/index.js插件入口。这意味着即使不写任何代码测试运行也具备数据库断言、文件解析与覆盖率采集能力。除默认配置外仓库还按测试域拆分出多份专项配置通过--config-file指定CI 中由 cy-ci-run.js 的CONFIG_FILE环境变量驱动cypress-platform.config.js平台/用户/权限相关用例cypress-ee-platform.config.js企业版EE平台用例cypress-appbuilder.config.jsApp Builder 用例specPattern覆盖appbuilder/**/*.cy.jscypress-marketplace.config.js 与 cypress-gitsync.config.js市场插件与 Git 同步用例cypress-run.config.js通用运行配置cypress-run.config.js还演示了on(task, ...)的注册方式readPdf用pdf-parse提取 PDF 文本、readXlsx用node-xlsx解析表格、deleteFolder递归清理下载目录、dbConnection直连数据库。这些都是 E2E 中断言导出文件内容正确的关键手段。CI 场景模块化运行与结果汇总对于持续集成ToolJet 提供了 cy-ci-run.js——它不是简单调用cypress run而是通过 Cypress 的Module APIcypress.run()编程式驱动测试并输出机器可读的summary.jsonCELL当前 CI 单元的人类可读标签如Platform / eeCONFIG_FILE指定--config-file如cypress-ee-platform.config.jsCYPRESS_CONFIG以k1v1,k2v2形式覆盖配置等价于--config例如baseUrlhttp://localhost:4001,server_hosthttp://localhost:3000BROWSER指定浏览器脚本将结果tests、passes、failures、pending、skipped、duration写入summary.json供下游通知如 Slack消费Cypress 自身启动失败或存在失败用例时以非零码退出。这种设计让 CI 每个单元platform / appbuilder / marketplace / gitsync 等都能独立运行并汇总是官方文档运行测试一节在生产环境中的完整落地。常见问题与调试建议连接被拒绝ECONNREFUSED先确认前端服务是否已按本地搭建指南启动且监听8082端口再核对cypress.config.js中的baseUrl。外部数据源用例失败检查对应环境变量是否注入。优先使用--env传参变量较多时建议基于cypress.env.example创建cypress.env.json。拖拽类用例不稳定确认已安装并导入cypress-real-dnd通过 CDP 实现真实 HTML5 拖拽详见 CYPRESS_REAL_DND_FIX.md。偶发失败干扰本地调试默认retries.runMode: 2会自动重试本地可改用--config retries0关闭重试快速定位真实原因。只想跑一个用例headless 下用--spec指定单个*.cy.js文件或用it.only/describe.only临时聚焦再通过cy:open交互式验证。小结ToolJet 的 Cypress 测试体系围绕 cypress-tests 目录展开npm install完成依赖安装npm run cy:open进入 headed 交互模式npm run cy:run走 headless 批量执行并支持--spec定向运行涉及外部数据源的用例通过--envJSON 或配置文件注入凭据CI 场景则由cy-ci-run.js模块化驱动并产出summary.json。理解 cypress.config.js 及各专项配置的超时、重试、视口与任务注册机制再配合cypress/commands下的自定义命令API 创建应用、数据库直查、真实拖拽等你就能高效地为 ToolJet 编写、运行与调试端到端测试。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考