在 Next.js 中設定 Cypress

Cypress 是一個用於 端到端測試 (E2E) 和 元件測試 的測試執行工具。本頁將展示如何在 Next.js 中設定 Cypress 並撰寫第一個測試。

警告：

對於 元件測試，Cypress 目前不支援 Next.js 第 14 版和 async 伺服器元件。這些問題正在追蹤中。目前元件測試可與 Next.js 第 13 版配合使用，我們建議對 async 伺服器元件使用 E2E 測試。

Cypress 目前不支援搭配 moduleResolution:"bundler" 的 TypeScript 第 5 版。此問題正在追蹤中。

快速開始

您可以使用 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()

    // 新網址應包含 "/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 環境：