Skip to main content

配置 Cypress 与 Next.js

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

warning
  • 对于组件测试,Cypress 目前不支持 Next.js 版本 14 和异步 Server 组件。这些问题正在被跟踪。目前,组件测试适用于 Next.js 版本 13,我们建议对异步 Server 组件使用端到端测试。
  • 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 以打开 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 文件:

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', () => {
// 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')
})
})

运行端到端测试

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

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

需要注意的是:

  • 您可以通过将 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 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('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')
})
})

运行组件测试

在您的终端中运行 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 和持续集成的更多信息: