ego-webqa

ego-webqa

AI 生成のウェブページ、H5 デモ、PWA 向けの、決定論的で簡易的なデリバリー QA です。

URL を指定すると、デフォルトで実際の Chromium ブラウザーでページを開き、 ゼロ設定の狭幅モバイルマトリックスをチェックし、メインの CTA を安全に検証して、 スクリーンショットと機械可読なエビデンスを残します。Firefox と Playwright WebKit は 一度に 1 つのエンジンを選択して利用できます。デフォルトの 8 種類の バリエーションは、次の組み合わせです。

• 360px と 390px の幅；
• 1.0x と 1.5x のテキスト拡大率；
• 0px と 34px のシミュレーションされた下部セーフエリア。

30 秒で結果を確認

まず完了済みの実行結果を確認したい場合は、 実行前後のライブエビデンスボードを開いてください。

python -m pip install ego-webqa
ego-webqa setup
ego-webqa https://your-preview.example --out .qa/first

setup は最初に選択したブラウザーを確認します。すでに起動できる場合、 何もダウンロードせずにセットアップを終了します。そうでない場合は、 現在有効な ego-webqa Python インタープリターを使って、固定された Playwright ヘッドレスシェルをインストールし、実際にヘッドレス起動できることを検証します。 初回の Chromium セットアップでは、監査はヘッドレスでのみ実行されるため、 フルのヘッド付きブラウザーのビルドは避けます。通常の doctor コマンドと監査 コマンドが、暗黙にブラウザーをダウンロードすることはありません。監査コマンドは、 合格または警告の場合は 0、デリバリーを妨げる不具合がある場合は 1、 監査またはブラウザーの失敗の場合は 2 で終了します。各実行では、スクリーンショットと 構造化されたエビデンスが残されます。

.qa/first/
├── agent_summary.json   # one aggregated, repair-ready item per root cause
├── feedback_bundle.json # privacy-safe summary for external issue reports
├── report.json
├── junit.xml
├── report.sarif
└── screenshots/

実際の dogfood で見つかった問題の例です。

{
  "dimension_id": "text_scale_layout_break",
  "selector": "body > div:nth-of-type(2) > div:nth-of-type(2) > a",
  "text_snippet": "我也要创建 →",
  "problem": "page is 9px wider than the viewport at 1.5x text scale",
  "trigger": "mobile-360-150-safe0 (360x800); mobile-360-150-safe34 (360x800)",
  "severity": "block"
}

レポートでは、何が壊れたか、どこで発生したか、影響を受けたビューポートの組み合わせを 説明し、失敗を再現するためのコマンドをエージェントに提示します。

実際のページで判明したこと

v0.8.2 の dogfood テストでは、Ego が所有する本番ページまたは正式な生成ページを 合計 20 件監査し、実行時エラーはありませんでした。ネットワークの影響を受ける パフォーマンス上の観察結果を、決定論的なデリバリー上の検出結果と分けたところ、 10 ページには問題がなく、10 ページには対応可能な構造上の検出事項がありました。 安定して再現する失敗には、テキスト拡大によるレイアウト崩れが 6 件、下部セーフエリアへの 侵入が 4 件、テキスト切り詰めの根本原因が 5 件、ターゲットサイズ不足のグループが 4 件、 サービスワーカーの読み込みに失敗する生成ページが 1 件ありました。このコーパスには、 安定して再現する、既知のブロッキング誤検出はありません。これは小規模で公開された コーパスであり、市場全体の精度を主張するものではありません。エビデンス全体、混在する プロファイルの生の件数、制約については、 docs/real-world-dogfood-2026-10-31-v0.8.2.mdを 参照してください。

レイアウトの失敗では、オーバーフローを発生させている、クリップされていない最深部の 要素を特定するため、エージェントは html ではなく、具体的な修正対象セレクターを 受け取れます。

生成されたページの根本原因を 3 件からブロッキング不具合 0 件に減らした事例については、 用語修正のケーススタディを ご覧ください。ご自身のページで同じサイクルを試す場合は、 初回 15 分トライアルの手順に従ってください。 現場フィードバックの手順では、実際の事例を分類し、 クリーンなコントロールまたはベンチマーク用フィクスチャに変換する方法を定めています。

