Node.js のビルドとテスト

はじめに

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

必要な環境

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

• 「GitHub Actions を学ぶ」
• 「Node.js を使ってみる」

Node.jsワークフローテンプレートでの開始

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

手早く始めるために、テンプレートをリポジトリの.github/workflowsディレクトリに追加してください。

name: Node.js CI

on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x, 15.x]

    steps:
    - uses: actions/checkout@v2
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

様々なオペレーティングシステム上での実行

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

runs-on: windows-latest

あるいはGitHubホストのmacOSランナーで実行させることもできます。

runs-on: windows-latest

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

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

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

strategy:
  matrix:
    node-version: [10.x, 12.x, 14.x, 15.x]

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

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

strategy:
  matrix:
    node-version: [8.16.2, 10.17.0]

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

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Use Node.js
      uses: actions/setup-node@v1
      with:
        node-version: '12.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もインストールされています。

GitHubホストランナーを使用する場合、依存関係をキャッシュしてワークフローの実行を高速化することもできます。 詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。

npmの利用例

以下の例では、package.jsonファイルで定義された依存関係がインストールされます。 詳しい情報についてはnpm installを参照してください。

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

npm ciを使うと、 package-lock.jsonあるいはnpm-shrinkwrap.jsonファイル中のバージョンがインストールされ、ロックファイルの更新を回避できます。 概してnpm ciは、npm installを実行するよりも高速です。 詳しい情報についてはnpm ci及び「Introducing npm ci for faster, more reliable builds」を参照してください。

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

Yarnの利用例

以下の例では、package.jsonファイルで定義された依存関係がインストールされます。 詳しい情報についてはyarn installを参照してください。

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    node-version: '12.x'
- name: Install dependencies
  run: yarn

あるいは--frozen-lockfileを渡してyarn.lockファイル中のバージョンをインストールし、yarn.lockファイルの更新を回避できます。

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

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

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

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

以下の例では、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を参照してください。

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    always-auth: true
    node-version: '12.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

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

GitHub ホストランナーを使用する場合、一意のキーを使用して依存関係をキャッシュし、cache アクションを使用して将来のワークフローを実行するときに依存関係を復元できます。 詳しい情報については「ワークフローを高速化するための依存関係のキャッシング」及びcacheアクションを参照してください。

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    node-version: '12.x'
- name: Cache Node.js modules
  uses: actions/cache@v2
  with:
    # npm cache files are stored in `~/.npm` on Linux/macOS
    path: ~/.npm
    key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.OS }}-node-
      ${{ runner.OS }}-
- name: Install dependencies
  run: npm ci

コードのビルドとテスト

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

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

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

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

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

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