1. 项目概述从“能用”到“好用”的自动化测试进阶之路最近在团队里做了一次关于测试自动化的内部分享主题就是如何让我们的Cypress测试套件从“能跑起来”变得“既稳又好维护”。我发现很多刚开始接触Cypress和TypeScript的同事写出来的测试代码虽然功能上没问题但读起来费劲维护起来头疼稳定性也时好时坏。这其实挺常见的自动化测试的初期目标往往是“把流程跑通”但要想让它真正成为研发流程中可靠的一环成为提升效率而非制造麻烦的工具就需要一些经过实战检验的实践来保驾护航。这次我结合自己踩过的坑和团队的最佳实践梳理了14个在TypeScript Cypress环境下简单又实用的技巧。这些实践覆盖了从项目配置、代码结构到测试编写、调试维护的全链路。它们不是什么高深的理论而是你明天就能在项目里用起来的“脚手架”和“工具箱”。无论你是刚入门想写出更规范的测试还是已经有一定经验希望提升测试套件的健壮性和可读性我相信这里面总有一些点能给你带来启发。我们的目标很明确让自动化测试脚本像产品代码一样清晰、可靠、易于协作。2. 环境搭建与配置优化为高效测试奠定基石2.1 TypeScript与Cypress的初始配置要点万事开头难一个合理的初始配置能避免后续无数麻烦。首先确保你的Node.js版本是LTS版本如18.x或20.x这能保证依赖兼容性。使用npm init -y初始化项目后安装核心依赖npm install cypress typescript --save-dev npm install types/node cypress/webpack-preprocessor --save-dev # 用于TypeScript编译接下来是关键的tsconfig.json配置。很多教程给的配置比较基础但在测试项目中我们需要特别关注几个点。首先将target设置为es2017或更高因为Cypress运行在较新的Chrome环境中可以利用现代JavaScript特性。其次module设置为commonjs这是Node.js环境的标准。最重要的是types字段一定要包含cypress和node这样你才能在代码中获得完整的类型提示。{ compilerOptions: { target: es2017, module: commonjs, lib: [es2017, dom], types: [cypress, node], strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, outDir: ./dist, rootDir: ./ }, include: [**/*.ts], exclude: [node_modules, dist] }注意网络热词中提到的“选项‘baseUrl’已弃用”等问题通常出现在更复杂的、将Cypress集成到现有Angular/React项目TypeScript配置中的场景。对于独立的Cypress测试项目使用上述独立的tsconfig.json并明确指定types: [“cypress”]可以完美规避这些兼容性警告无需担心TypeScript 7.0的破坏性变更。然后是cypress.config.ts或.js文件。这里我强烈建议使用TypeScript格式的配置文件以获得类型安全。一个基础的配置如下import { defineConfig } from cypress export default defineConfig({ e2e: { baseUrl: https://your-app.com, // 你的应用基础地址 specPattern: cypress/e2e/**/*.spec.ts, // 测试文件匹配模式 supportFile: cypress/support/e2e.ts, // 支持文件 viewportWidth: 1280, viewportHeight: 720, setupNodeEvents(on, config) { // 可以在这里配置插件 }, }, })这里有个小技巧baseUrl的设置至关重要。它不仅是测试的起点更重要的是Cypress的命令如cy.visit(‘/login’)会自动拼接这个baseUrl让你的测试代码更简洁且易于在不同环境开发、测试、预发布间切换只需修改配置即可。2.2 目录结构设计与支持文件规划清晰的目录结构是团队协作和维护性的基础。我推荐以下结构它分离了关注点cypress/ ├── e2e/ # 所有测试用例文件 (.spec.ts) │ ├── login/ # 按功能模块组织 │ ├── dashboard/ │ └── api/ ├── fixtures/ # 静态测试数据文件 (.json) │ └── test-users.json ├── support/ # 支持文件 │ ├── commands.ts # 自定义命令 │ ├── e2e.ts # 测试运行前加载的文件 │ └── index.d.ts # TypeScript类型定义扩展 ├── downloads/ # 测试运行时下载的文件 ├── screenshots/ # 失败时的截图 ├── videos/ # 测试录像 └── plugins/ # 插件配置 (Cypress 10 或 需要插件时)重点说一下support文件夹。e2e.ts是每个测试文件运行前都会执行的文件这里是放置全局配置的绝佳位置比如忽略掉一些无关紧要的XHR错误、或者设置全局的请求超时。而commands.ts则是你施展“魔法”的地方可以将重复的操作如登录、数据准备封装成自定义命令。index.d.ts文件用于为这些自定义命令添加TypeScript类型提示这是保证开发体验的关键一步。例如在commands.ts中你添加了一个自定义登录命令// cypress/support/commands.ts Cypress.Commands.add(loginByApi, (username: string, password: string) { cy.request(POST, /api/login, { username, password }).then((response) { window.localStorage.setItem(authToken, response.body.token) }) })那么你必须在index.d.ts中声明它的类型否则TypeScript会报错也无法获得代码补全// cypress/support/index.d.ts declare namespace Cypress { interface Chainable { /** * 通过API直接登录跳过UI * example cy.loginByApi(admin, password123) */ loginByApi(username: string, password: string): Chainablevoid } }这个简单的步骤能让你的团队在使用自定义命令时获得和原生Cypress命令一样的智能提示和类型检查极大提升开发效率和代码质量。3. 测试代码编写核心实践编写健壮、可读的测试用例3.1 选择器策略与页面对象模型POM的平衡元素选择器是UI自动化测试的基石糟糕的选择器是测试脆弱的首要原因。Cypress官方推荐使用>!-- 前端代码 -- button>// 测试代码 - 非常稳定 cy.get([data-testidsubmit-login-btn]).click()然而为每个元素都添加>// cypress/support/pages/LoginPage.ts export const LoginPage { selectors: { usernameInput: [data-testidusername], passwordInput: [data-testidpassword], submitButton: [data-testidsubmit-login-btn], errorMessage: .error-text } } // 在测试文件中使用 import { LoginPage } from ../support/pages/LoginPage cy.get(LoginPage.selectors.usernameInput).type(testuser) cy.get(LoginPage.selectors.passwordInput).type(pass123) cy.get(LoginPage.selectors.submitButton).click()这种方式平衡了可维护性和Cypress的原生风格。当元素选择器需要变更时你只需在一个地方修改。3.2 测试数据管理与Fixture的智能使用测试数据管理是另一个核心。硬编码在测试用例中的数据是“坏味道”。Cypress的fixtures文件夹用于存放静态的JSON数据文件非常适合用于 mock API响应或存储固定的测试账户信息。// cypress/fixtures/users.json { admin: { username: adminexample.com, password: Admin123!, role: administrator }, standardUser: { username: userexample.com, password: User123!, role: user } }在测试中加载和使用它beforeEach(() { cy.fixture(users).as(usersData) // 加载并起别名 }) it(使用fixture数据登录, function() { // 注意使用function以访问this const user this.usersData.standardUser cy.get([data-testidusername]).type(user.username) cy.get([data-testidpassword]).type(user.password) // ... 后续操作 })但fixtures是静态的对于需要动态生成或清理的数据如测试创建的订单、文章更好的方式是结合API。我常用的模式是在beforeEach或测试开始前通过API调用cy.request在后台创建测试所需的数据并获取其ID等引用信息在afterEach或测试结束后再通过API清理这些数据。这保证了测试的独立性和可重复性。describe(订单流程测试, () { let testOrderId: string beforeEach(() { // 通过API创建测试订单 cy.request(POST, /api/test/orders, { productId: 123 }).then((resp) { testOrderId resp.body.id // 将订单ID存入环境变量或挂载到window供前端应用访问如果需要 cy.window().then(win { (win as any).__TEST_ORDER_ID testOrderId }) }) }) afterEach(() { // 测试后清理订单 if (testOrderId) { cy.request(DELETE, /api/test/orders/${testOrderId}) } }) it(可以查看订单详情, () { // 访问包含该订单的页面 cy.visit(/orders/${testOrderId}) // ... 进行断言 }) })3.3 断言的艺术与异步操作处理Cypress的断言基于Chai库并且自动处理了异步等待这是它的一大优势。但写出好的断言依然需要技巧。首先断言应该具有表达力描述你期望的“状态”而非“过程”。例如与其断言“点击后按钮应该禁用”不如断言“提交后按钮处于禁用状态”。其次充分利用Cypress提供的丰富断言。除了常见的.should(‘be.visible’)、.should(‘have.text’, ‘xxx’)还有一些非常实用的.should(‘have.class’, ‘loading’) 断言元素具有某个CSS类。.should(‘be.disabled’) 断言表单元素被禁用。.should(‘have.value’, ‘input text’) 断言输入框的值。.should(($el) { expect($el).to.have.length(3) }) 使用回调函数进行更复杂的断言。对于异步操作比如等待一个API调用完成后再进行UI断言Cypress的cy.intercept()和cy.wait()是黄金组合。但要注意cy.wait()是等待一个特定的、被cy.intercept()命中的请求而不是傻等固定时间。it(搜索后显示结果, () { // 拦截搜索API请求并给它起个别名‘searchRequest’ cy.intercept(GET, /api/search?q*).as(searchRequest) cy.get([data-testidsearch-input]).type(Cypress{enter}) // 等待特定的请求完成 cy.wait(searchRequest).its(response.statusCode).should(eq, 200) // 然后断言UI更新 cy.get([data-testidresult-list] li).should(have.length.at.least, 1) })这个模式清晰地表达了“触发动作 - 等待网络请求完成 - 验证结果”的流程比使用cy.wait(5000)这种硬等待可靠得多。4. 提升可维护性与执行效率的进阶技巧4.1 自定义命令与可复用逻辑封装当你在多个测试文件中重复相同的操作序列时就是抽象成自定义命令或工具函数的时候了。自定义命令的优势在于它直接挂载在cy对象下使用起来和原生命令无异非常适合封装与UI强相关的流程。例如一个包含UI操作和API等待的完整登录流程// cypress/support/commands.ts Cypress.Commands.add(loginViaUI, (username: string, password: string) { // 拦截登录API以便等待 cy.intercept(POST, /api/auth/login).as(loginApi) cy.visit(/login) cy.get([data-testidusername]).type(username) cy.get([data-testidpassword]).type(password) cy.get([data-testidsubmit-login-btn]).click() // 等待登录成功 cy.wait(loginApi).then((interception) { expect(interception.response?.statusCode).to.be.oneOf([200, 201]) }) // 断言登录成功后的页面跳转或状态 cy.url().should(include, /dashboard) cy.contains(欢迎回来).should(be.visible) })而对于纯数据准备或工具类函数我更倾向于将其写成普通的TypeScript函数放在一个如cypress/support/utils.ts的文件中导出。这样逻辑更清晰也便于单元测试如果需要。// cypress/support/utils.ts /** * 生成一个随机的测试邮箱 * param prefix 邮箱前缀默认为‘test’ */ export function generateTestEmail(prefix: string test): string { const timestamp new Date().getTime() const random Math.floor(Math.random() * 10000) return ${prefix}${timestamp}${random}example.com } /** * 通过API快速创建一个测试用户并返回凭证 */ export function createTestUserViaApi(userData?: PartialUser): Promise{username: string, password: string} { // 使用cy.request但注意这在support文件非命令中需谨慎最好在测试上下文中调用 return cy.request(POST, /api/test/users, { username: generateTestEmail(), password: TempPass123!, ...userData }).then(resp resp.body) }在测试中使用时直接导入函数即可。这种分离使得“命令”专注于浏览器交互“工具函数”专注于数据和业务逻辑。4.2 配置管理与多环境适配一个专业的测试套件必须能轻松运行在不同环境。Cypress通过环境变量CYPRESS_*或cypress.config.ts中的env对象和配置文件来管理。我推荐使用cypress.config.ts配合dotenv来管理多环境配置。首先安装dotenvnpm install dotenv --save-dev。然后在项目根目录创建不同环境的.env文件如.env.staging、.env.production。在cypress.config.ts中动态加载// cypress.config.ts import { defineConfig } from cypress import * as dotenv from dotenv // 根据CYPRESS_ENV环境变量决定加载哪个配置文件默认为development const envFile .env.${process.env.CYPRESS_ENV || development} dotenv.config({ path: envFile }) export default defineConfig({ e2e: { baseUrl: process.env.CYPRESS_BASE_URL || http://localhost:3000, env: { // 将.env文件中的变量注入到Cypress环境变量中 apiUrl: process.env.CYPRESS_API_URL, adminUser: process.env.CYPRESS_ADMIN_USER, adminPassword: process.env.CYPRESS_ADMIN_PASSWORD, // 也可以定义一些逻辑变量 isProduction: process.env.CYPRESS_ENV production }, // ... 其他配置 }, })在测试中你可以通过Cypress.env(‘apiUrl’)来访问这些变量。这样在CI/CD流水线中只需设置CYPRESS_ENVstaging就能自动指向预发布环境进行测试。4.3 测试分组、钩子与执行策略合理的测试组织能提升运行效率和日志可读性。describe和context用于创建测试套件分组it指定单个测试用例。before、beforeEach、afterEach、after这些钩子函数用于设置和清理。一个重要的实践是将耗时的、通用的准备动作放在before或beforeEach中但要保持每个测试的独立性。这意味着如果测试B依赖于测试A创建的状态那就是一个糟糕的设计。每个it都应该能从beforeEach设定的初始状态开始执行。对于登录这种几乎所有测试都需要的前置条件你有几个选择在每个测试的beforeEach中登录最干净但可能慢因为每次都要走完整的UI登录流程。通过API快速登录loginByApi在beforeEach中调用速度快但跳过了UI流程适合不关心登录UI的测试。使用cy.session()Cypress 8.2这是官方推荐的终极方案。它可以将登录后的浏览器会话cookies, localStorage等缓存起来在同一个测试文件的不同测试间复用无需重复登录同时保证了测试的隔离性。// 在 support/e2e.ts 或测试文件中 beforeEach(() { // cy.session() 会缓存会话首次执行登录后续复用 cy.session(admin-user, () { cy.loginByApi(Cypress.env(adminUser), Cypress.env(adminPassword)) }) // 会话恢复后访问需要登录的页面 cy.visit(/dashboard) })关于执行策略在本地开发时你可能使用cypress open打开交互式运行器方便调试单个测试文件。但在CI/CD中使用cypress run以无头模式运行。使用--spec参数可以指定运行某个或某些测试文件--headed可以在无头模式下仍看到浏览器便于调试CI上的失败。利用--group和--tag可以对测试进行分组和标签化运行这在大型项目中非常有用。5. 调试、问题排查与持续集成实践5.1 高效的调试方法与日志记录即使测试写得再好失败也在所难免。高效的调试能力至关重要。Cypress Test Runner自带的时光机Time Travel和实时DOM快照是首要工具。测试失败时点击命令日志中的每一步都能看到当时的应用状态。善用cy.pause()和cy.debug()在怀疑的代码行前插入cy.pause()测试运行到此处会暂停你可以打开浏览器开发者工具检查元素、网络请求和console。cy.debug()则会暂停并输出上一个命令产生的主体subject到console对于检查链式调用中间结果非常有用。cy.get(table tr) // 获取所有行 .debug() // 暂停在console里打印出这个jQuery对象 .should(have.length, 5)利用cy.log()添加自定义日志在复杂的测试流程中添加一些上下文日志能帮你快速定位问题阶段。cy.log(开始创建订单流程) // ... 一些操作 cy.log(订单创建成功开始支付) // ... 更多操作网络请求调试cy.intercept()不仅可以用于等待更是强大的调试工具。你可以用它来记录请求和响应的详细信息甚至修改它们。cy.intercept(POST, /api/order, (req) { // 记录请求体 cy.log(Order API Request: ${JSON.stringify(req.body)}) // 可以在这里修改请求或响应 // req.reply({ ... }) // 例如模拟一个错误响应 req.continue() // 让请求继续 })5.2 常见问题排查速查表以下是一些我经常遇到的Cypress问题及其排查思路整理成了表格问题现象可能原因排查步骤与解决方案cy.get(...)超时找不到元素1. 元素尚未加载异步。2. 选择器写错了。3. 元素在iframe或shadow DOM内。4. 页面跳转或重定向导致上下文丢失。1. 使用.should(‘be.visible’)或.should(‘exist’)增加断言等待。2. 在Cypress运行器的实时快照中使用选择器工具验证。3. 对于iframe使用cy.frameLoaded()和cy.iframe()。对于shadow DOM使用.shadow()命令需插件或Cypress 13.6.0。4. 确保在cy.visit()或导致跳转的操作后后续命令作用于新页面。测试在CI上失败本地却通过1. CI环境与本地环境差异数据、配置、网络。2. CI机器性能差异步操作超时。3. 测试依赖未清理的脏数据。1. 检查CI环境变量baseUrl, 账户密码是否正确。在CI日志中打印关键环境信息。2. 适当增加默认命令超时defaultCommandTimeout在配置中或使用Cypress.config()。使用cy.intercept()等待特定请求而非固定等待。3. 强化测试的beforeEach和afterEach钩子确保测试独立性。cy.request()跨域错误请求的域名与测试打开的页面baseUrl不同源。1. 确保cy.request()的url是绝对路径或配置了baseUrl。2. 如果确实是调用第三方API可能需要服务器配置CORS或者在cypress.config.ts中设置chromeWebSecurity: false不推荐有安全限制。TypeScript 编译错误或类型提示丢失1.tsconfig.json配置不正确。2. 自定义命令缺少类型声明。3. 依赖的TypeScript版本与Cypress类型不兼容。1. 确认tsconfig.json中types包含cypressinclude包含测试文件路径。2. 确保在cypress/support/index.d.ts中为所有自定义命令添加了类型声明。3. 检查package.json中typescript和types/node的版本保持与Cypress官方推荐的一致。测试运行速度慢1. 使用了大量的cy.wait(毫秒数)。2. 每个测试都进行完整的UI登录。3. 操作了真实的外部依赖如支付网关。1. 用cy.intercept()cy.wait(‘alias’)替代固定等待。2. 使用cy.session()缓存登录状态或对非登录相关测试使用API登录。3. 使用cy.intercept()拦截并模拟外部API的响应避免真实网络调用。5.3 集成到CI/CD流水线将自动化测试集成到CI/CD中是实现其价值的关键。核心目标是快速反馈、稳定可靠。我以GitHub Actions为例展示一个基础的配置# .github/workflows/cypress-tests.yml name: E2E Tests on: [push, pull_request] jobs: cypress-run: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 cache: npm - name: Install dependencies run: npm ci # 使用ci命令确保依赖锁一致 - name: Run Cypress tests uses: cypress-io/github-actionv5 with: build: npm run build # 如果你的测试需要先构建应用 start: npm start # 启动本地开发服务器 wait-on: http://localhost:3000 # 等待服务器就绪 config-file: cypress.config.ts # 可以指定浏览器默认是Electron browser: chrome # 分组并行运行测试如果测试多 group: UI Tests # 记录测试结果到Dashboard如果需要 record: true parallel: false env: # 注入测试环境变量 CYPRESS_BASE_URL: http://localhost:3000 CYPRESS_API_URL: ${{ secrets.TEST_API_URL }} CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Upload artifacts (on failure) if: failure() uses: actions/upload-artifactv3 with: name: cypress-screenshots path: cypress/screenshots # 还可以上传videos和reports关键实践使用缓存缓存node_modules和Cypress二进制包能极大加速CI流程。失败时保留现场配置在测试失败时自动上传截图、视频和日志文件作为制品这是远程调试的救命稻草。环境隔离使用CI的Secrets功能管理敏感信息如密码、API密钥绝不硬编码在配置文件中。考虑并行化如果测试套件很大可以利用Cypress Cloud或第三方工具将测试分片到多台机器并行运行缩短反馈时间。设置质量门禁在PR流程中可以将E2E测试通过作为合并的前置条件。但要注意对于可能不稳定的测试可以设置允许重试或只作为非阻塞的检查。最后关于“自动化测试占比一般是多少”这个热词问题我想说没有一个黄金数字。它取决于产品类型、迭代速度、团队成熟度和测试金字塔的构建情况。UI自动化测试E2E应该是金字塔的塔尖数量最少但覆盖最关键的用户旅程。更多的测试应该是单元测试和集成测试。一个常见的反模式是试图用脆弱的UI自动化覆盖所有场景结果导致维护成本高昂。我的经验是优先保证核心业务流程如注册、登录、下单、支付的E2E自动化稳定可靠其价值远高于追求高覆盖率。让自动化测试成为安全网而不是负担。
TypeScript + Cypress 自动化测试实战：14个技巧打造稳定可维护的测试套件
发布时间：2026/7/25 10:23:39
1. 项目概述从“能用”到“好用”的自动化测试进阶之路最近在团队里做了一次关于测试自动化的内部分享主题就是如何让我们的Cypress测试套件从“能跑起来”变得“既稳又好维护”。我发现很多刚开始接触Cypress和TypeScript的同事写出来的测试代码虽然功能上没问题但读起来费劲维护起来头疼稳定性也时好时坏。这其实挺常见的自动化测试的初期目标往往是“把流程跑通”但要想让它真正成为研发流程中可靠的一环成为提升效率而非制造麻烦的工具就需要一些经过实战检验的实践来保驾护航。这次我结合自己踩过的坑和团队的最佳实践梳理了14个在TypeScript Cypress环境下简单又实用的技巧。这些实践覆盖了从项目配置、代码结构到测试编写、调试维护的全链路。它们不是什么高深的理论而是你明天就能在项目里用起来的“脚手架”和“工具箱”。无论你是刚入门想写出更规范的测试还是已经有一定经验希望提升测试套件的健壮性和可读性我相信这里面总有一些点能给你带来启发。我们的目标很明确让自动化测试脚本像产品代码一样清晰、可靠、易于协作。2. 环境搭建与配置优化为高效测试奠定基石2.1 TypeScript与Cypress的初始配置要点万事开头难一个合理的初始配置能避免后续无数麻烦。首先确保你的Node.js版本是LTS版本如18.x或20.x这能保证依赖兼容性。使用npm init -y初始化项目后安装核心依赖npm install cypress typescript --save-dev npm install types/node cypress/webpack-preprocessor --save-dev # 用于TypeScript编译接下来是关键的tsconfig.json配置。很多教程给的配置比较基础但在测试项目中我们需要特别关注几个点。首先将target设置为es2017或更高因为Cypress运行在较新的Chrome环境中可以利用现代JavaScript特性。其次module设置为commonjs这是Node.js环境的标准。最重要的是types字段一定要包含cypress和node这样你才能在代码中获得完整的类型提示。{ compilerOptions: { target: es2017, module: commonjs, lib: [es2017, dom], types: [cypress, node], strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, outDir: ./dist, rootDir: ./ }, include: [**/*.ts], exclude: [node_modules, dist] }注意网络热词中提到的“选项‘baseUrl’已弃用”等问题通常出现在更复杂的、将Cypress集成到现有Angular/React项目TypeScript配置中的场景。对于独立的Cypress测试项目使用上述独立的tsconfig.json并明确指定types: [“cypress”]可以完美规避这些兼容性警告无需担心TypeScript 7.0的破坏性变更。然后是cypress.config.ts或.js文件。这里我强烈建议使用TypeScript格式的配置文件以获得类型安全。一个基础的配置如下import { defineConfig } from cypress export default defineConfig({ e2e: { baseUrl: https://your-app.com, // 你的应用基础地址 specPattern: cypress/e2e/**/*.spec.ts, // 测试文件匹配模式 supportFile: cypress/support/e2e.ts, // 支持文件 viewportWidth: 1280, viewportHeight: 720, setupNodeEvents(on, config) { // 可以在这里配置插件 }, }, })这里有个小技巧baseUrl的设置至关重要。它不仅是测试的起点更重要的是Cypress的命令如cy.visit(‘/login’)会自动拼接这个baseUrl让你的测试代码更简洁且易于在不同环境开发、测试、预发布间切换只需修改配置即可。2.2 目录结构设计与支持文件规划清晰的目录结构是团队协作和维护性的基础。我推荐以下结构它分离了关注点cypress/ ├── e2e/ # 所有测试用例文件 (.spec.ts) │ ├── login/ # 按功能模块组织 │ ├── dashboard/ │ └── api/ ├── fixtures/ # 静态测试数据文件 (.json) │ └── test-users.json ├── support/ # 支持文件 │ ├── commands.ts # 自定义命令 │ ├── e2e.ts # 测试运行前加载的文件 │ └── index.d.ts # TypeScript类型定义扩展 ├── downloads/ # 测试运行时下载的文件 ├── screenshots/ # 失败时的截图 ├── videos/ # 测试录像 └── plugins/ # 插件配置 (Cypress 10 或 需要插件时)重点说一下support文件夹。e2e.ts是每个测试文件运行前都会执行的文件这里是放置全局配置的绝佳位置比如忽略掉一些无关紧要的XHR错误、或者设置全局的请求超时。而commands.ts则是你施展“魔法”的地方可以将重复的操作如登录、数据准备封装成自定义命令。index.d.ts文件用于为这些自定义命令添加TypeScript类型提示这是保证开发体验的关键一步。例如在commands.ts中你添加了一个自定义登录命令// cypress/support/commands.ts Cypress.Commands.add(loginByApi, (username: string, password: string) { cy.request(POST, /api/login, { username, password }).then((response) { window.localStorage.setItem(authToken, response.body.token) }) })那么你必须在index.d.ts中声明它的类型否则TypeScript会报错也无法获得代码补全// cypress/support/index.d.ts declare namespace Cypress { interface Chainable { /** * 通过API直接登录跳过UI * example cy.loginByApi(admin, password123) */ loginByApi(username: string, password: string): Chainablevoid } }这个简单的步骤能让你的团队在使用自定义命令时获得和原生Cypress命令一样的智能提示和类型检查极大提升开发效率和代码质量。3. 测试代码编写核心实践编写健壮、可读的测试用例3.1 选择器策略与页面对象模型POM的平衡元素选择器是UI自动化测试的基石糟糕的选择器是测试脆弱的首要原因。Cypress官方推荐使用>!-- 前端代码 -- button>// 测试代码 - 非常稳定 cy.get([data-testidsubmit-login-btn]).click()然而为每个元素都添加>// cypress/support/pages/LoginPage.ts export const LoginPage { selectors: { usernameInput: [data-testidusername], passwordInput: [data-testidpassword], submitButton: [data-testidsubmit-login-btn], errorMessage: .error-text } } // 在测试文件中使用 import { LoginPage } from ../support/pages/LoginPage cy.get(LoginPage.selectors.usernameInput).type(testuser) cy.get(LoginPage.selectors.passwordInput).type(pass123) cy.get(LoginPage.selectors.submitButton).click()这种方式平衡了可维护性和Cypress的原生风格。当元素选择器需要变更时你只需在一个地方修改。3.2 测试数据管理与Fixture的智能使用测试数据管理是另一个核心。硬编码在测试用例中的数据是“坏味道”。Cypress的fixtures文件夹用于存放静态的JSON数据文件非常适合用于 mock API响应或存储固定的测试账户信息。// cypress/fixtures/users.json { admin: { username: adminexample.com, password: Admin123!, role: administrator }, standardUser: { username: userexample.com, password: User123!, role: user } }在测试中加载和使用它beforeEach(() { cy.fixture(users).as(usersData) // 加载并起别名 }) it(使用fixture数据登录, function() { // 注意使用function以访问this const user this.usersData.standardUser cy.get([data-testidusername]).type(user.username) cy.get([data-testidpassword]).type(user.password) // ... 后续操作 })但fixtures是静态的对于需要动态生成或清理的数据如测试创建的订单、文章更好的方式是结合API。我常用的模式是在beforeEach或测试开始前通过API调用cy.request在后台创建测试所需的数据并获取其ID等引用信息在afterEach或测试结束后再通过API清理这些数据。这保证了测试的独立性和可重复性。describe(订单流程测试, () { let testOrderId: string beforeEach(() { // 通过API创建测试订单 cy.request(POST, /api/test/orders, { productId: 123 }).then((resp) { testOrderId resp.body.id // 将订单ID存入环境变量或挂载到window供前端应用访问如果需要 cy.window().then(win { (win as any).__TEST_ORDER_ID testOrderId }) }) }) afterEach(() { // 测试后清理订单 if (testOrderId) { cy.request(DELETE, /api/test/orders/${testOrderId}) } }) it(可以查看订单详情, () { // 访问包含该订单的页面 cy.visit(/orders/${testOrderId}) // ... 进行断言 }) })3.3 断言的艺术与异步操作处理Cypress的断言基于Chai库并且自动处理了异步等待这是它的一大优势。但写出好的断言依然需要技巧。首先断言应该具有表达力描述你期望的“状态”而非“过程”。例如与其断言“点击后按钮应该禁用”不如断言“提交后按钮处于禁用状态”。其次充分利用Cypress提供的丰富断言。除了常见的.should(‘be.visible’)、.should(‘have.text’, ‘xxx’)还有一些非常实用的.should(‘have.class’, ‘loading’) 断言元素具有某个CSS类。.should(‘be.disabled’) 断言表单元素被禁用。.should(‘have.value’, ‘input text’) 断言输入框的值。.should(($el) { expect($el).to.have.length(3) }) 使用回调函数进行更复杂的断言。对于异步操作比如等待一个API调用完成后再进行UI断言Cypress的cy.intercept()和cy.wait()是黄金组合。但要注意cy.wait()是等待一个特定的、被cy.intercept()命中的请求而不是傻等固定时间。it(搜索后显示结果, () { // 拦截搜索API请求并给它起个别名‘searchRequest’ cy.intercept(GET, /api/search?q*).as(searchRequest) cy.get([data-testidsearch-input]).type(Cypress{enter}) // 等待特定的请求完成 cy.wait(searchRequest).its(response.statusCode).should(eq, 200) // 然后断言UI更新 cy.get([data-testidresult-list] li).should(have.length.at.least, 1) })这个模式清晰地表达了“触发动作 - 等待网络请求完成 - 验证结果”的流程比使用cy.wait(5000)这种硬等待可靠得多。4. 提升可维护性与执行效率的进阶技巧4.1 自定义命令与可复用逻辑封装当你在多个测试文件中重复相同的操作序列时就是抽象成自定义命令或工具函数的时候了。自定义命令的优势在于它直接挂载在cy对象下使用起来和原生命令无异非常适合封装与UI强相关的流程。例如一个包含UI操作和API等待的完整登录流程// cypress/support/commands.ts Cypress.Commands.add(loginViaUI, (username: string, password: string) { // 拦截登录API以便等待 cy.intercept(POST, /api/auth/login).as(loginApi) cy.visit(/login) cy.get([data-testidusername]).type(username) cy.get([data-testidpassword]).type(password) cy.get([data-testidsubmit-login-btn]).click() // 等待登录成功 cy.wait(loginApi).then((interception) { expect(interception.response?.statusCode).to.be.oneOf([200, 201]) }) // 断言登录成功后的页面跳转或状态 cy.url().should(include, /dashboard) cy.contains(欢迎回来).should(be.visible) })而对于纯数据准备或工具类函数我更倾向于将其写成普通的TypeScript函数放在一个如cypress/support/utils.ts的文件中导出。这样逻辑更清晰也便于单元测试如果需要。// cypress/support/utils.ts /** * 生成一个随机的测试邮箱 * param prefix 邮箱前缀默认为‘test’ */ export function generateTestEmail(prefix: string test): string { const timestamp new Date().getTime() const random Math.floor(Math.random() * 10000) return ${prefix}${timestamp}${random}example.com } /** * 通过API快速创建一个测试用户并返回凭证 */ export function createTestUserViaApi(userData?: PartialUser): Promise{username: string, password: string} { // 使用cy.request但注意这在support文件非命令中需谨慎最好在测试上下文中调用 return cy.request(POST, /api/test/users, { username: generateTestEmail(), password: TempPass123!, ...userData }).then(resp resp.body) }在测试中使用时直接导入函数即可。这种分离使得“命令”专注于浏览器交互“工具函数”专注于数据和业务逻辑。4.2 配置管理与多环境适配一个专业的测试套件必须能轻松运行在不同环境。Cypress通过环境变量CYPRESS_*或cypress.config.ts中的env对象和配置文件来管理。我推荐使用cypress.config.ts配合dotenv来管理多环境配置。首先安装dotenvnpm install dotenv --save-dev。然后在项目根目录创建不同环境的.env文件如.env.staging、.env.production。在cypress.config.ts中动态加载// cypress.config.ts import { defineConfig } from cypress import * as dotenv from dotenv // 根据CYPRESS_ENV环境变量决定加载哪个配置文件默认为development const envFile .env.${process.env.CYPRESS_ENV || development} dotenv.config({ path: envFile }) export default defineConfig({ e2e: { baseUrl: process.env.CYPRESS_BASE_URL || http://localhost:3000, env: { // 将.env文件中的变量注入到Cypress环境变量中 apiUrl: process.env.CYPRESS_API_URL, adminUser: process.env.CYPRESS_ADMIN_USER, adminPassword: process.env.CYPRESS_ADMIN_PASSWORD, // 也可以定义一些逻辑变量 isProduction: process.env.CYPRESS_ENV production }, // ... 其他配置 }, })在测试中你可以通过Cypress.env(‘apiUrl’)来访问这些变量。这样在CI/CD流水线中只需设置CYPRESS_ENVstaging就能自动指向预发布环境进行测试。4.3 测试分组、钩子与执行策略合理的测试组织能提升运行效率和日志可读性。describe和context用于创建测试套件分组it指定单个测试用例。before、beforeEach、afterEach、after这些钩子函数用于设置和清理。一个重要的实践是将耗时的、通用的准备动作放在before或beforeEach中但要保持每个测试的独立性。这意味着如果测试B依赖于测试A创建的状态那就是一个糟糕的设计。每个it都应该能从beforeEach设定的初始状态开始执行。对于登录这种几乎所有测试都需要的前置条件你有几个选择在每个测试的beforeEach中登录最干净但可能慢因为每次都要走完整的UI登录流程。通过API快速登录loginByApi在beforeEach中调用速度快但跳过了UI流程适合不关心登录UI的测试。使用cy.session()Cypress 8.2这是官方推荐的终极方案。它可以将登录后的浏览器会话cookies, localStorage等缓存起来在同一个测试文件的不同测试间复用无需重复登录同时保证了测试的隔离性。// 在 support/e2e.ts 或测试文件中 beforeEach(() { // cy.session() 会缓存会话首次执行登录后续复用 cy.session(admin-user, () { cy.loginByApi(Cypress.env(adminUser), Cypress.env(adminPassword)) }) // 会话恢复后访问需要登录的页面 cy.visit(/dashboard) })关于执行策略在本地开发时你可能使用cypress open打开交互式运行器方便调试单个测试文件。但在CI/CD中使用cypress run以无头模式运行。使用--spec参数可以指定运行某个或某些测试文件--headed可以在无头模式下仍看到浏览器便于调试CI上的失败。利用--group和--tag可以对测试进行分组和标签化运行这在大型项目中非常有用。5. 调试、问题排查与持续集成实践5.1 高效的调试方法与日志记录即使测试写得再好失败也在所难免。高效的调试能力至关重要。Cypress Test Runner自带的时光机Time Travel和实时DOM快照是首要工具。测试失败时点击命令日志中的每一步都能看到当时的应用状态。善用cy.pause()和cy.debug()在怀疑的代码行前插入cy.pause()测试运行到此处会暂停你可以打开浏览器开发者工具检查元素、网络请求和console。cy.debug()则会暂停并输出上一个命令产生的主体subject到console对于检查链式调用中间结果非常有用。cy.get(table tr) // 获取所有行 .debug() // 暂停在console里打印出这个jQuery对象 .should(have.length, 5)利用cy.log()添加自定义日志在复杂的测试流程中添加一些上下文日志能帮你快速定位问题阶段。cy.log(开始创建订单流程) // ... 一些操作 cy.log(订单创建成功开始支付) // ... 更多操作网络请求调试cy.intercept()不仅可以用于等待更是强大的调试工具。你可以用它来记录请求和响应的详细信息甚至修改它们。cy.intercept(POST, /api/order, (req) { // 记录请求体 cy.log(Order API Request: ${JSON.stringify(req.body)}) // 可以在这里修改请求或响应 // req.reply({ ... }) // 例如模拟一个错误响应 req.continue() // 让请求继续 })5.2 常见问题排查速查表以下是一些我经常遇到的Cypress问题及其排查思路整理成了表格问题现象可能原因排查步骤与解决方案cy.get(...)超时找不到元素1. 元素尚未加载异步。2. 选择器写错了。3. 元素在iframe或shadow DOM内。4. 页面跳转或重定向导致上下文丢失。1. 使用.should(‘be.visible’)或.should(‘exist’)增加断言等待。2. 在Cypress运行器的实时快照中使用选择器工具验证。3. 对于iframe使用cy.frameLoaded()和cy.iframe()。对于shadow DOM使用.shadow()命令需插件或Cypress 13.6.0。4. 确保在cy.visit()或导致跳转的操作后后续命令作用于新页面。测试在CI上失败本地却通过1. CI环境与本地环境差异数据、配置、网络。2. CI机器性能差异步操作超时。3. 测试依赖未清理的脏数据。1. 检查CI环境变量baseUrl, 账户密码是否正确。在CI日志中打印关键环境信息。2. 适当增加默认命令超时defaultCommandTimeout在配置中或使用Cypress.config()。使用cy.intercept()等待特定请求而非固定等待。3. 强化测试的beforeEach和afterEach钩子确保测试独立性。cy.request()跨域错误请求的域名与测试打开的页面baseUrl不同源。1. 确保cy.request()的url是绝对路径或配置了baseUrl。2. 如果确实是调用第三方API可能需要服务器配置CORS或者在cypress.config.ts中设置chromeWebSecurity: false不推荐有安全限制。TypeScript 编译错误或类型提示丢失1.tsconfig.json配置不正确。2. 自定义命令缺少类型声明。3. 依赖的TypeScript版本与Cypress类型不兼容。1. 确认tsconfig.json中types包含cypressinclude包含测试文件路径。2. 确保在cypress/support/index.d.ts中为所有自定义命令添加了类型声明。3. 检查package.json中typescript和types/node的版本保持与Cypress官方推荐的一致。测试运行速度慢1. 使用了大量的cy.wait(毫秒数)。2. 每个测试都进行完整的UI登录。3. 操作了真实的外部依赖如支付网关。1. 用cy.intercept()cy.wait(‘alias’)替代固定等待。2. 使用cy.session()缓存登录状态或对非登录相关测试使用API登录。3. 使用cy.intercept()拦截并模拟外部API的响应避免真实网络调用。5.3 集成到CI/CD流水线将自动化测试集成到CI/CD中是实现其价值的关键。核心目标是快速反馈、稳定可靠。我以GitHub Actions为例展示一个基础的配置# .github/workflows/cypress-tests.yml name: E2E Tests on: [push, pull_request] jobs: cypress-run: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 cache: npm - name: Install dependencies run: npm ci # 使用ci命令确保依赖锁一致 - name: Run Cypress tests uses: cypress-io/github-actionv5 with: build: npm run build # 如果你的测试需要先构建应用 start: npm start # 启动本地开发服务器 wait-on: http://localhost:3000 # 等待服务器就绪 config-file: cypress.config.ts # 可以指定浏览器默认是Electron browser: chrome # 分组并行运行测试如果测试多 group: UI Tests # 记录测试结果到Dashboard如果需要 record: true parallel: false env: # 注入测试环境变量 CYPRESS_BASE_URL: http://localhost:3000 CYPRESS_API_URL: ${{ secrets.TEST_API_URL }} CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Upload artifacts (on failure) if: failure() uses: actions/upload-artifactv3 with: name: cypress-screenshots path: cypress/screenshots # 还可以上传videos和reports关键实践使用缓存缓存node_modules和Cypress二进制包能极大加速CI流程。失败时保留现场配置在测试失败时自动上传截图、视频和日志文件作为制品这是远程调试的救命稻草。环境隔离使用CI的Secrets功能管理敏感信息如密码、API密钥绝不硬编码在配置文件中。考虑并行化如果测试套件很大可以利用Cypress Cloud或第三方工具将测试分片到多台机器并行运行缩短反馈时间。设置质量门禁在PR流程中可以将E2E测试通过作为合并的前置条件。但要注意对于可能不稳定的测试可以设置允许重试或只作为非阻塞的检查。最后关于“自动化测试占比一般是多少”这个热词问题我想说没有一个黄金数字。它取决于产品类型、迭代速度、团队成熟度和测试金字塔的构建情况。UI自动化测试E2E应该是金字塔的塔尖数量最少但覆盖最关键的用户旅程。更多的测试应该是单元测试和集成测试。一个常见的反模式是试图用脆弱的UI自动化覆盖所有场景结果导致维护成本高昂。我的经验是优先保证核心业务流程如注册、登录、下单、支付的E2E自动化稳定可靠其价值远高于追求高覆盖率。让自动化测试成为安全网而不是负担。
