在 Next.js 中配置 Cypress

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

警告：

对于 组件测试，Cypress 目前不支持 Next.js 14 版本和 async 服务端组件。这些问题正在跟踪中。目前，组件测试可与 Next.js 13 版本配合使用，我们建议对 async 服务端组件使用 E2E 测试。

Cypress 目前不支持 TypeScript 5 版本的 moduleResolution:"bundler"。该问题正在跟踪中。

快速开始

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

终端

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

手动设置

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

终端

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 以打开测试套件：

终端

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>Home</h1>
      <Link href="/about">About</Link>
    </div>
  )
}

app/about/page.js

import Link from 'next/link'

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

添加一个测试以检查导航是否正确工作：

cypress/e2e/app.cy.js

describe('Navigation', () => {
  it('should navigate to the about page', () => {
    // 从首页开始
    cy.visit('http://localhost:3000/')

    // 找到包含 "about" 的链接并点击
    cy.get('a[href*="about"]').click()

    // 新 URL 应包含 "/about"
    cy.url().should('include', '/about')

    // 新页面应包含 "About" 标题
    cy.get('h1').contains('About')
  })
})

运行 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 包以结合 Next.js 生产服务器运行 Cypress。安装后，在 package.json 的 scripts 字段中添加 "test": "start-server-and-test start http://localhost:3000 cypress"。请记得在更改后重新构建应用。

创建第一个 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('should render and display expected content', () => {
    // 挂载首页的 React 组件
    cy.mount(<Page />)

    // 页面应包含 "Home" 标题
    cy.get('h1').contains('Home')

    // 验证包含预期 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 环境：