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 を使用したパフォーマンス モニタリングを容易にする無料ツールのスイートです。1 つの Lighthouse レポートには、実行時のウェブページのパフォーマンスのスナップショットが表示されます。Lighthouse CI では、これらの結果が時間の経過とともにどのように変化したかが表示されます。これを使用して、特定のコード変更の影響を特定したり、継続的インテグレーション プロセス中にパフォーマンスのしきい値が満たされていることを確認したりできます。パフォーマンス モニタリングは Lighthouse CI の最も一般的なユースケースですが、Lighthouse レポートの他の側面（SEO やユーザー補助など）のモニタリングにも使用できます。

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 Action を使用する
• Lighthouse Server が提供するダッシュボードを使用して、パフォーマンスを継続的にトラッキングする。

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

Lighthouse CI の代替手段としては、サードパーティのパフォーマンス モニタリング サービスを使用するか、CI プロセス中にパフォーマンス データを収集する独自のスクリプトを作成します。パフォーマンス モニタリング サーバーとテストデバイスの管理を他のユーザーに任せたい場合や、通知機能（メールや Slack の統合など）を自分で構築せずに使用したい場合は、サードパーティ サービスの使用を検討してください。

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

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

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 を実行する URL を指定します。url プロパティの値は、URL の配列として指定する必要があります。この配列には、1 つ以上の URL を含めることができます。デフォルトでは、Lighthouse CI は各 URL に対して Lighthouse を 3 回実行します。

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

   注: これらの URL は、前の手順で構成したサーバーで提供できる必要があります。したがって、Lighthouse CI をローカルで実行している場合、これらの URL には本番環境ホストではなく localhost を含める必要があります。

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 Action で Lighthouse CI を使用する場合にのみ必要です。GitHub アクションの設定方法については、この記事の後半で説明します。

   出力内の 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 ドキュメントの Configure Your CI Provider セクションには、一般的な 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 アクションを設定する

注: このセクションは、Git、GitHub、GitHub pull リクエストに精通していることを前提としています。

GitHub Action を使用して 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 がトリガーされたことを確認し、生成されたレポートを表示するには、プロジェクトの [Actions] タブに移動します。最新の commit の下に、Build project and Run Lighthouse CI ワークフローが表示されます。

   

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

   

   Lighthouse CI を実行する GitHub アクションを設定しました。これは、GitHub のステータス チェックと組み合わせて使用すると最も効果的です。

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

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

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

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

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

3. すべてのリポジトリで Lighthouse CI を有効にする場合は [All repositories] を選択し、特定のリポジトリでのみ使用する場合は [Only select repositories] を選択して、リポジトリを選択します。[Install & Authorize] をクリックします。

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

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

   

6. [Name] フィールドを LHCI_GITHUB_APP_TOKEN に設定し、[Value] フィールドを前の手順でコピーしたトークンに設定して、[Add secret] ボタンをクリックします。

7. lighthouse-ci.yaml ファイルに移動し、新しい環境シークレットを「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 サーバーは、独自のインフラストラクチャのデプロイと管理に慣れているユーザーに最適です。

Lighthouse CI サーバーの設定方法（Heroku と Docker を使用したデプロイ方法など）については、こちらの手順をご覧ください。

詳細

• Lighthouse CI GitHub リポジトリ