Node.js のビルドとテスト

この記事の内容

Node.jsプロジェクトのビルドとテストのための継続的インテグレーション（CI）ワークフローを作成できます。

はじめに

このガイドでは、Node.jsのコードのビルドとテストを行う継続的インテグレーション（CI）ワークフローの作成方法を紹介します。 CIテストにパスしたなら、コードをデプロイしたりパッケージを公開したりすることになるでしょう。

前提条件

Node.js、YAML、ワークフローの設定オプションと、ワークフローファイルの作成方法についての基本的な知識を持っておくことをおすすめします。 詳細については、次を参照してください。

Node.js スターター ワークフローの使用

GitHub では、ほとんどの Node.js プロジェクトで使用できる Node.js のスターター ワークフローを提供しています。 このガイドには、スターター ワークフローをカスタマイズして利用できる npm および Yarn の例が含まれます。 詳細については、Node.js のスターター ワークフローに関するページを参照してください。

既定のスターター ワークフローは、ビルドとテストのワークフローを構築するときに適した出発点であり、プロジェクトの要求に合わせてこのスターター ワークフローをカスタマイズできます。

すぐに作業を開始するには、リポジトリの .github/workflows ディレクトリにスターター ワークフローを追加します。

YAML
name: Node.js CI

The name of the workflow. GitHub displays the names of your workflows under your repository's "Actions" tab. If you omit name, GitHub displays the workflow file path relative to the root of the repository.

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

This example workflow assumes that the default branch for your repository is main. If the default branch has a different name, edit this example and add your repository's default branch.

jobs:
  build:
    runs-on: ubuntu-latest

このワークフローは、別のオペレーティング システムを使用して実行できます。

スターター ワークフローは、GitHub ホスト ubuntu-latest ランナーを使って Linux 上で実行するジョブを設定します。 runs-on キーを変更すると、別のオペレーティング システムでジョブを実行するようにできます。

たとえば、runs-on: windows-latest を指定すると、GitHub がホストする Windows ランナーを使うことができます。 あるいは、runs-on: macos-latest を使用すると、GitHub がホストする macOS ランナーで実行させることもできます。

Dockerコンテナ上でジョブを実行させたり、独自のインフラストラクチャ上で動作するセルフホストランナーを提供したりすることもできます。 詳しくは、「GitHub Actions のワークフロー構文」を参照してください。

    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x, 20.x]

This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "ジョブにマトリックスを使用する."

    steps:
      - uses: actions/checkout@v4

このステップでは、actions/checkout アクションで、ランナーにリポジトリのコピーをダウンロードします。

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

This step uses the actions/setup-node action to set up Node.js for each version indicated by the matrix.node-version key above.

      - run: npm ci

This step runs npm ci to install any dependencies listed in your package.json file.

      - run: npm run build --if-present

This step runs the build script if there is one specified under the scripts key in your package.json file.

      - run: npm test

This step runs the test script that is specified under the scripts key in your package.json file.

# The name of the workflow. GitHub displays the names of your workflows under your repository's "Actions" tab. If you omit `name`, GitHub displays the workflow file path relative to the root of the repository.
name: Node.js CI

# This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch.
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

#
jobs:
  build:

    # <!-- This is a YAML comment for use in annotated code examples. -->
    # このワークフローは、別のオペレーティング システムを使用して実行できます。
    #
    # スターター ワークフローは、GitHub ホスト `ubuntu-latest` ランナーを使って Linux 上で実行するジョブを設定します。 `runs-on` キーを変更すると、別のオペレーティング システムでジョブを実行するようにできます。
    #
    # たとえば、`runs-on: windows-latest` を指定すると、GitHub がホストする Windows ランナーを使うことができます。 あるいは、`runs-on: macos-latest` を使用すると、GitHub がホストする macOS ランナーで実行させることもできます。
    #
    # Dockerコンテナ上でジョブを実行させたり、独自のインフラストラクチャ上で動作するセルフホストランナーを提供したりすることもできます。 詳しくは、「[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)」を参照してください。
    runs-on: ubuntu-latest

    # This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)."
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x, 20.x]
#
    steps:
      # このステップでは、`actions/checkout` アクションで、ランナーにリポジトリのコピーをダウンロードします。
      - uses: actions/checkout@v4
      # This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above.
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      # This step runs `npm ci` to install any dependencies listed in your `package.json` file.
      - run: npm ci
      # This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file.
      - run: npm run build --if-present
      # This step runs the `test` script that is specified under the `scripts` key in your `package.json` file.
      - run: npm test

Node.jsのバージョンの指定

最も簡単に Node.js のバージョンを指定する方法は、GitHub によって提供される setup-node アクションを使用することです。 詳細については、setup-node に関するページを参照してください。

setup-node アクションでは Node.js のバージョンを入力として取り、ランナー上でそのバージョンを構成します。 setup-node アクションでは、各ランナーのツール キャッシュから特定のバージョンの Node.js を見つけ、必要なバイナリを PATH に追加します。これは、残りのジョブで永続化されます。 setup-node アクションを利用することは、GitHub Actions で Node.js を使用するための推奨される方法です。そうすることで様々なランナーや様々なバージョンの Node.js で一貫した動作が保証されるのです。 セルフホスト ランナーを使用している場合は、Node.js をインストールし、それを PATH に追加する必要があります。

スターター ワークフローには、4 つの Node.js バージョン (14.x、16.x、18.x、および 20.x) を使用してコードをビルドおよびテストするマトリックス戦略が含まれています。 この'x'はワイルドカードキャラクターで、そのバージョンで利用できる最新のマイナー及びパッチリリースにマッチします。 node-version 配列で指定された Node.js の各バージョンに対して、同じステップを実行するジョブが作成されます。

