Node.js のビルドとテスト

はじめに

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

必要な環境

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

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

GitHub Enterprise Server上でのセルフホストランナーの利用

GitHub Enterprise Server上でセルフホストランナーと合わせてセットアップアクション（actions/setup-LANGUAGEのような）を使う� �合、インターネットアクセスを持たないランナー上にツールキャッシュをセットアップする必要があるかもしれません。 詳しい情� �については「インターネットアクセスを持たないセルフホストランナー上へのツールキャッシュのセットアップ」を参照してく� さい。

Using the Node.js starter workflow

GitHub provides a Node.js starter workflow that will work for most Node.js projects. This guide includes npm and Yarn examples that you can use to customize the starter workflow. For more information, see the Node.js starter workflow.

To get started quickly, add the starter workflow to the .github/workflows directory of your repository. 以下に示すワークフローは、リポジトリのデフォルトブランチが main であることを前提としています。

name: Node.js CI on: push: branches: [ main ] pull_request: branches: [ main ] 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@v2 with: node-version: ${{ matrix.node-version }} - run: npm ci - run: npm run build --if-present - run: npm test

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

The starter workflow configures jobs to run on Linux, using the GitHub-hosted ubuntu-latest runners. runs-onキーを変更し、異なるオペレーティングシステ� でジョブを実行するようにすることができます。 たとえば、GitHubホストのWindowsランナーを使うことができます。

runs-on: windows-latest 

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

runs-on: macos-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に追� しなければなりません。

The starter workflow includes a matrix strategy that builds and tests your code with four Node.js versions: 10.x, 12.x, 14.x, and 15.x. この'x'はワイルドカードキャラクターで、そのバージョンで利用できる最新のマイナー及びパッチリリースにマッチします。 node-version配列で指定されたNode.jsの各バージョンに対して、同じステップを実行するジョブが作成されます。

それぞれのジョブは、配列node-version のマトリクスで定義された値に、matrixコンテキストを使ってアクセスできます。 setup-nodeアクションは、このコンテキストをnode-versionのインプットとして使います。 setup-nodeアクションは、コードのビルドとテストに先立って、様々なNode.jsのバージョンで各ジョブを設定します。 For more information about matrix strategies and contexts, see "Workflow syntax for GitHub Actions" and "Contexts."

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@v2 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@v2 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もインストールされています。

npmの利用例

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

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

Alternatively, you can pass --frozen-lockfile to install the versions in the yarn.lock file and prevent updates to the yarn.lock file.

steps: - uses: actions/checkout@v2 - name: Use Node.js uses: actions/setup-node@v2 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@v2 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 

コードのビルドとテスト

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

steps: - uses: actions/checkout@v2 - name: Use Node.js uses: actions/setup-node@v2 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パッケージの公開」を参照してく� さい。