理由

生成されたページは、ユニットテストに合格していても、スマートフォンの画面幅を超えるコンテンツ、見えないボタン、壊れた画像、コンソールエラー、何も起こらない行動喚起、ユーザーがタップしようとしている間にページがずれる、といった明らかな配信上の不具合を含んだまま公開されることがあります。

ego-webqa は、こうした問題を再現性のあるチェックに変えます。ビジュアルリグレッションサービスではなく、テストの作成や承認済みスクリーンショットの保存も必要ありません。

インストール

公開済みのパッケージを PyPI からインストールします。

python -m pip install ego-webqa
ego-webqa setup

リリース前に現在のチェックアウトをインストールするには、次のようにします。

git clone https://github.com/ROY32172310/qa.git
cd qa
python -m pip install .
ego-webqa setup

開発時は、コミット済みのロックファイルを使用します。

uv lock --check
uv sync --locked --all-extras
uv run --locked ego-webqa setup

uv を使わない場合も、python -m pip install -e '.[dev]' は引き続き使用できます。

uv が利用可能で、Python パッケージを永続的にインストールしたくない場合は、バージョンを固定した分離環境 uvx を通じて同じコマンドを実行できます。

uvx --from ego-webqa==0.8.2 ego-webqa setup
uvx --from ego-webqa==0.8.2 ego-webqa https://your-preview.example

Playwright のバージョンはパッケージによって固定されており、ブラウザーのバイナリは Playwright の共有キャッシュに保存されます。そのため、一時的な uvx 環境と、その後の MCP の起動で同じブラウザーリビジョンが再利用されます。

doctor で Linux のシステムライブラリが不足していると報告された場合は、セットアップでインストールしてください。

ego-webqa setup --with-deps

セットアップは、意図的に独立した明示的なコマンドになっています。wheel のインストールはオフラインでも安全に行える一方、ブラウザーのダウンロードやオペレーティングシステムの変更は、ユーザーが確認でき、再試行可能な操作です。setup は冪等で、実際の起動チェックに合格するブラウザーがすでにあれば再利用します。インタープリターに紐づく正確なコマンドを確認するには setup --dry-run を、破損したブラウザーリビジョンを再インストールするには --force を使用してください。

より低レベルの修復や、インストールコマンドを明示的に実行するには、次のようにします。

ego-webqa install-browser
ego-webqa doctor

Chromium のインストールは、デフォルトでヘッドレスのみです。同じマシン上の別のツールで完全なヘッド付き Chromium ビルドが必要な場合は、明示的にオプトインしてください。

ego-webqa setup --full-chromium

Chromium をダウンロードする代わりに、システムの Chrome を使用します。

ego-webqa https://example.com --browser-channel chrome

Firefox と WebKit

必要な追加エンジンだけをインストールし、その後、監査全体で使用するエンジンを選択します。

ego-webqa setup --browser-engine firefox
ego-webqa https://example.com --browser-engine firefox

ego-webqa setup --browser-engine webkit
ego-webqa https://example.com --browser-engine webkit

デフォルトは引き続き Chromium です。各監査で実行するエンジンは 1 つです。これにより、ブラウザーのコストがひそかに増えたり、エンジン間の同等性をうたったりすることはありません。webkit オプションでは Playwright の WebKit ビルドが使用され、Safari エンジンに関する有用な証拠が得られますが、実際の iPhone、iPad、macOS Safari での実行ではありません。配信の判断に実機でのテストが必要な場合は、実機テストを行ってください。

使用方法

ego-webqa https://example.com
ego-webqa --dir ./dist --file index.html
ego-webqa https://example.com --preset quick
ego-webqa http://127.0.0.1:8000 --viewports 390x844:[email protected]~34,1280x800:desktop
ego-webqa https://example.com --browser-engine firefox
ego-webqa https://example.com --profile performance \
  --ready-selector "#app-ready" --wait-for-network-idle
ego-webqa https://example.com --smoke-success-selector "#thank-you"
ego-webqa https://example.com --smoke-scope all --smoke-require-assertion \
  --smoke-success-selector "#thank-you"
