Skip to main content

Cypress

Cypress是用于端到端 (E2E) 测试和组件测试的测试工具。本页面将向你展示如何在 Next.js 中设置 Cypress 并编写你的第一个测试。

警告:

  • 对于 组件测试, Cypress 目前不支持Next.js 版本 14 和 async服务端组件。这些问题正在跟踪中。目前，组件测试适用于 Next.js 版本 13，我们建议对async服务端组件使用 E2E 测试。
  • 低于 Cypress 13.6.3 的版本不支持TypeScript 版本 5 和 moduleResolution:"bundler"。不过，此问题已在 Cypress 13.6.3 及以后版本中修复。cypress v13.6.3

快速开始​

您可以使用create-next-app和with-cypress 示例 快速开始。

npx create-next-app@latest --example with-cypress with-cypress-app

手动设置​

要手动设置 Cypress, 请安装cypress开发依赖：

npm install -D cypress
# or
yarn add -D cypress
# or
pnpm install -D cypress

将 Cypressopen命令添加到package.json文件 scripts 字段：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "cypress:open": "cypress open"
  }
}

首次运行 Cypress 以打开 Cypress 测试套件：

npm run cypress:open

你可以选择配置E2E 测试 和/或 组件测试。选择任一选项将自动在项目中创建cypress.config.js文件和cypress文件夹。

创建你的第一个 Cypress E2E 测试

确保你的cypress.config.js文件具有以下配置：

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {},
  },
});
const { defineConfig } = require("cypress");

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {},
  },
});

然后，创建两个新的 Next.js 文件：

import Link from "next/link";

export default function Page() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  );
}
import Link from "next/link";

export default function Page() {
  return (
    <div>
      <h1>About</h1>
      <Link href="/">Home</Link>
    </div>
  );
}

添加测试以检查导航是否正常运行：

describe("Navigation", () => {
  it("should navigate to the about page", () => {
    // Start from the index page
    cy.visit("http://localhost:3000/");

    // Find a link with an href attribute containing "about" and click it
    cy.get('a[href*="about"]').click();

    // The new url should include "/about"
    cy.url().should("include", "/about");

    // The new page should contain an h1 with "About"
    cy.get("h1").contains("About");
  });
});

运行 E2E 测试​

Cypress 将模拟用户浏览你的应用程序，这需要你的 Next.js 服务器正在运行。我们建议针对生产代码运行测试，以更接近真实应用的行为。

运行 npm run build && npm run start构建你的 Next.js 应用程序，然后在另一个终端窗口中运行npm run cypress:open启动 Cypress 并运行 E2E 测试套件。

您需要知道:

  • 通过将baseUrl: 'http://localhost:3000'添加到cypress.config.js配置文件中，您可以使用cy.visit("/")而不是cy.visit("http://localhost:3000/") 。
  • 或者，你可以安装start-server-and-test包以在运行 Cypress 时同时运行 Next.js 生产服务器。安装后，将"test": "start-server-and-test start http://localhost:3000 cypress"添加到package.json脚本字段。记得在有新更改后重新构建应用程序。

创建你的第一个 Cypress 组件测试​

组件测试可以构建并挂载特定组件，而无需打包整个应用程序或启动服务器。

在 Cypress 应用中选择** 组件测试**，然后选择Next.js作为您的前端框架。项目中将创建cypress/component文件夹, 并更新 cypress.config.js文件已开启组件测试。

确保cypress.config.js文件有如下配置：

import { defineConfig } from "cypress";

export default defineConfig({
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
  },
});
const { defineConfig } = require("cypress");

module.exports = defineConfig({
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
  },
});

假设与上一节相同的组件，添加测试以验证组件是否渲染了预期的输出：

import Page from "../../app/page";

describe("<Page />", () => {
  it("should render and display expected content", () => {
    // Mount the React component for the Home page
    cy.mount(<Page />);

    // The new page should contain an h1 with "Home"
    cy.get("h1").contains("Home");

    // Validate that a link with the expected URL is present
    // Following the link is better suited to an E2E test
    cy.get('a[href="/about"]').should("be.visible");
  });
});

您需要知道:

  • Cypress 目前不支持async服务端组件的组件测试。我们建议使用 E2E 测试。
  • 由于组件测试不需要 Next.js 服务器，因此依赖于可用的服务器的的功能（如<img />）可能无法直接使用。

运行组件测试​

在终端中运行npm run cypress:open启动 Cypress 并运行组件测试套件。

持续集成(CI)​

除了交互式测试，你还可以使用cypress run 命令在无头模式下运行 Cypress，这种模式更适合 CI 环境：

{
  "scripts": {
    //...
    "e2e": "start-server-and-test dev http://localhost:3000 \"cypress open --e2e\"",
    "e2e:headless": "start-server-and-test dev http://localhost:3000 \"cypress run --e2e\"",
    "component": "cypress open --component",
    "component:headless": "cypress run --component"
  }
}

你可以通过以下资源了解更多关于 Cypress 和持续集成的信息：