Lighthouse CI を使用したパフォーマンス モニタリング

GitHub Actions などの継続的インテグレーション システムに Lighthouse を追加する方法。

Katie Hempenius

Lighthouse CI は、継続的インテグレーションで Lighthouse を使用するためのツールスイートです。Lighthouse CI は、さまざまな方法でデベロッパー ワークフローに組み込むことができます。このガイドでは、次のトピックについて説明します。

• Lighthouse CI CLI を使用する。
• Lighthouse CI を実行するように CI プロバイダを構成する。
• Lighthouse CI の GitHub アクションとステータス チェックを設定する。これにより、GitHub の pull リクエストに Lighthouse の結果が自動的に表示されます。
• Lighthouse レポート用のパフォーマンス ダッシュボードとデータストアを構築する。

概要

Lighthouse CI は、Lighthouse によるパフォーマンス モニタリングを容易にする一連の無料ツールです。Lighthouse のレポートでは、実行時にウェブページのパフォーマンスのスナップショットを確認できます。Lighthouse CI では、検出結果の経時的な変化を確認できます。これは、特定のコード変更の影響を特定するためや、継続的インテグレーション プロセス中にパフォーマンスしきい値を確実に満たすために使用できます。パフォーマンス モニタリングは Lighthouse CI の最も一般的なユースケースですが、SEO やユーザー補助など、Lighthouse レポートの他の側面のモニタリングにも使用できます。

Lighthouse CI のコア機能は、Lighthouse CI コマンドライン インターフェースで提供されます。（注: これは Lighthouse CLI とは別のツールです）。Lighthouse CI CLI には、Lighthouse CI を使用するための一連のコマンドが用意されています。たとえば、autorun コマンドは、Lighthouse を複数回実行して、Lighthouse レポートの中央値を特定し、保存するレポートをアップロードします。この動作は、追加のフラグを渡すか、Lighthouse CI の構成ファイル lighthouserc.js をカスタマイズすることで、大幅にカスタマイズできます。

Lighthouse CI のコア機能は主に Lighthouse CI CLI にカプセル化されていますが、Lighthouse CI は通常、次のいずれかの方法で使用されます。

• 継続的インテグレーションの一環として Lighthouse CI を実行する
• すべての pull リクエストに対して実行とコメントを行う Lighthouse CI GitHub アクションを使用する
• Lighthouse サーバーが提供するダッシュボードを使用して、パフォーマンスの推移をトラッキングします。

これらのアプローチはすべて、Lighthouse CI CLI を基盤として構築されています。

Lighthouse CI の代わりに、サードパーティのパフォーマンス モニタリング サービスや、CI プロセス中にパフォーマンス データを収集する独自のスクリプトを作成する方法もあります。パフォーマンス モニタリング サーバーとテストデバイスの管理を他のユーザーに任せたい場合、またはこれらの機能を独自に構築せずに通知機能（メールや Slack の統合など）を希望する場合は、サードパーティ サービスの使用を検討する必要があります。

ローカルで Lighthouse CI を使用する

このセクションでは、Lighthouse CI CLI をローカルで実行してインストールする方法と、lighthouserc.js を構成する方法について説明します。lighthouserc.js が正しく構成されていることを確認するには、Lighthouse CI CLI をローカルで実行するのが最も簡単な方法です。

1. Lighthouse CI CLI をインストールします。

   npm install -g @lhci/cli
   

   Lighthouse CI を構成するには、プロジェクトのリポジトリのルートに lighthouserc.js ファイルを配置します。このファイルは必須であり、Lighthouse CI 関連の構成情報が含まれます。Lighthouse CI は git リポジトリなしで使用するように構成できますが、この記事の手順では、プロジェクト リポジトリが git を使用するように構成されていることを前提としています。

2. リポジトリのルートで、lighthouserc.js 構成ファイルを作成します。

   touch lighthouserc.js
   