ego-webqa --dir examples/demo --config examples/webqa-demo-flow.json
ego-webqa https://example.com --profile accessibility
ego-webqa https://example.com --profile performance
ego-webqa https://example.com --profile full

終了コード：

• 0：合格、または警告のみ
• 1：ブロッキングエラーが1件以上あります
• 2：呼び出しが無効、またはブラウザー／ランタイムでエラーが発生しました

--viewports は WIDTHxHEIGHT[:NAME][@TEXT_SCALE][~SAFE_BOTTOM_PX] を受け付けます。 明示的に指定したビューポートは、デフォルトのマトリックスを置き換えます。テキストスケールは1.0～2.0、シミュレートする下部セーフエリアは0～100pxの範囲で指定してください。

--preset quick は、エージェントのループを高速化するため、ペアごとのバランスを考慮した4つのモバイルバリアントを選択します。各幅で両方のテキストスケールと両方のセーフエリア状態を網羅し、スケールとセーフエリアの組み合わせは幅ごとに交互になります。--preset full は、デフォルトの8バリアントのマトリックスを明示的に選択します。プリセットは --viewports と併用できません。

実行ごとに自己完結型のエビデンスが出力されます。JSON 内のスクリーンショット参照はレポートディレクトリからの相対パスです。そのため、エージェントやCIはパスを書き換えずに、アーティファクトディレクトリ全体を移動できます。

webqa-report/
├── report.json
├── agent_summary.json
├── feedback_bundle.json
├── junit.xml
├── report.sarif
└── screenshots/

レポートに一切の問題がないことを求めるCIゲートには、--fail-on-warn を追加します。

agent_summary.json は、エージェント向けに情報を簡潔にまとめたビューです。繰り返し発生する指摘は、登録済みのディメンションごとに集約されます。そのため、複数のビューポートにまたがる同じ根本原因は、影響を受けるトリガーと再現可能なコマンドを含む、1つの修正項目として出力されます。MCP の呼び出し元には、同じ概要が構造化コンテンツと短いテキスト結果の両方で返されます。

feedback_bundle.json は、外部フィードバック向けのビューです。デフォルトでは、ディメンション ID、件数、サニタイズ済みのビューポート形状、ブラウザーエンジン、ターゲット種別が含まれます。一方、ターゲット URL、ローカルパス、カスタムビューポート名、セレクター、ページテキスト、メッセージ、生のエビデンス、スクリーンショット、設定内容は含まれません。共有する前に内容を確認してください。非公開の問題に意図的にコンテキストを追加するには、次のようにします。

ego-webqa feedback --report webqa-report/report.json
ego-webqa feedback --report webqa-report/report.json \
  --include-target --include-selectors --include-messages \
  --out webqa-report/feedback-with-context.json

最初のコマンドは、デフォルトのバンドルを再生成し、レポートの隣に保存します。2つ目のコマンドは明示的なオプトインであり、ページの機密データが含まれる場合があります。

ベースラインとリグレッションゲート

スクリーンショットを管理せずに、実行結果を既知の正常なレポートと比較できます。安定したフィンガープリントは、登録済みのディメンションと、そのセレクターまたは根本原因を組み合わせます。

ego-webqa https://your-preview.example \
  --out .qa/current \
  --baseline-report .qa/known-good/report.json \
  --gate new

ego-webqa delta \
  --baseline .qa/known-good/report.json \
  --current .qa/current/report.json

実行すると、delta.json に new、persistent、changed、resolved の各根本原因が記録されます。--gate new は、ブロッキングとなる根本原因が新たに発生した場合、ブロッキングに変化した場合、ブロッキングの発生件数が増えた場合、または影響を受けるビューポートが追加された場合にのみ失敗します。未解決の既存ブロッカーは引き続き表示されますが、変更のないビルドを再び失敗させることはありません。新規または変更された警告もゲートの対象にするには、--fail-on-warn を追加します。

両方のレポートで、ターゲットソース、プロファイル、ビューポートマトリックス、ブラウザーエンジン、ブラウザーチャネルを同じにする必要があります。異なるターゲットや設定を意図的に比較する場合は、--allow-target-change および／または --allow-configuration-change が必要です。これは決定論的な指摘の差分であり、ビジュアルリグレッションのベースラインではありません。

