Setting up Cypress with Next.js
Cypress 是一个用于端到端 (E2E) 和组件测试的测试运行器。本页将向你展示如何在 Next.js 中设置 Cypress 并编写你的第一个测试。
警告:
- 低于 13.6.3 版本的 Cypress 不支持使用
moduleResolution:"bundler"
的 TypeScript 5 版本。但是,这个问题已在 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
# 或
yarn add -D cypress
# 或
pnpm install -D cypress
将 Cypress open
命令添加到 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
你可以选择配置端到端测试和/或组件测试。选择任何这些选项将自动在你的项目中创建一个 cypress.config.js
文件和一个 cypress
文件夹。
创建你的第一个 Cypress E2E 测试
确保你的 cypress.config
文件具有以下配置:
import { defineConfig } from 'cypress'
export default 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 测试套件。
值得注意的是:
- 你可以使用
cy.visit("/")
而不是cy.visit("http://localhost:3000/")
,方法是在cypress.config.js
配置文件中添加baseUrl: '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
文件具有以下配置:
import { defineConfig } from 'cypress'
export default 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 服务器,依赖于服务器可用的功能(如
<Image />
)可能无法开箱即用。
运行组件测试
在你的终端中运行 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 和持续集成的信息: