Next.jsでCypressをセットアップする方法

Cypressは、エンドツーエンド（E2E）テストとコンポーネントテストに使用されるテストランナーです。このページでは、Next.jsでCypressをセットアップし、最初のテストを書く方法を説明します。

警告:

• Cypressバージョン13.6.3未満では、TypeScriptバージョン5のmoduleResolution:"bundler"をサポートしていません。この問題はCypressバージョン13.6.3以降で修正されています。cypress v13.6.3

クイックスタート

with-cypress exampleを使用して、create-next-appで素早く開始できます。

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

E2Eテストと/またはコンポーネントテストを設定するかを選択できます。いずれかのオプションを選択すると、自動的にcypress.config.jsファイルとcypressフォルダがプロジェクトに作成されます。

最初のCypress E2Eテストを作成する

cypress.configファイルに以下の設定があることを確認してください：

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {},
  },
})

次に、2つの新しい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('ナビゲーション', () => {
  it('aboutページに遷移すること', () => {
    // インデックスページから開始
    cy.visit('http://localhost:3000/')

    // "about"を含むhref属性を持つリンクを見つけてクリック
    cy.get('a[href*="about"]').click()

    // 新しいURLに"/about"が含まれること
    cy.url().should('include', '/about')

    // 新しいページに"About"というh1が含まれること
    cy.get('h1').contains('About')
  })
})

E2Eテストの実行

Cypressはユーザーがアプリケーションを操作する様子をシミュレートするため、Next.jsサーバーが実行されている必要があります。アプリケーションの動作をより正確に再現するために、本番コードに対してテストを実行することを推奨します。

Next.jsアプリケーションをビルドするためにnpm run build && npm run startを実行し、別のターミナルウィンドウでnpm run cypress:openを実行してCypressを起動し、E2Eテストスイートを実行します。

豆知識:

• cypress.config.js設定ファイルにbaseUrl: 'http://localhost:3000'を追加することで、cy.visit("http://localhost:3000/")の代わりにcy.visit("/")を使用できます。
• または、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ファイルに以下の設定があることを確認してください：

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
  },
})

前のセクションと同じコンポーネントを使用して、コンポーネントが期待される出力をレンダリングしていることを検証するテストを追加します：

import Page from '../../app/page'

describe('<Page />', () => {
  it('期待されるコンテンツをレンダリングして表示すること', () => {
    // ホームページのReactコンポーネントをマウント
    cy.mount(<Page />)

    // 新しいページに"Home"というh1が含まれること
    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環境に適しています：

{
  "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と継続的インテグレーションについてさらに学ぶには、以下のリソースを参照してください：

• Next.js with Cypress example
• Cypress Continuous Integration Docs
• Cypress GitHub Actions Guide
• Official Cypress GitHub Action
• Cypress Discord