Node.js のビルドとテスト

はじめに

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

前提条件

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

Node.js ワークフローテンプレートの使用

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

GitHub では、ほとんどの Node.js プロジェクトで動作する Node.js 用のワークフローテンプレートを提供しています。このガイドの以降のセクションでは、このワークフローテンプレートをカスタマイズする方法の例を示します。

GitHub で、リポジトリのメインページに移動します。
リポジトリ名の下にある [アクション] をクリックします。
ワークフローが既にリポジトリ内にある場合は、 [新しいワークフロー] をクリックします。
[ワークフローの選択] ページには、推奨されるワークフローテンプレートの選択が表示されます。「Node.js」を検索します。
[継続的インテグレーション] をクリックして、ワークフローの選択をフィルター処理します。
[Node.js] ワークフローで、[構成] をクリックします。
必要に応じてワークフローを編集します。たとえば、使用する Node のバージョンを変更します。
[変更をコミットする] をクリックします。

node.js.yml ワークフローファイルがリポジトリの .github/workflows ディレクトリに追加されます。

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 に追加する必要があります。

ワークフローテンプレートには、node-version で一覧表示された Node.js バージョンを使用してコードをビルドおよびテストするマトリックス戦略が含まれています。このバージョン番号の'x'はワイルドカード文字で、あるバージョンで利用できる最新のマイナー及びパッチリリースにマッチします。 node-version 配列で指定された Node.js の各バージョンに対して、同じステップを実行するジョブが作成されます。

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

YAML

strategy:
  matrix:
    node-version: ['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 }}

strategy:
  matrix:
    node-version: ['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']

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: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

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: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Node.jsのバージョンを指定しなかった場合、GitHubは環境のデフォルトのNode.jsのバージョンを使います。詳しくは、「GitHub ホステッドランナーの使用」をご覧ください。

依存関係のインストール

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: '20.x'
- name: Install dependencies
  run: npm ci

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.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: '20.x'
- name: Install dependencies
  run: npm install

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.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: '20.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.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: '20.x'
- name: Install dependencies
  run: yarn

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.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: '20.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '20.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: '20'
    cache: 'npm'
- run: npm install
- run: npm test

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

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

YAML

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

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    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: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

# このワークフローは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: '20'
    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: '20.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

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

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

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

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

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

Node.js のビルドとテスト

この記事の内容