logoNext.js 日本語
ドキュメントブログ学習
はじめに/アプリケーションの構築/テスト/Cypress

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

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

警告:

  • コンポーネントテストについては、Cypress は現在 Next.js バージョン 14 と async サーバーコンポーネントをサポートしていません。これらの問題は追跡中です。現時点では、コンポーネントテストは Next.js バージョン 13 で動作し、async サーバーコンポーネントには E2E テストを使用することを推奨します。
  • Cypress は現在、moduleResolution:"bundler" を使用した TypeScript バージョン 5 をサポートしていません。この問題は追跡中です。

クイックスタート

with-cypress サンプル を使用して 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 フィールドに追加します:

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) {},
  },
})

次に、2つの新しい Next.js ファイルを作成します:

app/page.js
import Link from 'next/link'

export default function Page() {
  return (
    <div>
      <h1>ホーム</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="/">ホーム</Link>
    </div>
  )
}

ナビゲーションが正しく動作することを確認するテストを追加します:

cypress/e2e/app.cy.js
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 サーバーが実行されている必要があります。アプリケーションの動作をより正確に再現するため、本番コードに対してテストを実行することを推奨します。

npm run build && npm run start を実行して Next.js アプリケーションをビルドし、別のターミナルウィンドウで 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.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('期待されるコンテンツをレンダリングして表示すること', () => {
    // ホームページの 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 環境により適しています:

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

Playwright

Next.js でエンドツーエンド (E2E) テストを行うために Playwright をセットアップする方法を学びます。

認証

Next.js での認証実装方法について学びます。ベストプラクティス、ルート保護、認可技術、セッション管理を網羅しています。