各ジョブでは、matrix コンテキストを使用してマトリックス node-version 配列で定義された値にアクセスできます。 setup-node アクションでは、コンテキストが node-version 入力として使用されます。 setup-node アクションでは、コードのビルドとテストに先立って、様々な Node.js のバージョンで各ジョブを設定します。 マトリックスの戦略とコンテキストについて詳しくは、「GitHub Actions のワークフロー構文」と「コンテキスト」をご覧ください。

YAML
strategy:
  matrix:
    node-version: [14.x, 16.x, 18.x, 20.x]

steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}

あるいは、厳密にNode.jsバージョンを指定してビルドとテストを行うこともできます。

YAML
strategy:
  matrix:
    node-version: [10.17.0, 17.9.0]

または、Node.jsの1つのバージョンを使ってビルドとテストを行うこともできます。

YAML
name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Node.jsのバージョンを指定しなかった場合、GitHubは環境のデフォルトのNode.jsのバージョンを使います。 詳しくは、「Using GitHub-hosted runners」をご覧ください。

依存関係のインストール

GitHubホストランナーには、依存関係マネージャーのnpmとYarnがインストールされています。 コードのビルドとテストに先立って、npmやYarnを使ってワークフロー中で依存関係をインストールできます。 Windows及びLinuxのGitHubホストランナーには、Grunt、Gulp、Bowerもインストールされています。

ワークフローの速度を上げるために、依存関係をキャッシュすることもできます。 詳細については、「依存関係をキャッシュしてワークフローのスピードを上げる」を参照してください。

npmの利用例

この例では、package-lock.json ファイルまたは npm-shrinkwrap.json ファイル内のバージョンがインストールされ、ロック ファイルの更新が防止されます。 npm ci を使用する方法は一般に npm install を実行する方法よりも高速です。 詳細については、「npm ci」 および「より高速で信頼性の高いビルドのための npm ci の導入」を参照してください。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.x'
- name: Install dependencies
  run: npm ci

npm install を使うと、package.json ファイルで定義された依存関係がインストールされます。 詳細については、「npm install」を参照してください。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.x'
- name: Install dependencies
  run: npm install

Yarnの利用例

この例では、yarn.lock ファイルで定義されている依存関係がインストールされ、yarn.lock ファイルの更新が防止されます。 詳細については、「yarn install」を参照してください。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

または、package.json ファイルで定義されている依存関係をインストールすることもできます。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.x'
- name: Install dependencies
  run: yarn

プライベートレジストリの利用と.npmrcファイルの作成の例

setup-node アクションを使用して、既定のレジストリとスコープを構成するローカルの .npmrc ファイルをランナーに作成できます。 setup-node アクションは、プライベート リポジトリへのアクセスや node パッケージの公開に使われる認証トークンも入力として受け付けます。 詳細については、setup-node をご覧ください。

プライベートレジストリに対して認証するには、npm 認証トークンをシークレットとして保存する必要があります。 たとえば、NPM_TOKEN というリポジトリ シークレットを作成します。 詳しくは、「GitHub Actions でのシークレットの使用」を参照してください。

以下の例では、NPM_TOKEN というシークレットには npm の認証トークンが保存されます。 setup-node アクションでは、NODE_AUTH_TOKEN 環境変数から npm 認証トークンを読み取るように、 .npmrc ファイルを構成します。 setup-node アクションを使用して .npmrc ファイルを作成する場合は、npm 認証トークンを含むシークレットを使用して NODE_AUTH_TOKEN 環境変数を設定する必要があります。

依存関係をインストールする前に、setup-node アクションを使用して .npmrc ファイルを作成します。 このアクションには2つの入力パラメーターがあります。 node-version パラメーターによって、Node.js のバージョンが設定され、registry-url パラメーターによって既定のレジストリーが設定されます。 パッケージ レジストリでスコープが使用されている場合は、scope パラメーターを使用する必要があります。 詳細については、「npm-scope」を参照してください。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '18.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

上の例では、以下の内容で .npmrc ファイルを作成しています。

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true

依存関係のキャッシングの例

setup-nodeアクションを使用して依存関係をキャッシュおよび復元できます。

次の例では npm の依存関係をキャッシュします。

YAML
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'npm'
- run: npm install
- run: npm test

次の例では Yarn の依存関係をキャッシュします。

YAML
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'yarn'
- run: yarn
- run: yarn test

次の例では pnpm (v6.10+) の依存関係をキャッシュします。

YAML
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

カスタム要件がある場合、またはキャッシュに対してより細かい制御が必要な場合は、cache アクションを使用できます。 詳しくは、「依存関係をキャッシュしてワークフローのスピードを上げる」を参照してください。

コードのビルドとテスト

ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。 たとえば、npm run build を実行することで、package.json ファイルで定義されたビルド ステップを実行し、さらに npm test を実行することでテスト スイートを実行する場合は、それらのコマンドをワークフロー ファイルに追加します。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

成果物としてのワークフローのデータのパッケージ化

ビルドとテストのステップの成果物を保存し、ジョブの完了後に見ることができます。 たとえば、ログファイル、コアダンプ、テスト結果、スクリーンショットを保存する必要があるかもしれません。 詳しくは、「ワークフロー データを成果物として保存する」を参照してください。

パッケージレジストリへの公開

CIテストにパスした後、Node.jsパッケージをパッケージレジストリに公開するようにワークフローを設定できます。 npm と GitHub Packages への公開について詳しくは、「Node.jsパッケージの公開」をご覧ください。