設定 Next.js 的 Cypress

Cypress 是一個用於端對端 (E2E) 和元件測試的測試執行器。本頁面將說明如何設定 Next.js 的 Cypress 並編寫您的第一個測試。

警告

低於 13.6.3 的 Cypress 版本不支援 TypeScript 版本 5 與 moduleResolution:"bundler"。但是，此問題已在 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
# 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

您可以選擇設定E2E 測試和/或元件測試。選擇任何這些選項都會自動在您的專案中建立 cypress.config.js 檔案和 cypress 資料夾。

建立您的第一個 Cypress E2E 測試

確保您的 cypress.config 檔案具有以下設定

cypress.config.ts

import { defineConfig } from 'cypress'
 
export default 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('https://#: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 測試套件。

要知道的好事

您可以透過將 baseUrl: 'https://#:3000' 新增至 cypress.config.js 設定檔，來使用 cy.visit("/") 而不是 cy.visit("https://#:3000/")。

或者，您可以安裝 start-server-and-test 套件，以將 Next.js 生產伺服器與 Cypress 結合執行。安裝後，將 "test": "start-server-and-test start https://#:3000 cypress" 新增至您的 package.json scripts 欄位。請記住，在進行新的變更後重新建置您的應用程式。

建立您的第一個 Cypress 元件測試

元件測試會建置並掛載特定的元件，而無需捆綁您的整個應用程式或啟動伺服器。

在 Cypress 應用程式中選取元件測試，然後選取 Next.js 作為您的前端框架。將在您的專案中建立 cypress/component 資料夾，並更新 cypress.config.js 檔案以啟用元件測試。

確保您的 cypress.config 檔案具有以下設定

cypress.config.ts

import { defineConfig } from 'cypress'
 
export default 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')
  })
})

要知道的好事:

Cypress 目前不支援 async 伺服器元件的元件測試。我們建議使用 E2E 測試。

由於元件測試不需要 Next.js 伺服器，因此諸如 <Image /> 等依賴伺服器可用的功能可能無法直接運作。

執行元件測試

在您的終端機中執行 npm run cypress:open 以啟動 Cypress 並執行您的元件測試套件。

持續整合 (CI)

除了互動式測試外，您還可以透過使用 cypress run 命令以無頭模式執行 Cypress，這更適合 CI 環境

package.json

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

您可以從以下資源了解更多關於 Cypress 和持續整合的資訊