各修正項目では、互換性のために最初のエビデンスオブジェクトを保持し、すべてのビューポートをまたぐエビデンスを evidence_by_viewport マップに記録します。ネットワーク障害には、リソース種別、フレーム URL、同一オリジンかどうか、リダイレクト元、HTTP ステータスまたはブラウザーエラー、発生件数を含む failure_details も記録されます。報告されるすべての URL から、クエリ文字列と認証情報が削除されます。

チェック項目

ブロッキングエラー：

• ページの水平方向のはみ出し
• テキストを拡大したときのレイアウト崩れ
• 画面下部のコントロールがデバイスのセーフエリアに侵入する
• JavaScript ページエラーおよび console.error
• リソースの読み込み失敗および HTTP エラー
• ほぼ空白のページ
• 10px 未満の読みにくいテキスト
• 表示されている画像の破損
• canvas／画像／動画のアスペクト比の歪み
• 機能しない主要 CTA
• 設定されたスモークフローのターゲットまたは操作後のアサーションの失敗
• 予期しない深刻なレイアウトシフト

警告：

• DOM は描画されたものの、load イベントが設定された期限を超過
• 44px 未満の小さなタップターゲット
• 12px 未満の補助テキスト
• 固定オーバーレイが大きすぎる
• 初回コンテンツ描画が遅い
• 中程度のレイアウトシフト
• 初回読み込み時のバイト数またはリクエスト数が過剰

ブラウザープローブは事実を報告します。すべてのしきい値と合否判定は src/ego_webqa/config.py にあります。 アスペクト比チェックでは、デフォルトで 48px の aspect_min_rendered_px 以上の サイズで描画されたメディアのみを評価し、小さなアイコンによる ピクセル丸めの誤差を回避します。

ディメンション

問題コードは、src/ego_webqa/dimensions.py にある バージョン管理された限定的なレジストリに属します。レポートは 未登録のコードを拒否し、各エージェントの概要項目にはディメンション ID、 バージョン、検出器、デフォルトの重大度が含まれます。ドキュメントや連携機能は、 文章を解析せずに同じ信頼できる情報源を参照できます：

ego-webqa --list-dimensions

プロファイル

baseline はデフォルトのデリバリープロファイルです。ページが描画され、 応答し、ビューポートに収まり、主要な操作が機能するかをチェックします。 デリバリーゲートにネットワーク依存の観測項目を意図的に含めていません。 初回描画、load イベントの期限、ネットワークアイドルタイムアウト、 転送量／リクエスト数の予算は、baseline では問題として報告されません。

performance では、すべてのベースラインチェックに加えて、これら4つの ネットワーク依存の観測項目もチェックします。監査を制御されたネットワークで 実行する場合や、呼び出し元が観測結果に基づくパフォーマンスゲートを明示的に 求める場合に使用してください。

accessibility では、すべてのベースラインチェックに加えて、次の決定的な チェックを実行します：

• ドキュメントの言語またはページタイトルの欠落
• アクセシブルな名前のないコントロール
• alt 属性のない表示画像
• aria-hidden コンテナー内のインタラクティブなコンテンツ
• ID の重複および見出しレベルの飛び越し
• 自然なフォーカス順序を上書きする正の tabindex 値

このプロファイルでは、一般的な機械検出可能な不具合を検出します。WCAG 適合性監査ではなく、キーボードや支援技術を使ったテストに代わるものでも ありません。

full では、ベースライン、パフォーマンス、アクセシビリティの各チェックを すべて有効にします。生の時間計測値は、どのプロファイルでも report.json に 保持されます。選択したプロファイルによって、問題として報告される可能性のある 登録済みディメンションが決まります。

設定

ego-webqa https://example.com --config examples/webqa.json

{
  "profile": "full",
  "viewport_preset": "full",
  "min_tap_target_px": 44,
  "min_font_px": 12,
  "ready_selector": "#app-ready",
  "wait_for_network_idle": true,
  "smoke_mode": "safe",
  "smoke_scope": "all",
  "smoke_settle_ms": 800,
  "smoke_require_assertion": true,
  "smoke_success_selector": "#thank-you",
  "smoke_success_url_pattern": "/complete$",
  "ignore_selectors": [".third-party-chat-widget"],
  "ignore_console_patterns": ["third-party-widget"],
  "ignore_request_patterns": ["/analytics/"]
}

