Menu

在 Next.js 中设置 Cypress

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

警告：

  • 对于 组件测试，Cypress 目前不支持 Next.js 14 版本 和 async 服务器组件。这些问题正在被跟踪。目前，组件测试适用于 Next.js 13 版本，我们建议对 async 服务器组件使用 E2E 测试。
  • Cypress 13.6.3 版本以下不支持使用 moduleResolution:"bundler" 的 TypeScript 5 版本。但是，这个问题在 Cypress 13.6.3 及更高版本中已经解决。cypress v13.6.3

快速开始

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

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

手动设置

要手动设置 Cypress，请将 cypress 安装为开发依赖：

Terminal
npm install -D cypress
# 或
yarn add -D cypress
# 或
pnpm install -D cypress

将 Cypress open 命令添加到 package.json 的 scripts 字段中：

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

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

Terminal
npm run cypress:open

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

创建你的第一个 Cypress E2E 测试

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

cypress.config.ts
import { defineConfig } from "cypress";
 
export default defineConfig({
  e2e: {
    setupNodeEvents (on, config) {},
  },
});
cypress.config.js
const { defineConfig } = require ("cypress");
 
module.exports = defineConfig ({
  e2e: {
    setupNodeEvents (on, config) {},
  },
});

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

app/page.js
import Link from "next/link";
 
export default function Page () {
  return (
    <div>
      <h1>首页</h1>
      <Link href="/about">关于</Link>
    </div>
  );
}
app/about/page.js
import Link from "next/link";
 
export default function Page () {
  return (
    <div>
      <h1>关于</h1>
      <Link href="/">首页</Link>
    </div>
  );
}

添加一个测试来检查你的导航是否正常工作：

cypress/e2e/app.cy.js
describe ("导航", () => {
  it ("应该导航到关于页面", () => {
    // 从索引页面开始
    cy.visit ("http://localhost:3000/");
 
    // 找到包含 "about" 的 href 属性的链接并点击它
    cy.get ('a[href*="about"]').click ();
 
    // 新的 url 应该包含 "/about"
    cy.url ().should ("include", "/about");
 
    // 新页面应该包含一个内容为 "关于" 的 h1
    cy.get ("h1").contains ("关于");
  });
});

运行 E2E 测试

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

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

值得注意的是：

  • 你可以通过在 cypress.config.js 配置文件中添加 baseUrl: 'http://localhost:3000' 来使用 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 的 scripts 字段中。记得在新的更改后重新构建你的应用程序。

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

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

在 Cypress 应用程序中选择 组件测试，然后选择 Next.js 作为你的前端框架。一个 cypress/component 文件夹将在你的项目中创建，并且 cypress.config.js 文件将被更新以启用组件测试。

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

cypress.config.ts
import { defineConfig } from "cypress";
 
export default defineConfig ({
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
  },
});
cypress.config.js
const { defineConfig } = require ("cypress");
 
module.exports = defineConfig ({
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
  },
});

假设使用上一节中的相同组件，添加一个测试来验证组件是否渲染了预期的输出：

cypress/component/about.cy.tsx
import Page from "../../app/page";
 
describe ("<Page />", () => {
  it ("应该渲染并显示预期内容", () => {
    // 挂载首页的 React 组件
    cy.mount (<Page />);
 
    // 新页面应该包含一个内容为 "首页" 的 h1
    cy.get ("h1").contains ("首页");
 
    // 验证具有预期 URL 的链接是否存在
    // 跟随链接更适合 E2E 测试
    cy.get ('a[href="/about"]').should ("be.visible");
  });
});

值得注意的是：

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

运行组件测试

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

持续集成 (CI)

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

package.json
{
  "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 和持续集成的信息：