Cypress：详解架构原理与环境设置指南

原创于 2025-12-16 08:11:53 发布 · 414 阅读

4 ·

CC 4.0 BY-SA版权

文章标签：

#架构 #智能体 #前端 #自动化

人工智能同时被 2 个专栏收录

18 篇文章

订阅专栏

自动化测试

9 篇文章

订阅专栏

前端测试的世界变化很快，从 Selenium 时代一路走到如今的现代化测试框架，Cypress 无疑是站在浪潮之巅的那一位。它以“开发者体验优先”的理念迅速成为 Web 自动化测试的主流选择。

但很多同学用过 Cypress 写用例，却没有真正理解它的架构与运行机制，也不清楚环境应该如何正确配置。本文就来系统讲清楚：Cypress 到底是怎么工作的？以及如何搭建一套可用于真实项目的 Cypress 环境？

一、Cypress 的整体架构：为什么它这么快？

Cypress 的核心创新在于：它并不是像 Selenium 那样通过 WebDriver 间接驱动浏览器，而是把自己嵌入到浏览器内部运行，让测试脚本与被测页面共享同一个运行环境。

从三个角度理解它的架构机制更清晰。

1. 浏览器内部运行

Cypress 的测试代码直接跑在浏览器里，可直接操作并访问：

DOM 元素（无需额外等待）
window、document 等浏览器对象
XHR / Fetch 网络请求
cookie、本地存储等数据

没有 WebDriver 的跨进程通信，自然也就更快、更稳定。

2. Node 进程提供额外能力

浏览器能干的事情不多，Cypress 会再起一个 Node 服务来处理系统级任务，例如：

文件读写（如下载、上传模拟）
截图与录屏
定制任务（task）
调用后端 API

你可以把它理解成“双引擎”：浏览器做页面操作，Node 做系统操作。

3. 内置命令队列调度

像 cy.get()、cy.click() 并不是立即执行，而是进入 Cypress 内部的“命令队列”，按顺序执行并自动等待。

这意味着 Cypress 天生就有“智能等待”的能力，大量减少 sleep、wait，也让测试更加稳定。

二、Cypress 环境设置：如何搭建一套完整项目？

以下步骤适用于大多数前端项目、测试项目，以及 CI 流水线环境。

1. 安装 Cypress

在项目根目录执行：

npm install cypress --save-dev

安装后：

npx cypress open

首次运行会生成默认目录结构：

cypress/
  e2e/       
  fixtures/  
  support/   
cypress.config.js

2. 配置文件（核心设置）

所有核心配置都在根目录的：

cypress.config.js

常见配置如下：

const { defineConfig } = require("cypress");

module.exports = defineConfig({
  e2e: {
    baseUrl: "https://test.example.com",
    viewportWidth: 1280,
    viewportHeight: 800,
    video: true,
    screenshotOnRunFailure: true,
    pageLoadTimeout: 60000,
    retries: 2,
  },
});

这些参数基本是前端自动化的“必配项”，能确保用例稳定执行。

3. support（全局逻辑）

cypress/support/e2e.js 常用于放置：

全局 before/after
网络拦截
公共逻辑封装
自定义命令

例如封装登录：

Cypress.Commands.add("login", (user, pass) => {
  cy.request("POST", "/login", { user, pass });
});

用例中只要：

cy.login("tom", "123456");

即可完成前置逻辑。

4. Fixtures（模拟数据）

适合在后端接口不稳定，或需要 Mock 返回的场景中使用。

比如：

{
  "user": { "id": 1, "name": "Tom Tester" }
}

使用时：

cy.fixture("user.json").then(user => {
  cy.log(user.name);
});

5. 编写第一个 Cypress 用例

在 cypress/e2e/login.cy.js 中：

describe("用户登录流程", () => {
  it("正确用户名密码可登录", () => {
    cy.visit("/");
    cy.get("#username").type("tom");
    cy.get("#password").type("123456");
    cy.get("#login-btn").click();
    cy.contains("欢迎回来").should("be.visible");
  });
});

启动 Test Runner 后即可看到可视化执行过程。