最初のゲートで4つのバリアントを使うには "viewport_preset": "quick" を指定するか、 プロジェクト固有のマトリックスを使うには、代わりに明示的な "viewports" リストを 指定してください。プリセットと明示的なリストは併用できません。

主要な操作のテキストがデフォルトの CTA 用語に一致しない場合は、 --smoke-selector "#checkout" を使用してください。安全なスモークテストでは HTTP リクエストを中止し、初回読み込み後に分離されたブラウザーコンテキストを オフラインに切り替えます。実際の副作用を意図している場合に限り --smoke-mode live を使用してください。DOM のみのクリックも望ましくない場合は --no-smoke を使用してください。

smoke_success_selector と smoke_success_url_pattern を設定すると、 「何かが変化した」という一般的なヒューリスティックではなく、明示的なクリック後の 条件を使用できます。両方を設定した場合、どちらも未一致から一致に変化する必要が あります。

すべてのビューポートで CTA を個別に動作させるには、smoke_scope に all を 設定してください。曖昧な DOM の変化を成功として扱わないデリバリーゲートでは、 smoke_require_assertion を使用してください。

有界スモークフロー

クライアント側の短いパスでは、smoke_flow を使用して、決定論的なアクションの順序付きシーケンスを記述できます。以下の限定されたセットから、最大 8 ステップを指定できます。

• click：セレクターをクリックします。
• fill：セレクターに値を入力します。値はレポートでは伏せられます。
• press：セレクター上でキーを押します。
• expect_visible：セレクターが表示されることを要求します。
• expect_url：現在の URL が正規表現に一致することを要求します。
• expect_text：表示されている要素のレンダリング済みテキスト、またはフォームコントロールの現在値が、大文字と小文字を区別しない正規表現に一致することを要求します。

{
  "smoke_mode": "safe",
  "smoke_flow": [
    {"action": "fill", "selector": "#email", "value": "[email protected]"},
    {"action": "click", "selector": "#continue"},
    {"action": "expect_visible", "selector": "#success"},
    {"action": "expect_url", "pattern": "#complete$"},
    {"action": "expect_text", "selector": "#status", "pattern": "^Ready$"}
  ]
}

フローには click、fill、press のいずれかのアクションを含め、その後に少なくとも 1 つの expect_visible、expect_url、expect_text のアサーションを含める必要があります。フローは、単一の CTA セレクター／アサーションフィールドと組み合わせることはできません。デフォルトの safe モードでは、最初のページ読み込み後の HTTP 通信がブロックされるため、smoke_mode を明示的に live に変更しない限り、フローは決定論的なクライアント側の動作に限定されます。任意の JavaScript やユーザー定義の検出器は受け付けません。

expect_text は Playwright を通じて input、textarea、select の値を読み取ります。それ以外の要素では、表示されている要素のレンダリング済みテキストを使用します。非表示の子孫要素は、配信されたコンテンツとして扱われません。レポートにはパターン、ソースの種類、観測した長さが保持されますが、観測したテキストが証拠にコピーされることはありません。これにより、ページに入力された値を漏らすことなく、テキストアサーションの決定性を保てます。

フローが失敗すると、report.json には完了した各ステップ、失敗したステップ、およびそのエラーが含まれます。Agent の要約では、一般的なボタンの不具合ではなく、該当するアクションが正確に示されます。

プロジェクトでは、1 つの設定に複数の限定フローを保持し、名前で 1 つを選択できます。

{
  "smoke_flow_name": "checkout",
  "smoke_flows": {
    "login": [
      {"action": "fill", "selector": "#email", "value": "[email protected]"},
      {"action": "click", "selector": "#continue"},
      {"action": "expect_visible", "selector": "#welcome"}
    ],
    "checkout": [
      {"action": "click", "selector": "#buy"},
      {"action": "expect_text", "selector": "#status", "pattern": "^paid$"}
    ]
  }
}

