使用 Next.js 设置 Cypress

Cypress 是一种用于 **端到端 (E2E)** 和 **组件测试** 的测试运行器。此页面将向你展示如何使用 Next.js 设置 Cypress 以及编写你的第一个测试。

警告

对于 **组件测试**，Cypress 目前不支持 Next.js 版本 14 和 `async` 服务器组件。这些问题正在跟踪中。目前，组件测试适用于 Next.js 版本 13，我们建议对 `async` 服务器组件进行端到端测试。

低于 13.6.3 版本的 Cypress 不支持 TypeScript 版本 5 以及 `moduleResolution:"bundler"`。但是，此问题已在 Cypress 13.6.3 及更高版本中得到解决。cypress v13.6.3

手动设置

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

终端

npm install -D cypress
# or
yarn add -D cypress
# or
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 测试套件

终端

npm run cypress:open

你可以选择配置 **端到端测试** 和/或 **组件测试**。选择任何这些选项都将自动在你的项目中创建 `cypress.config.js` 文件和 `cypress` 文件夹。

创建你的第一个 Cypress 端到端测试

确保你的 `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 文件

pages/index.js

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

pages/about.js

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

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

cypress/e2e/app.cy.js

describe('Navigation', () => {
  it('should navigate to the about page', () => {
    // Start from the index page
    cy.visit('https://127.0.0.1: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')
  })
})

运行端到端测试

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

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

值得注意

通过在 cypress.config.js 配置文件中添加 baseUrl: 'https://127.0.0.1:3000'，您可以使用 cy.visit("/") 代替 cy.visit("https://127.0.0.1:3000/")。

或者，您可以安装 start-server-and-test 包，以结合使用 Cypress 运行 Next.js 生产服务器。安装后，将 "test": "start-server-and-test start https://127.0.0.1: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.js

import AboutPage from '../../pages/about'
 
describe('<AboutPage />', () => {
  it('should render and display expected content', () => {
    // Mount the React component for the About page
    cy.mount(<AboutPage />)
 
    // The new page should contain an h1 with "About page"
    cy.get('h1').contains('About')
 
    // Validate that a link with the expected URL is present
    // *Following* the link is better suited to an E2E test
    cy.get('a[href="/"]').should('be.visible')
  })
})

值得注意:

Cypress 目前不支持 async 服务器组件的组件测试。我们建议使用端到端测试。

由于组件测试不需要 Next.js 服务器，因此像 <Image /> 这样依赖于服务器可用的功能可能无法开箱即用。

运行组件测试

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

持续集成 (CI)

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

package.json

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

您可以从以下资源中了解有关 Cypress 和持续集成的更多信息。