メインコンテンツまでスキップ

Next.js での Cypress のセットアップ

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

警告:

  • コンポーネントテストについては、Cypressは現在、Next.jsバージョン14とasyncサーバーコンポーネントをサポートしていません。これらの問題は追跡されています。今のところ、Next.jsバージョン13ではコンポーネントテストが機能し、asyncサーバーコンポーネントにはE2Eテストをお勧めします。
  • Cypressバージョン13.6.3未満では、moduleResolution:"bundler"を使用したTypeScriptバージョン5をサポートしていません。ただし、この問題はCypressバージョン13.6.3以降で解決されています。cypress v13.6.3

クイックスタート​

create-next-appを使用して、with-cypress例を利用し、迅速に開始できます。

Terminal
npx create-next-app@latest --example with-cypress with-cypress-app

手動セットアップ​

Cypressを手動でセットアップするには、cypressを開発依存としてインストールします：

Terminal
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テストスイートを開きます：

Terminal
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>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"を含む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テストスイートを実行します。

Good to know:

  • cypress.config.jsファイルにbaseUrl: 'http://localhost:3000'を追加することで、cy.visit("http://localhost:3000/")の代わりにcy.visit("/")を使用することができます。
  • 代わりに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.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"を含むh1が存在するはずです
    cy.get('h1').contains('Home')

    // 期待されるURLを持つリンクが存在することを確認します
    // リンクのフォローはE2Eテストに適しています
    cy.get('a[href="/about"]').should('be.visible')
  })
})

Good to know:

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