PlaywrightでAI実装のブラウザ表示を検証する設計
この記事で学べること
- 構造・URL検証と、Playwrightによるブラウザ表示確認の役割の違い
- レイアウト、操作、表示状態のうちPlaywrightで確認したい対象
- 既存の検証フローへ組み込む位置と、人のレビューに残す判断
Playwrightでブラウザ表示の最終確認を自動化する
AIが更新したWeb画面を確認済みにするには、ファイルの構造検査を通した後で、実際の表示と操作も確かめる必要があります。Playwrightはブラウザを自動操作して表示や操作を確認する道具ですが、内容の正確さや公開判断までは担いません。構造検査、ブラウザ確認、人の判断を順に分けると、各確認の責任が明確になります。
この記事では、「構造検査の後にPlaywrightと人の判断をどこへ置くか」という問いに焦点を当て、実行前の前提、作業手順、完了を確かめる方法を扱います。
最後まで読むと、「構造検査の後にPlaywrightと人の判断をどこへ置くか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
Playwrightは最後の表示確認を補完するために使う
このサイトでは、品質確認をすべてブラウザテストに寄せるのではなく、まずMarkdownや設定ファイルを対象にした機械検査で検出できる問題を減らしています。そのうえで、実際にブラウザで表示しないと分からない問題をPlaywrightで補完する、という位置づけにしています。
Playwright Testは、モダンなWebアプリケーション向けのE2Eテストフレームワークです。Chromium、WebKit、Firefoxを対象に、ローカル環境やCI（GitHub Actionsなどでテストや検証を自動実行する仕組み）でテストを実行できます。[1] ただし、このサイトでは現時点でPlaywrightを常設のE2Eテスト基盤として導入しているわけではありません。まずは、既存の検証スクリプトと人間の目視確認の間を埋めるブラウザ確認手段として扱っています。
Playwrightの前に構造・リンク・設定を機械検査する
このサイトの品質確認では、ブラウザを開く前に、リポジトリ上で判定できる項目を先に確認します。
主な確認対象は次のとおりです。
- Markdownの構造
- 参考文献セクションと本文引用番号の対応
- 参考文献URLの形式
- 内部リンクの形式
- 日英記事ペアの構造差分
- ハーネス（AIに渡すルール、作業手順、検証方法をまとめた仕組み）やエージェント設定の整合性
たとえば、npm run review:content は記事本文の引用・参考文献まわりを確認します。npm run review:references:live は外部URLに実際にアクセスして、リンク切れや到達不能を確認します。npm run harness:check は、共有ルールとランタイムアダプター、日英構造差分などをまとめて確認します。
ここで重要なのは、Playwrightに任せる前に、テキストとして判定できるものを先に落とすことです。Markdownの引用番号がずれている、参考文献がリンクになっていない、存在しない npm script を記事で紹介している、といった問題はブラウザを開かなくても検出できます。
Playwrightで表示・操作・レスポンシブ状態を確認する
Playwrightで確認したいのは、ファイルやMarkdownだけでは分からない「表示後の状態」です。
このサイトで確認対象にしやすいのは、次のような項目です。
- トップページ、ブログ記事、docs記事が表示できるか
- 日本語ページと英語ページの内部リンクが期待どおり遷移するか
- モバイル幅でナビゲーションや本文が崩れていないか
- 参考文献リンクがページ上でクリック可能なリンクとして表示されているか
- Starlightのサイドバー、パンくず、見出しリンクが意図どおり表示されるか
- コンソールエラーが出ていないか
これらは、ソースファイルを読んだだけでは判断しにくい項目です。AstroやStarlightのレンダリング、テーマ、生成スクリプト、ホスティング時のURL挙動が重なった結果として、実際の画面に問題が出る場合があります。
Playwright MCPはAIエージェントの確認補助に向いている
Playwrightには、通常のテストコードとして使う方法と、Playwright MCPとしてAIエージェントからブラウザを操作する方法があります。
Playwright MCPは、Playwrightを使ったブラウザ自動化機能をMCPサーバーとして提供します。LLMはアクセシビリティスナップショットを読み取り、要素参照を使ってクリック、入力、確認などを実行できます。[2]
この違いを、このサイトの運用に当てはめると次のようになります。
| 使い方 | 向いている場面 |
|---|---|
| 通常のPlaywrightテスト | 毎回同じ手順で確認したい表示・リンク・回帰テスト |
| Playwright MCP | CodexやClaudeにローカルページを開かせ、画面状態を確認させたい調査 |
| 人間の目視確認 | デザインの違和感、文章の読みやすさ、判断が必要な表示確認 |
私は、まずPlaywright MCPを探索的な確認に使い、繰り返し発生する問題だけを通常のPlaywrightテストや既存スクリプトに昇格させるのが扱いやすいと考えています。
Playwrightは構造検査後の最終表示確認に置く
このサイトでPlaywrightを使うなら、既存の検証フローの最後に置くのが自然です。
先に実行するのは、リポジトリ上で判定できる検証です。
npm run harness:check
npm run review:references:liveその後、ローカルプレビューを起動してブラウザ確認を行います。
npm run devこの状態で、PlaywrightまたはPlaywright MCPから主要ページを開きます。確認対象は、全ページを網羅するよりも、壊れると影響が大きいページから始める方が現実的です。
/ja//en//ja/blog//en/blog/- 新規または更新したブログ記事
- 直近で構造を変更したdocs記事
この順番にすると、軽量な検査で検出できる問題を先に解消し、ブラウザ確認を「表示後にしか分からない問題」に集中できます。
公開判断・内容の正確さ・秘密情報はPlaywrightへ任せない
Playwrightは、画面上に要素が表示されるか、リンクがクリックできるか、コンソールエラーが出ていないかを確認するには有効です。一方で、記事の主張が参考文献によって正しく支えられているかまでは判断できません。
たとえば、参考文献リンクがクリック可能で、HTTPステータスが正常でも、そのページが本文の主張を本当に裏付けているとは限りません。これは、npm run review:content や npm run review:references:live だけでも完結しない部分です。最終的には、人が本文と参考文献の対応を確認する必要があります。
そのため、このサイトでは役割を分けて考えています。
| 確認対象 | 主な担当 |
|---|---|
| Markdown構造、引用番号、参考文献形式 | 検証スクリプト |
| 外部URLの到達性 | npm run review:references:live |
| 表示、リンククリック、モバイル幅、コンソールエラー | PlaywrightまたはPlaywright MCP |
| 主張と参考文献の対応、文章の妥当性 | 人間レビュー |
まとめ：Playwrightは構造検査の後、人の判断の前に置く
このサイトにおけるPlaywrightの役割は、すべての品質確認を置き換えることではありません。構造チェック、URL検証、リポジトリ上の整合性確認で検出できる問題を先に減らし、その後にブラウザでしか確認できない表示・操作・レイアウトの問題を補完するために使います。
特にAI支援で記事や設定を更新する場合、ファイル上の正しさと画面上の正しさは分けて確認する必要があります。Playwrightは、その間を埋める確認手段として有効です。繰り返し確認したい項目は通常のPlaywrightテストへ、探索的に確認したい項目はPlaywright MCPへ、判断が必要な項目は人間レビューへ分担させることで、過剰な自動化に寄せすぎない品質確認ができます。
最初の行動は、重要な画面を1つ選び、表示、操作、スマートフォン幅の3条件を再現することです。内容の正確さ、秘密情報の扱い、公開可否はブラウザ操作だけでは決められないため、人の確認へ残します。
参考文献
- Microsoft, Installation | Playwright, Playwright Docs
- Microsoft, Playwright MCP, Playwright Docs