フロー名は [A-Za-z0-9][A-Za-z0-9._-]{0,63} に一致する限定識別子で、定義は最大 16 個まで受け付けられます。すべての定義が検証されますが、実行されるのは選択されたフローだけです。smoke_flows と単一のインライン smoke_flow は相互に排他的です。また、名前付きフローと、単一ステップの smoke_selector／成功アサーションも相互に排他的です。これは、すべての名前付きフローに独自のインタラクションとアサーションを含める必要があるためです。設定済みのデフォルトは --smoke-flow-name checkout で上書きできます。レポートには選択した名前が保持され、入力値はこれまでどおり伏せられます。

ロードイベント後に表示される SPA コンテンツには ready_selector を使用してください。既知のサードパーティー製コンソールおよびリクエストのノイズは、DOM ベースの検出結果を隠すことなく、正規表現パターンで除外できます。無視されたレスポンスは、リクエスト数と転送バイト数の予算の両方から除外されます。レポートには、準備完了コンテンツ、フォント、および制限付きネットワークアイドルに到達したかどうかが記録されます。

認証が必要なプレビュー

HTTP Basic 認証、リクエストヘッダー、またはサインイン済みのブラウザーセッションで保護されたプレビューは、JSON 設定または環境変数を通じて利用できます。

export EGO_WEBQA_HTTP_USERNAME=preview-user
export EGO_WEBQA_HTTP_PASSWORD=preview-password
export EGO_WEBQA_EXTRA_HTTP_HEADERS='{"X-Preview-Key":"agent-key"}'
ego-webqa "$PREVIEW_URL" --storage-state ./auth/storage-state.json

認証情報とヘッダー値は、JSON レポートでは伏せられます。環境変数を通じて渡すことで、CLI プロセスの引数一覧に表示されることも避けられます。

プラットフォームとマルチエージェントでの利用

監査エンジンは、Python 3.10 以降を使用して Linux、macOS、Windows で動作します。 CI では、3 つすべてのオペレーティングシステムで同じテストスイートを実行します。

各 audit() または CLI の呼び出しは、それぞれ独自のブラウザーライフサイクル、ブラウザーコンテキスト、 静的ローカルサーバー、出力ディレクトリを管理します。共有される可変の監査状態はないため、 各エージェントが一意の --out ディレクトリを指定すれば、複数のエージェントを並行して実行できます。

ego-webqa "$PREVIEW_URL" --out "webqa/$AGENT_ID" --json \
  --smoke-scope all --smoke-require-assertion \
  --smoke-success-selector "#thank-you"

--json は、report.json に書き込まれるものと同じ安定したペイロードを出力します。 互換性は schema_version によって管理されます。JUnit と SARIF は、 同じメモリ内の課題リストから生成されます。エージェントは終了コード 0 を合格／警告、 1 をブロックする検出結果、2 を呼び出しまたはブラウザーの失敗として扱ってください。

8 種類の公開 JSON ペイロードには、同梱された Draft 2020-12 スキーマがあります。 ego-webqa --print-schema report でスキーマを出力できます。名称と互換性ポリシーについては、 docs/json-contracts.md を参照してください。

1 回の監査では、最大 3 つのビューポートを分離されたブラウザーで並行してレンダリングします。 これにより、ビューポート間で Cookie、ネットワーク状態、スクリーンショット、 可変の証拠を共有せずに、応答の遅いサイトによる実行時間を抑えます。

MCP サーバー

AI コーディングエージェント内でゲートを直接利用できるようにします。

python -m pip install ego-webqa
ego-webqa setup
ego-webqa mcp

ego-webqa-mcp は互換性エイリアスとして引き続き利用できます。MCP クライアントは、 どちらのコマンドも stdio 経由で起動できます。レジストリ互換のワンショット形式は uvx [email protected] mcp です。このサーバーは、構造化された成功結果とブロックエラー結果を返す 1 つのツール audit_web_page を公開します。

{
  "mcpServers": {
    "ego-webqa": {
      "command": "uvx",
      "args": ["[email protected]", "mcp"]
    }
  }
}

ツールに渡す引数の例は次のとおりです。

{
  "url": "http://127.0.0.1:5173",
  "out_dir": ".qa/agent-a",
  "config": "/workspace/webqa-flow.json",
  "profile": "accessibility",
  "browser_engine": "webkit",
  "viewport_preset": "quick",
  "smoke_flow_name": "checkout",
  "smoke_scope": "all"
}