3. lighthouserc.js に次のコードを追加します。このコードは、空の Lighthouse CI 構成です。この構成は、後のステップで追加します。

   module.exports = {
     ci: {
       collect: {
         /* Add configuration here */
       },
       upload: {
         /* Add configuration here */
       },
     },
   };
   

4. Lighthouse CI が実行されるたびに、サイトを提供するサーバーが起動されます。このサーバーにより、他のサーバーが実行されていない場合でも、Lighthouse はサイトを読み込むことができます。Lighthouse CI の実行が完了すると、サーバーは自動的にシャットダウンされます。サービングが正しく機能するように、staticDistDir プロパティまたは startServerCommand プロパティを構成する必要があります。

   サイトが静的の場合は、ci.collect オブジェクトに staticDistDir プロパティを追加して、静的ファイルの場所を指定します。Lighthouse CI は、サイトのテスト中に独自のサーバーを使用してこれらのファイルを提供します。サイトが静的でない場合は、ci.collect オブジェクトに startServerCommand プロパティを追加して、サーバーを起動するコマンドを指定します。Lighthouse CI は、テスト中に新しいサーバー プロセスを開始し、その後、シャットダウンします。

   // Static site example
   collect: {
     staticDistDir: './public',
   }
   

   // Dynamic site example
   collect: {
     startServerCommand: 'npm run start',
   }
   

5. ci.collect オブジェクトに url プロパティを追加して、Lighthouse CI による Lighthouse CI の実行対象 URL を指定します。url プロパティの値は、URL の配列として指定します。この配列には 1 つ以上の URL を含めることができます。デフォルトでは、Lighthouse CI は各 URL に対して Lighthouse CI を 3 回実行します。

   collect: {
     // ...
     url: ['http://localhost:8080']
   }
   

6. target プロパティを ci.upload オブジェクトに追加し、値を 'temporary-public-storage' に設定します。Lighthouse CI で収集された Lighthouse レポートは、一時的な公開ストレージにアップロードされます。レポートは 7 日間表示された後、自動的に削除されます。この設定ガイドでは、簡単に設定できる「一時的な公開ストレージ」のアップロード オプションを使用します。Lighthouse レポートを保存するその他の方法については、こちらのドキュメントをご覧ください。

   upload: {
     target: 'temporary-public-storage',
   }
   

   レポートの保存場所は次のようになります。

   https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html
   

   （レポートはすでに削除されているため、この URL は機能しません）。

7. ターミナルから autorun コマンドを使用して、Lighthouse CI CLI を実行します。これにより、Lighthouse が 3 回実行され、Lighthouse レポートの中央値がアップロードされます。

   lhci autorun
   

   Lighthouse CI が正しく構成されている場合、このコマンドを実行すると、次のような出力が生成されます。

   ✅  .lighthouseci/ directory writable
   ✅  Configuration file found
   ✅  Chrome installation found
   ⚠️   GitHub token not set
   Healthcheck passed!
   
   Started a web server on port 65324...
   Running Lighthouse 3 time(s) on http://localhost:65324/index.html
   Run #1...done.
   Run #2...done.
   Run #3...done.
   Done running Lighthouse!
   
   Uploading median LHR of http://localhost:65324/index.html...success!
   Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591720514021-82403.report.html
   No GitHub token set, skipping GitHub status check.
   
   Done running autorun.
   

   コンソール出力の GitHub token not set メッセージは無視してかまいません。GitHub トークンは、GitHub アクションで Lighthouse CI を使用する場合にのみ必要です。GitHub Action の設定方法については、この記事の後半で説明します。

   出力で https://storage.googleapis.com... で始まるリンクをクリックすると、Lighthouse の実行の中央値に対応する Lighthouse レポートが表示されます。

   autorun で使用されるデフォルトは、コマンドラインまたは lighthouserc.js でオーバーライドできます。たとえば、以下の lighthouserc.js 構成は、autorun が実行されるたびに 5 つの Lighthouse 実行を収集する必要があることを示しています。

8. numberOfRuns プロパティを使用するように lighthouserc.js を更新します。

   module.exports = {
       // ...
       collect: {
         numberOfRuns: 5
       },
     // ...
     },
   };
   

