lighthouse-scanner

Lighthouse CI アクセシビリティ統合

Lighthouse CI とは？

Lighthouse CI は、CI パイプラインで Google Lighthouse の監査を実行するためのツール群です。最も一般的な GitHub Actions との統合では、treosh/lighthouse-ci-action を使用します。

Lighthouse は次の機能を提供します。

• パフォーマンス、アクセシビリティ、ベストプラクティス、SEO のスコア（0～100）
• 合否ステータスと詳細な検出結果を含む、個々の監査結果
• 回帰時にビルドを失敗させるためのスコア予算とアサーション
• HTML および JSON のレポートアーティファクト
• 傾向を追跡するための、実行間のスコア比較

アクセシビリティに関する重点項目： Lighthouse のアクセシビリティカテゴリでは、axe-core ルールの一部を実行し、重み付けされた 0～100 のスコアと、個々の監査での違反を報告します。

Lighthouse CI の導入状況の検出

ワークフローファイルの検出

Lighthouse CI を参照しているワークフローファイルを検索します。

# Search for the treosh Lighthouse CI action
grep -rl "treosh/lighthouse-ci-action" .github/workflows/

# Search for official Lighthouse CI CLI usage
grep -rl "lhci autorun\|lighthouse-ci" .github/workflows/

YAML 内で照合するパターン：

- uses: treosh/lighthouse-ci-action@v12

設定ファイルの検出

Lighthouse CI では、リポジトリのルートにある設定ファイルを使用します。

# Check for Lighthouse CI config files
ls lighthouserc.js lighthouserc.json .lighthouserc.js .lighthouserc.json .lighthouserc.yml 2>/dev/null

設定ファイル	形式
lighthouserc.js	JavaScript モジュール
lighthouserc.json	JSON
.lighthouserc.js	JavaScript モジュール（ドットファイル）
.lighthouserc.json	JSON（ドットファイル）
.lighthouserc.yml	YAML（ドットファイル）

設定の構造

Lighthouse CI 設定の主なフィールド：