config パスは、制限付きの smoke_flow シーケンス、認証済みリクエスト、 無視ポリシーなど、ツールを呼び出すたびに繰り返し指定する必要のない設定を行うための MCP 統合ポイントです。

レポートのステータスが fail の場合、MCP の結果はエラーとしてマークされますが、 レポート全体は構造化コンテンツとして引き続き利用できます。認証用の環境変数は、 ツールの引数として渡されるのではなく、サーバープロセスによって読み込まれます。 このアダプターは意図的に、デリバリーのユーザビリティを検証するゲートにとどめています。 セキュリティスキャナー、WCAG 認証ツール、ビジュアルリグレッションシステムではありません。

管理された値のオーバーライド

プロジェクトでは、ディメンションを無効にしたり、任意のアサーションを追加したりせずに、 登録済みディメンションの値を一時的に調整できます。オーバーライドにはすべて所有者、 理由、有効期限が必要です。また、適用される block／warn の重大度を変更し、 そのディメンションで宣言された、安全にオーバーライド可能な閾値のみを使用できます。

{
  "overrides": [
    {
      "dimension_id": "tiny_fonts",
      "reason": "Typography migration tracked in DS-142",
      "owner": "design-system",
      "expires": "2026-11-30",
      "severity": "warn",
      "parameters": {
        "min_font_px": 13
      }
    }
  ]
}

有効期限の判定には UTC の監査日が使われます。オーバーライドは expires の日付まで有効で、 翌日にはレジストリのデフォルト値に自動的に戻ります。 不明なディメンション、不明または安全でないパラメーター、重複するディメンション項目、 共有閾値に対する競合する値は拒否されます。

report.json では、影響を受ける各課題にオーバーライドが記録され、 有効および期限切れの宣言と、適用されるパラメーターを含む governance ブロックが追加されます。 agent_summary.json には同じソースメタデータが含まれ、 overridden_dimensions、downgraded_blocks、expired_overrides が報告されます。 JUnit と SARIF には、適用後の重大度が使用されます。期限切れのオーバーライドは監査用に表示されますが、 検出やステータスには影響しません。examples/webqa-governed.json を参照してください。

DeepSeek Harness では、別個の宣言型 dsh-ego-webqa バンドルを通じて、同じ MCP ツールをインストールできます。 2 つ目の QA 実装を追加するのではなく、DSH のネイティブ MCP クライアントを再利用します。 統合の範囲と受け入れ基準については、docs/dsh-integration.md を参照してください。

GitHub Actions

このリポジトリは複合型の GitHub Action としても利用できます。この Action は Action の ref からパッケージをインストールし、選択したブラウザーエンジン（デフォルトは Chromium）をインストールして監査を実行します。監査が失敗した場合でもレポートをアップロードし、プライバシーに配慮した簡潔な根本原因の表をジョブのサマリーに書き込みます。

jobs:
  delivery-qa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ROY32172310/[email protected]
        with:
          url: ${{ vars.PREVIEW_URL }}
          browser-engine: webkit
          profile: accessibility
          viewport-preset: quick
          smoke-flow-name: checkout
          fail-on-warn: "true"
          smoke-scope: all
          baseline-report: .qa/known-good/report.json
          delta-gate: new
          http-username: ${{ secrets.PREVIEW_USERNAME }}
          http-password: ${{ secrets.PREVIEW_PASSWORD }}
          extra-http-headers: ${{ secrets.PREVIEW_HEADERS_JSON }}
          artifact-name: webqa-${{ github.run_id }}

このリポジトリをローカルでチェックアウトした場合は、チェックアウト後に uses: ./ を使用してください。Action の safe スモークモードがデフォルトです。クリックによって実際の副作用が意図的に発生してもよい場合に限り、smoke-mode: live を設定してください。すべての入力については、examples/github-action.yml と action.yml を参照してください。@v0.8.2 タグは、同じコミットが完全なクロスプラットフォーム CI マトリックスに合格した後にのみ作成されます。

Python API

from ego_webqa import Settings, SmokeStep, audit

