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

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

Katie Hempenius
Katie Hempenius
X

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 アクションを使用する
  • Lighthouse Server が提供するダッシュボードで、時間の経過に伴うパフォーマンスをトラッキングする。

これらのアプローチはすべて、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 を実行する対象の URL を指定します。url プロパティの値は URL の配列として指定する必要があります。この配列には 1 つ以上の URL を含めることができます。デフォルトでは、Lighthouse CI は各 URL に対して Lighthouse を 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 Action で 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 CI を使用して、特定の Lighthouse 監査に合格する、すべてのパフォーマンス バジェットを満たすなど、事前定義された条件を満たしていない場合にビルドを失敗させる場合があります。この動作は、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 アサーションの詳細については、ドキュメントをご覧ください。

Lighthouse CI を実行する GitHub Actions を設定する

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

GitHub のステータス チェックのスクリーンショット

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

    GitHub の [設定] タブのスクリーンショット

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

    GitHub の [Settings] タブのスクリーンショット

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

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

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

GitHub の [Settings] タブのスクリーンショット

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

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

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

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

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

  5. トークンを追加するには、GitHub リポジトリの [設定] ページに移動し、[シークレット]、[新しいシークレットを追加] の順にクリックします。

    GitHub の [設定] タブのスクリーンショット

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

  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 レポートの限定公開の長期データストアとしても機能します。

Lighthouse CI サーバー ダッシュボードのスクリーンショット
Lighthouse CI Server で 2 つの Lighthouse レポートを比較した場合のスクリーンショット
  1. 比較するコミットを選択します。
  2. 2 つの commit 間で Lighthouse スコアが変化した量。
  3. このセクションには、2 つの commit 間で変更された指標のみが表示されます。
  4. 回帰はピンクでハイライト表示されます。
  5. 改善点は青色でハイライト表示されます。

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

Heroku と Docker を使用してデプロイするレシピなど、Lighthouse CI サーバーの設定については、手順をご覧ください。

補足説明