9. autorun コマンドを再実行します。

   lhci autorun
   

   ターミナルの出力を見ると、Lighthouse がデフォルトの 3 回ではなく 5 回実行されたことがわかります。

   ✅  .lighthouseci/ directory writable
   ✅  Configuration file found
   ✅  Chrome installation found
   ⚠️   GitHub token not set
   Healthcheck passed!
   
   Automatically determined ./dist as `staticDistDir`.
   Set it explicitly in lighthouserc.json if incorrect.
   
   Started a web server on port 64444...
   Running Lighthouse 5 time(s) on http://localhost:64444/index.html
   Run #1...done.
   Run #2...done.
   Run #3...done.
   Run #4...done.
   Run #5...done.
   Done running Lighthouse!
   
   Uploading median LHR of http://localhost:64444/index.html...success!
   Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591716944028-6048.report.html
   No GitHub token set, skipping GitHub status check.
   
   Done running autorun.
   

   他の構成オプションについては、Lighthouse CI の構成ドキュメントをご覧ください。

Lighthouse CI を実行するための CI プロセスを設定する

Lighthouse CI は、お好みの CI ツールで使用できます。Lighthouse CI ドキュメントの CI プロバイダの構成セクションには、一般的な CI ツールの構成ファイルに Lighthouse CI を組み込む方法を示すコードサンプルが含まれています。具体的には、以下のコードサンプルは、Lighthouse CI を実行して CI プロセス中にパフォーマンス測定値を収集する方法を示しています。

パフォーマンス モニタリングを開始するには、Lighthouse CI を使用してパフォーマンス測定値を収集することをおすすめします。ただし上級ユーザーは、さらに一歩進んで、特定の Lighthouse 監査に合格する、すべてのパフォーマンス バジェットを満たすなど、事前に定義された基準を満たしていない場合、Lighthouse CI を使用してビルドを失敗させることをおすすめします。この動作は、lighthouserc.js ファイルの assert プロパティで構成します。

Lighthouse CI では、次の 3 つのレベルのアサーションがサポートされています。

• off: アサーションを無視する
• warn: エラーを stderr に出力する
• error: エラーを stderr に出力し、ゼロ以外の終了コードで Lighthouse CI を終了します。

アサーションを含む lighthouserc.js 構成の例を次に示します。Lighthouse のパフォーマンス カテゴリとユーザー補助カテゴリのスコアに関するアサーションを設定します。これを試すには、以下に示すアサーションを lighthouserc.js ファイルに追加してから、Lighthouse CI を再実行します。

module.exports = {
  ci: {
    collect: {
      // ...
    },
    assert: {
      assertions: {
        'categories:performance': ['warn', {minScore: 1}],
        'categories:accessibility': ['error', {minScore: 1}]
      }
    },
    upload: {
      // ...
    },
  },
};

生成されるコンソール出力は次のようになります。

Lighthouse CI アサーションの詳細については、こちらのドキュメントをご覧ください。

Lighthouse CI を実行する GitHub アクションを設定する

GitHub アクションを使用して Lighthouse CI を実行できます。これにより、GitHub リポジトリのブランチにコード変更が push されるたびに、新しい Lighthouse レポートが生成されます。これをステータス チェックと併用すると、各 pull リクエストでこれらの結果を表示できます。

1. リポジトリのルートに、.github/workflows という名前のディレクトリを作成します。プロジェクトのワークフローは、このディレクトリに配置されます。ワークフローは、所定の時間（コードが push されたときなど）に実行されるプロセスで、1 つ以上のアクションで構成されます。

   mkdir .github
   mkdir .github/workflows
   

2. .github/workflows で、lighthouse-ci.yaml という名前のファイルを作成します。このファイルには、新しいワークフローの構成が保持されます。

   touch lighthouse-ci.yaml
   