settings = Settings(
    smoke_flow=(
        SmokeStep("click", selector="#continue"),
        SmokeStep("expect_visible", selector="#success"),
    )
)
report = audit("https://example.com", settings=settings, output_dir="qa")
print(report.status)

対象範囲と独立性

これは、明らかな配信上の失敗を検出するための、決定論的な簡易ゲートです。範囲を限定したスモークフローで、設定された単一の短いクライアント側パスが、宣言された表示状態、テキスト／値、または URL に到達することを確認できます。ただし、ビジネス上の正しさ、サポート対象のすべてのブラウザーでの一致、ページの安全性を証明するものではありません。

固定のレポート対象範囲：

本レポートは、複数端末におけるレイアウトと基本的なユーザー体験の決定論的な簡易チェックのみを対象とします。ビジネス上の主要経路、クロスブラウザー互換性、安全性とコンプライアンスは別途検証が必要です。

このリポジトリは、ego プロジェクト内で当初検証された汎用の配信チェックを独立した形で抽出したものです。ego_protocol、ego_uri、ego の共有、デプロイ、ミニアプリ、製品シェルのセマンティクスには依存しません。製品固有のチェックはコアではなく、プラグインに実装してください。

ベンチマークと信頼性

このリポジトリでは、管理されたローカル回帰ベンチマークと、実環境でのパブリックネットワーク観測を分けています。

• benchmarks/ は、狭幅、モバイル、タブレット、デスクトップの各バリエーションで、独立した合成ケースを 128 件実行します。これは、シリアル実行時の Chromium のレイテンシー基準であり、登録済みの 38 の全次元を対象とする正確性コーパスです。
• dogfood/ は、固定された実ページのサンプルを実行し、url と local の結果を分けて報告します。ネットワークや対象サイトの挙動はツールの制御外で変化するため、これは観測結果であり、レイテンシーのしきい値ではありません。

正解データはベンチマークのシナリオごとに宣言されます。評価器は、結果が正しいかどうかの判定に検出器のしきい値を読み込みません。

python benchmarks/run.py

評価器は、次元ごとの完全一致、ケース単位の適合率／再現率／F1、ブロッキングの偽陽性率と偽陰性率、次元単位の TP／FP／FN、監査全体のレイテンシーを報告します。機械可読なエビデンスと Markdown サマリーを書き出します。0.7.0 の基準値は、ローカルで Chromium をシリアル実行した場合、完全一致が 128/128、ブロッキングの FP/FN が 0%、P50 が 357ms、P95 が 1147ms、最大値が 3615ms です。 docs/benchmark-2026-10-30-v0.7.0.md。

これらの結果は、Chromium 上の厳選された合成フィクスチャを測定したものであり、実サイトのカバレッジやエンジン間の同等性を示すものではありません。Firefox と WebKit については、クリーンなページと決定論的なオーバーフロー失敗を対象とした、別個の実ブラウザー CI フィクスチャがあります。ベンチマークの価値は、回帰を検出しやすくすることにあります。初回の実行では、標準的な <label> マークアップで実際に発生する accessibility プロファイルのクラッシュと、CTA の根本原因が重複して報告される問題が明らかになりました。どちらも基準値の記録前に修正されました。測定の契約と 2 種類のエビデンスについては、docs/performance-baselines.md を参照してください。

開発

uv sync --locked --all-extras
uv run --locked ego-webqa setup
uv run --locked python scripts/dev.py test
uv run --locked python scripts/dev.py coverage
uv run --locked python scripts/dev.py lint
uv run --locked python scripts/dev.py format-check
uv run --locked python scripts/dev.py typecheck
uv run --locked python scripts/dev.py benchmark
uv run --locked python scripts/dev.py package
uv run --locked python scripts/dev.py check   # lint + format + MyPy + coverage
uv run --locked python scripts/dev.py full    # check + Chromium benchmark

GitHub Actions は Linux、macOS、Windows で、同じ scripts/dev.py エントリーポイントとロックファイルを使用するため、ローカルと CI で依存関係やコマンドに差異が生じるのを防ぎます。カバレッジには、行と分岐のカバレッジが 90% 以上という要件があります。ルールを追加する前に、CONTRIBUTING.md を参照してください。各ルールには、陽性対照と、観測された失敗モードが必要です。

ライセンス

MIT