{
  "ci": {
    "collect": {
      "url": ["https://example.com", "https://example.com/about"],
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:accessibility": ["error", {"minScore": 0.9}]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

セクション	目的	エージェントでの用途
ci.collect.url	監査する URL	CI スキャンの対象範囲
ci.collect.numberOfRuns	各 URL の実行回数	信頼性の指標
ci.assert.assertions	スコア予算としきい値	回帰の検出
ci.upload.target	レポートの保存先	レポートの取得

Lighthouse のアクセシビリティ結果の解析

アクセシビリティスコア

Lighthouse は、個々の監査結果に基づいて、重み付けされた 0～100 のアクセシビリティスコアを算出します。

スコア範囲	評価	解釈
90～100	A	アクセシビリティは良好です
70～89	B～C	対処すべき問題があります
50～69	D	重大な問題があります
0～49	F	アクセシビリティに重大な問題があります

個々の監査結果

Lighthouse の各アクセシビリティ監査は、axe-core のルールに対応しています。

監査 ID	axe-core ルール	WCAG 基準	重み
image-alt	image-alt	1.1.1	10
color-contrast	color-contrast	1.4.3	7
label	label	1.3.1	7
button-name	button-name	4.1.2	7
link-name	link-name	2.4.4	7
html-has-lang	html-has-lang	3.1.1	7
document-title	document-title	2.4.2	7
heading-order	heading-order	1.3.1	3
meta-viewport	meta-viewport	1.4.4	10
bypass	bypass	2.4.1	7
tabindex	tabindex	2.4.3	7
aria-allowed-attr	aria-allowed-attr	4.1.2	10
aria-hidden-body	aria-hidden-body	4.1.2	10
aria-required-attr	aria-required-attr	4.1.2	10
aria-roles	aria-roles	4.1.2	7
aria-valid-attr-value	aria-valid-attr-value	4.1.2	7
aria-valid-attr	aria-valid-attr	4.1.2	10

重大度のマッピング

Lighthouse は影響度レベルではなく重みを使用します。重みと監査の合否に基づいて、エージェントの重大度モデルにマッピングします。

Lighthouse の重み	監査ステータス	エージェントの重大度
10	Fail	Critical
7	Fail	Serious
3	Fail	Moderate
1	Fail	Minor
任意	Pass	N/A（報告対象外）

ローカルスキャンとの相関

Lighthouse と axe-core の対応付け

Lighthouse は内部で axe-core を使用しているため、簡単に対応付けできます。

1. 監査／ルール ID で照合： Lighthouse の監査 ID は axe-core のルール ID に直接対応します
2. URL で照合： Lighthouse の設定にあるスキャン対象 URL とローカルのスキャン対象を比較します
3. 信頼度を高める： Lighthouse CI とローカルの axe-core スキャンの両方で確認された検出結果には、high の信頼度が付与されます

ソースの比較

シナリオ	解釈	対応
Lighthouse とローカルスキャンの両方で検出	信頼度が高い	信頼度が高いと報告し、重大度の重みをすべて適用します
Lighthouse のみで検出	環境固有	信頼度が中程度と報告し、「CI のみで検出」と記載します
ローカルスキャンのみで検出	Lighthouse の対象範囲外	信頼度が中程度と報告し、「ローカルのみで検出」と記載します
Lighthouse のスコアが低下	新たなアクセシビリティの問題が発生	リグレッションとしてフラグを付け、レポートで優先します

スコアのリグレッション検出

実行ごとの Lighthouse アクセシビリティスコアを追跡して、リグレッションを検出します。

スコアの比較

{
  "url": "https://example.com",
  "previousScore": 95,
  "currentScore": 87,
  "delta": -8,
  "status": "regressed",
  "newFailures": ["color-contrast", "image-alt"],
  "newPasses": []
}

リグレッションのしきい値

差分	重大度	対応
スコアが 10 ポイント以上低下	重大	直ちに対応します。複数の違反が新たに発生している可能性があります
スコアが 5～9 ポイント低下	深刻	新たな違反が発生しています。マージ前に確認します
スコアが 1～4 ポイント低下	中程度	軽微なリグレッションです。フォローアップ対象として記録します
スコアに変化なし、または向上	該当なし	リグレッションは検出されませんでした

構造化出力形式

lighthouse-bridge が Lighthouse データを正規化すると、次の形式で検出結果が生成されます。

{
  "source": "lighthouse-ci",
  "ruleId": "color-contrast",
  "wcagCriterion": "1.4.3",
  "wcagLevel": "AA",
  "severity": "serious",
  "confidence": "high",
  "url": "https://example.com/login",
  "element": "button.submit-btn",
  "description": "Element has insufficient color contrast ratio",
  "lighthouseWeight": 7,
  "lighthouseScore": {
    "overall": 87,
    "previousOverall": 95,
    "delta": -8,
    "status": "regressed"
  }
}

GitHub Actions との統合

treosh/lighthouse-ci-action

最も一般的に使用されている Lighthouse CI の GitHub Action です。

- name: Run Lighthouse CI
  uses: treosh/lighthouse-ci-action@v12
  with:
    urls: |
      https://example.com
      https://example.com/about
    uploadArtifacts: true
    configPath: ./lighthouserc.json

Action の入力

入力	必須	説明
urls	はい（または設定ファイルで指定）	監査対象 URL を改行区切りで指定します
configPath	いいえ	Lighthouse CI の設定ファイルへのパス
uploadArtifacts	いいえ	HTML レポートをワークフローのアーティファクトとしてアップロードします
temporaryPublicStorage	いいえ	共有用に一時的なパブリックストレージへアップロードします
runs	いいえ	URL ごとの実行回数（デフォルト：1）
budgetPath	いいえ	Lighthouse の予算 JSON ファイルへのパス

アーティファクトからの結果の抽出

Lighthouse CI は結果をワークフローのアーティファクトとしてアップロードします。スコアを取得するには、次の手順を実行します。

1. ワークフローの実行からアーティファクトをダウンロードします
2. JSON レポートファイルを解析します
3. 総合スコアとして categories.accessibility.score を抽出します
4. 違反として個別の audits.{audit-id} の結果を抽出します