3. lighthouse-ci.yaml に次のテキストを追加します。

   name: Build project and run Lighthouse CI
   on: [push]
   jobs:
     lhci:
       name: Lighthouse CI
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v1
         - name: Use Node.js 10.x
           uses: actions/setup-node@v1
           with:
             node-version: 10.x
         - name: npm install
           run: |
             npm install
         - name: run Lighthouse CI
           run: |
             npm install -g @lhci/cli@0.3.x
             lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"
   

   この構成では、新しいコードがリポジトリに push されるたびに実行される単一のジョブで構成されるワークフローが設定されます。このジョブには 4 つのステップがあります。

   • Lighthouse CI が実行されるリポジトリを確認する
   • Node をインストールして構成する
   • 必要な npm パッケージをインストールする
   • Lighthouse CI を実行し、結果を一時的な公開ストレージにアップロードする。

4. これらの変更を commit して GitHub に push します。上記の手順を正しく実行していれば、GitHub にコードを push すると、追加したワークフローの実行がトリガーされます。

5. Lighthouse CI がトリガーされたことを確認し、生成されたレポートを表示するには、プロジェクトの [操作] タブに移動します。最新の commit に [Build project and Run Lighthouse CI] ワークフローが表示されます。

   

   [アクション] タブから、特定の commit に対応する Lighthouse レポートに移動できます。commit をクリックし、[Lighthouse CI] ワークフロー ステップをクリックしてから、[run Lighthouse CI] ステップの結果を展開します。

   

   これで、Lighthouse CI を実行する GitHub アクションの設定が完了しました。これは、GitHub のステータス チェックと組み合わせて使用すると非常に便利です。

GitHub ステータス チェックを設定する

ステータス チェックが構成されている場合、すべての PR に表示されるメッセージで、通常はテストの結果やビルドの成功などの情報が含まれます。

以下の手順では、Lighthouse CI のステータス チェックをセットアップする方法について説明します。

1. Lighthouse CI GitHub アプリページに移動し、[構成] をクリックします。

2. （省略可）GitHub の複数の組織に所属している場合は、Lighthouse CI を使用するリポジトリを所有する組織を選択します。

3. すべてのリポジトリで Lighthouse CI を有効にする場合は [All repositories] を選択し、特定のリポジトリでのみ使用する場合は [Only select repositories] を選択して、リポジトリを選択します。次に、[インストールと承認] をクリックします。

4. 表示されたトークンをコピーします。これを次のステップで使用します。

5. トークンを追加するには、GitHub リポジトリの [Settings] ページに移動し、[Secret] をクリックしてから、[Add a new secret] をクリックします。

   

6. [名前] フィールドを LHCI_GITHUB_APP_TOKEN に設定し、[値] フィールドに前の手順でコピーしたトークンを設定し、[シークレットを追加] ボタンをクリックします。

7. lighthouse-ci.yaml ファイルに移動し、新しい環境 Secret を「run Lighthouse CI」コマンドに追加します。

-           name: run Lighthouse CI
            run: |
              npm install -g @lhci/cli@0.3.x
              lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"
+            env:
+              LHCI_GITHUB_APP_TOKEN: $

1. ステータス チェックを使用する準備ができました。テストするには、新しい pull リクエストを作成するか、既存の pull リクエストに commit を push します。

Lighthouse CI サーバーを設定する

Lighthouse CI サーバーには、過去の Lighthouse レポートを確認するためのダッシュボードが用意されています。また、Lighthouse レポート用の非公開の長期データストアとしても機能します。

1. 比較する commit を選択します。
2. 2 つの commit 間で Lighthouse のスコアが変化した量。
3. このセクションには、2 つの commit 間で変化した指標のみが表示されます。
4. 回帰はピンクでハイライト表示されます。
5. 改善点は青色でハイライト表示されます。

Lighthouse CI Server は、独自のインフラストラクチャのデプロイと管理に慣れているユーザーに最適です。

デプロイに Heroku と Docker を使用する場合のレシピなど、Lighthouse CI サーバーの設定の詳細については、こちらのinstructionsをご覧ください。

補足説明

• Lighthouse CI GitHub リポジトリ