株式会社ACCESS Advent Calendar 2025

株式会社ACCESS

LLM×Playwright×VS Code でテスト仕様書が自動生成される仕組み

Last updated at 2025-12-27Posted at 2025-12-23

1. はじめに

最近のテスト自動化のトレンドとして、 テストコードの自動生成 や テスト仕様書（テスト計画）の自動生成 が一気に加速しています。

その中でも、Microsoft 製の E2E テストフレームワークである Playwright が提供している
Playwright Test Agent（planner / generator / healer） は、

Web アプリを実際にブラウザで自動探索し
その結果をもとに テスト仕様書（Markdown） を作成し
仕様書から Playwright のテストコード を自動生成します

Playwright Test Agent が どのようなアーキテクチャで動作し、 どのようなプロセスでテスト仕様書を作っているのか」を調査して、最終的には、「同じ考え方で、Appium を使ったモバイルアプリの自動テスト仕様書生成ができそうか？」というところまで見通しを立てることを目標とします。

2. 全体像

アーキテクチャと関係するコンポーネントをざっくり整理します。

2.1 参照するソースコードとドキュメント

Playwright 本体
- https://github.com/microsoft/playwright
Playwright MCP（Model Context Protocol サーバー）
- https://github.com/microsoft/playwright-mcp
Playwright Test Agents 公式ドキュメント
- https://playwright.dev/docs/test-agents
解説ブログ例（日本語）
- Qiita / Zenn / 各社 Tech Blog など

この記事ではこれらをベースに、実際の設定ファイルやソースコードの動き方を追いかけていきます

2.2 「誰と誰がしゃべっているか」を先に整理する

Playwright Test Agent の構成はざっくりと下記のようになっています

コンポーネント

VS Code
- GitHub Copilot Chat / Custom Agent 機能
- .github/chatmodes/*.chatmode.md に定義した カスタムエージェント
LLM（GPT-4/5 や Claude など）
- VS Code からの指示に従って、ツールを呼びながら思考する
MCP サーバー（playwright-mcp）
- LLM からの「ツール呼び出し」を受け取り、Playwright を実行する
Playwright 本体
- 実際にブラウザを起動し、クリックや入力を行う
テスト対象 Web アプリ
- ローカル / リモートなど

処理の流れ

VS Code の Chat エージェントに「この Web アプリのテスト仕様書を作って」と話しかける
エージェントは内部で LLM を呼び出し、.chatmode.md に書かれた方針に従って思考を開始
LLM は Playwright MCP のツール（browser_click など）を呼び出しながら UI を探索
探索結果をもとにテスト観点を整理し、Markdown のテスト仕様書を生成
必要に応じて、仕様書から テストコード（.spec.ts） まで自動生成

3. 環境セットアップとプロジェクト構成

ここでは、VS Code から Playwright Test Agent を使うための最低限のセットアップを見ていきます

3.1 プロジェクト作成

# 適当なディレクトリを作成
mkdir playwright-test
cd playwright-test

3.2 VS Code 向け Playwright Test Agent の初期化

# VS Code と連携するための Agent プロジェクトを初期化
npx playwright init-agents --loop=vscode

実行すると、次のようなファイルが自動生成されます。

.
├── .github
│   └── chatmodes
│       ├── 🎭 planner.chatmode.md
│       ├── 🎭 generator.chatmode.md
│       └── 🎭 healer.chatmode.md
├── .vscode
│   └── mcp.json
├── README.md
└── seed.spec.ts

3.3 生成される各ファイルの役割

.github/chatmodes/*.chatmode.md
- VS Code が認識する カスタムエージェントの定義
- planner.chatmode.md：テスト計画（仕様書）を作るエージェント
- generator.chatmode.md：テストコードを生成するエージェント
- healer.chatmode.md：落ちたテストを直すエージェント
.vscode/mcp.json
- VS Code が MCP サーバー（playwright-mcp）へ接続するための設定
- どの MCP サーバーを使うか、どのツールを公開するか等を定義
seed.spec.ts
- Planner が最初に実行する シードテスト
- ログインや初期ページ遷移など、「テスト開始前に 1 回だけやっておきたい処理」を書く

ここまでで、「VS Code から Planner を呼べる状態」になります。

4.テスト計画エージェントの設計思想

Playwright Test Agent の賢さの多くは、実は Playwright 本体ではなく planner.chatmode.md という 1 つの Markdown ファイルの中に書かれています。

4.1 エージェントの「専門性」をテキストで埋め込む

planner.chatmode.md の中心はエージェントの役割宣言であり、例えば次のようなスキルが書かれています。

Web UI の構造を読み解く
ユーザーフロー（導線）を把握する
バリデーションやエッジケースを見つける
テスト観点を設計する
体系的なテスト計画を Markdown で書く

人間の QA エンジニアが「私はこういうことを得意としています」と名刺に書くように、
LLM に対して 「あなたはこういう専門家として振る舞いなさい」 と教えているイメージです。

これにより、ユーザーが少し曖昧な指示をしても、

「これはテスト計画なので、
　Happy path だけでなく Edge / Error も拾おう」

といった判断が自律的に行われるようになります。

4.2 行動プロセスの具体的な指示

planner.chatmode.md には、行動手順も細かく書かれています。例えば：

planner_setup_page を必ず最初に 1 回だけ呼びなさい
その後、browser_* 系ツールで UI を徹底的に探索しなさい
主要導線とユーザーフローを洗い出しなさい
Happy / Edge / Error を体系的に設計しなさい
仕様書は Markdown で、見出しやステップを明確に書きなさい

などです。

これらの指示は ただの文章 ですが、
LLM にとっては「行動規範（ポリシー）」になっており、
これに従ってツールを呼び、テスト観点を広げていきます。

4.3 サンプル仕様書という「見本」

planner.chatmode.md には、TodoMVC アプリ向けの サンプルテストプランも丸ごと入っています。

アプリ概要
シナリオごとの手順と期待結果
Happy / Edge / Error のバランス

がきれいに書かれており、
LLM にとっては

「これくらいの粒度・表現の仕様書を目指しなさい」

という スタイルのお手本 になっています。

5. Playwright MCP ツール群でブラウザを探索する仕組み

次に、LLM がどのようにブラウザを操作しながら仕様書を書いているのかを見ていきます。

5.1 VS Code 側のローカルファイル系ツール

VS Code には、ローカル環境にアクセスするための MCP ツールが用意されています。例えば：

ツール名	機能概要
`edit/createFile`	新規ファイル作成＋内容書き込み
`edit/createDirectory`	ディレクトリ作成
`search/fileSearch`	ファイル名・パスを glob で検索
`search/textSearch`	ワークスペース全文検索
`search/readFile`	ファイル内容の読み取り

これらは、LLM が

既存テストファイルを読み込んだり
新しい仕様書ファイルを保存したり

するときに使われます。

5.2 Playwright MCP のブラウザ操作系ツール

ブラウザを実際に操作するツールは、Playwright MCP サーバー側で提供されています。代表例：

ツール名	機能概要
`playwright-test/browser_navigate`	任意 URL へナビゲート
`playwright-test/browser_click`	指定要素をクリック
`playwright-test/browser_type`	入力欄にテキストを入力
`playwright-test/browser_hover`	要素へ hover
`playwright-test/browser_file_upload`	ファイルアップロード
`playwright-test/browser_take_screenshot`	スクリーンショット取得
`playwright-test/browser_snapshot`	ページ全体のスナップショット
`playwright-test/browser_wait_for`	要素の出現などを待機
`playwright-test/browser_console_messages`	console.log の収集
`playwright-test/browser_network_requests`	ネットワークリクエストの取得
`playwright-test/browser_close`	ブラウザを閉じる
`playwright-test/planner_setup_page`	Planner 専用の初期化処理（後述）

LLM はこれらのツールを組み合わせて、

画面遷移
入力フォーム操作
コンソールログやネットワークの状態確認
UI 構造の把握

などを行い、その結果から

どんな機能があるのか
どんなエラーになりそうか
どんなテスト観点が必要か

を考えていきます。

6. planner_setup_page が担う「最初の 1 手」

ブラウザ操作ツールの中で、Planner 専用なのは planner_setup_page だけです。

6.1 何をするツールなのか？

一言で言うと：

「テスト設計の前に、ブラウザをちょうどいい状態にして止めておく」ツール

です。

例としては：

指定ユーザーでログインしておく
初期ページに遷移しておく
必要なモーダルを開いておく

といった「最初に 1 回だけやる準備」を自動で実行します。

6.2 入力パラメータ

planner_setup_page は主に次の 2 つを受け取ります。

project?: string
- Playwright のプロジェクト名（chromium / firefox など）
seedFile?: string
- 1 本だけ実行する シードテストファイル（例：tests/seed.spec.ts）

指定しなければ、デフォルトの Seed テストが使われます。

6.3 Seed テスト `seed.spec.ts` に書くべき内容

Seed テストに書くことは 最小限 で構いません。例えば：

import { test, expect } from '@playwright/test';

test('setup environment and login', async ({ page }) => {
  // Website URL
  await page.goto('http://localhost');
});

ここで大事なのは、

アプリに正しくアクセスできること
必要ならログイン・初期化を行うこと
複雑な検証ロジックは書かないこと

です。

planner_setup_page は、この Seed テストを 1 回だけ流し、
ページを「テスト計画を立てるのにちょうど良い状態」で止めてくれます。

7. Playwright Test Planner の正体

ここまでの要素をまとめると、Planner の本質が見えてきます。

7.1 実は「特別な AI アルゴリズム」は入っていない

Playwright 側には、

テストプランニング専用のアルゴリズム
テスト観点を自動列挙する仕組み

のようなものは実装されていません。

Playwright がやっていることは、ざっくり次の 2 つです。

MCP 経由で Playwright を操作するための ツール群を提供
Planner 専用ツールとして planner_setup_page を追加

それ以上の「賢いこと」はしていません。

7.2 賢さの本体はどこにあるか？

賢さの本体は、

LLM（GPT-4/5, Claude など）
VS Code ChatAgent
planner.chatmode.md に書かれた指示

にあります。

LLM は chatmode.md を読み込んで、

自分の役割（テスト計画エージェント）
行動方針（探索 → ユーザーフロー分析 → シナリオ設計）
出力形式（Markdown の仕様書）

を理解し、そのルールに従って MCP ツールを呼び出しながら思考を進めます。

7.3 アーキテクチャ図

シーケンスを確認すると、次のような構造になっています。

VS Code の Chat 画面でユーザーが「この URL のテスト仕様書作って」と入力する
VS Code は planner.chatmode.md をロードして、LLM に「あなたは Planner です」と伝える
LLM は planner_setup_page を呼び、Seed テストを 1 回流してページを初期化
その後、browser_* ツールを使って UI を探索
得られた情報をもとに、Happy/Edge/Error のシナリオを設計し、Markdown の仕様書を生成
VS Code のファイルツールで、仕様書を tests/test_plan_xxx.md として保存

つまり Planner の正体は、

「LLM に Playwright を操らせ、
　planner.chatmode.md で行動指針を定義したもの」

と捉えるのが一番しっくりきます。

8. 実践：planner でテスト仕様書を自動生成してみる

ここからは、実際に Planner を使ってテスト仕様書を作る流れを、ざっくり追ってみます。

8.1 Playwright ランタイムのインストール

まずは Playwright 本体とブラウザをインストールします。

npm init -y
npm install -D @playwright/test
npx playwright install

8.2 シンプルな Seed テストの例

例として、ローカルで動いている PowerPoint 翻訳 Web アプリを対象にする場合：

import { test, expect } from '@playwright/test';

test('setup environment', async ({ page }) => {
  await page.goto('http://www.google.com'); // Your app URL
});

8.3 planner への指示例

VS Code の Copilot Chat で、Planner エージェントを選び、例えば次のように指示します。

http://www.google.com でサービスされているWebアプリの画面を探索し、基本操作のテスト計画を作成してください。
テスト仕様書は Markdown 形式で tests/google-claudesonnet45.md に保存してください。

Planner は内部で：

planner_setup_page を実行してページを初期化
browser_snapshot や browser_click などのツールで UI を探索
結果をもとに、テスト仕様書（例：tests/test_plan_basic_operations.md）を生成

という流れになります。

9. GPT-5 と Claude のそれぞれでテスト仕様書を作成した場合の違い

次のような指示を与えて GPT-5 と Claude Sonnet4.5 のそれぞれにテスト仕様書を作成させて比較評価しました。

http://www.google.com でサービスされているWebアプリの画面を探索し、基本操作のテスト計画を作成してください。
テスト仕様書は Markdown 形式で tests/google.md に保存してください。

9.1. 「全体構成」を見比べて AI の“文章の癖”を掴む

テスト仕様書の全体構成を比較し、AI がどのように全体を整理しているか を確認する

9.1.1. GPT-5 のカテゴリリスト

GPT-5 の仕様書は、機能ごとにカテゴリ A〜N を並べる形式でした。

A. 初期表示 / アクセシビリティ  
B. サジェスト (入力/急上昇/Clear/報告ボタン/キーボード)  
C. 検索実行 (ボタン/Enter/例外入力)  
D. ナビゲーション (Gmail/画像/ログイン/Googleアプリメニュー/戻る)  
E. 多言語 (English 切替/戻し/履歴挙動)  
F. 補助検索UI (音声/画像/AIモード)  
G. 設定/テーマ (設定ボタン/メニュー/ダークモード)  
H. フッター企業情報リンク  
I. エラー/回復 (429/CAPTCHA)  
J. セキュリティ (HTTPS/CSP/XSS無害化)  
K. アクセシビリティ (ARIA/タブ順/コントラスト)  
L. パフォーマンス (/complete/search レイテンシ & 初期ロード)  
M. 互換性 (主要ブラウザ)  
N. レジリエンス (ネットワーク遮断/低速)

特徴

観点が幅広く網羅されている
バランスは良いが、章構造ではなく箇条書き中心の作り

9.1.2. Claude 4.5 の章構成

Claude はよりレポート型の章構成を採用していました。

## 1. エグゼクティブサマリー  
## 2. 探索ステップ詳細（トレーサビリティ根拠）  
## 3. 前提条件・テスト環境  
## 4. 機能要件  
   - 4.1 初期表示（カテゴリA）  
   - 4.2 サジェスト機能（カテゴリB）  
   - 4.3 検索実行（カテゴリC）  
   - 4.4 多言語対応（カテゴリE）  
   - 4.5 ナビゲーション（カテゴリD）  
   - 4.6 設定（カテゴリG）  
   - 4.7 フッター（カテゴリH）  
## 5. 非機能要件  
   - パフォーマンス（カテゴリL）  
   - セキュリティ（カテゴリJ）  
   - アクセシビリティ（カテゴリK）  
   - 互換性（カテゴリM）  
## 6. エラー処理・レジリエンス（カテゴリI, N）

特徴

テスト計画書的な重厚な構造
初心者には複雑だが文書としての完成度は高い
GPT-5 よりも設計者寄りのアプローチ

9.2. 「個々のテストケース」の書き方を比較

カテゴリA（初期表示）における TC-A01 を両者で比較します。

9.2.1. GPT-5 の TC-A01

### カテゴリA: 初期表示
1. TC-A01 初期要素可視性  
   手順: 初期URLアクセス。`getByRole('combobox',{name:/検索/})` 等を列挙。  
   期待: タイトル=Google / combobox focus / 検索ボタン2種 / Englishリンク / フッター主要リンク。  
   根拠: Step1/2。

特徴

シンプルで読みやすい
実務に必要な最小限の情報を押さえている

9.2.2. Claude の TC-A01

#### TC-A01: 主要UI要素の可視性
**優先度**: 高  
**手順**:
1. `https://www.google.com/?hl=ja` にアクセス
2. DOM要素を検証

**期待結果**:
- ページタイトル "Google"
- Googleロゴ画像
- combobox フォーカス状態
- 検索ボタン2種
- 音声/画像検索アイコン
- Gmail、画像、Googleアプリ、ログイン
- English リンク
- フッターリンク群

特徴

GPT-5 より丁寧かつ詳細
初心者でも迷わないレベルの網羅性

9.3. 差が明確に出た部分

カテゴリD（ナビゲーション）で GPT-5 と Claude の差が明確に出ました

9.3.1. GPT-5 のカテゴリD

### カテゴリD: ナビゲーション
17. TC-D01 Gmailリンク遷移  
18. TC-D02 画像検索 `/imghp`  
19. TC-D03 ストアリンク  
20. TC-D04 Googleアプリメニュー展開  
21. TC-D05 ログインリンク  
22. TC-D06 戻る操作でホーム復帰

問題点

手順がない
期待結果もない
記述が“メモ化”している

9.3.2. Claude のカテゴリD

### 4.5 ナビゲーション（カテゴリD）

#### TC-D01: Gmailリンク遷移
手順: "Gmail" をクリック  
期待: `https://mail.google.com/` へ遷移  

#### TC-D02: 画像検索遷移
手順: "画像" をクリック  
期待: `https://www.google.com/imghp` へ遷移  

#### TC-D03: Googleアプリメニュー表示
手順: Googleアプリボタンをクリック  
期待:
- iframe 展開  
- アプリ計33件が表示される

特徴

手順・期待が明確で実行可能
GPT-5 が弱くなる後半でも質が維持されている

9.4. 非機能テスト（パフォーマンス・セキュリティ）の比較

9.4.1. GPT-5 の非機能テスト

### カテゴリL: パフォーマンス
45. TC-L01 初期ロード指標 (TTFB/FCP/LCP)  
46. TC-L02 サジェストAPI応答 <200ms / p95<500ms  

### カテゴリJ: セキュリティ
39. TC-J01 HTTP→HTTPS強制  
40. TC-J02 CSPヘッダー検証  
41. TC-J03 XSS再掲

観点の抜けは少なく、重要ポイントはしっかり押さえている
- TTFB・FCP・LCP といった主要なパフォーマンス指標、HTTPS・CSP・XSS といった基本的セキュリティ観点は網羅されており、経験者にとっては十分な骨組みになっている
記述が “見出しレベル” で止まっており、実行可能性が低い
- 「どう測るか」「どう確認するか」「どのツールを使うか」などが明示されていないため、初心者が読んでも「結局どうやるの？」となりやすい
非機能テストの特性上、観点だけでは不足しやすい
- パフォーマンスは閾値だけでは不十分で、測定方法まで書かれていないとテストが再現できない点が弱さとして現れている

9.4.2. Claude の非機能テスト

### 5.1 パフォーマンス
TTFB <200ms  
FCP <1.0s  
LCP <2.5s  

### 5.2 セキュリティ
HTTPSリダイレクト確認  
CSPヘッダーが nonce/hash で保護

しきい値が明確で、実務でそのまま使える記述
-「TTFB <200ms」「LCP <2.5s」など具体的な値が示されているため、合否判定が容易で、テスト担当者間の認識ズレが起きにくい
測定内容が整理され、初心者でも理解しやすい構造
- パフォーマンスとセキュリティが章として分かれており、読む側が迷わない
セキュリティ面も具体的で実用的
- CSP の nonce/hash 設定まで踏み込んでいる点は実務的で、Web アプリケーションの堅牢性を確実に担保できる
総じて GPT-5 より“手順を追加すればすぐ運用可能なレベル”
- 書類としての完成度が高く、非機能特有の曖昧さを減らす構成になっている。

9.5. まとめ

比較箇所	GPT-5	Claude	目的
全体構成	箇条書き中心	重厚な章構成	文書整理の癖を比較
TC-A01	コンパクト	丁寧で詳細	基礎品質を比較
カテゴリD	手順・期待なし	全ケース詳細	GPT-5 の弱点確認
非機能	観点のみ	指標まで記述	専門性の差を明確化

GPT-5： 後半の情報が不足しがち
Claude： 丁寧だが重いので軽量化が必要

10. より安定した仕様書を作るためのプロンプト設計

上記の差を踏まえ、「GPT-5 でも Claude でも 似たレベルの高品質の仕様書 を出せるようにする」ためのプロンプトを作成した。

10.1 フェーズを分ける：構造（フェーズ1） → 詳細化（フェーズ2）

フェーズ1：構造だけを作る
- テストカテゴリ一覧
- 各カテゴリのシナリオ名（タイトル）
- シナリオの分類（Happy / Edge / Error）
- アプリ概要（短く）
フェーズ2：詳細テストケースを書く
- フェーズ1で作った構造を読み込み
- 1 カテゴリずつ、テンプレートに沿って詳細化

という 2 段階のプロンプトに分解しました。

フェーズ1のプロンプトには、

「このフェーズでは手順・期待結果・失敗条件など **詳細は絶対に書いてはいけない**」

と禁止事項を明記し、構造だけをきれいに揃えるようにしました。

10.2 テストケースのテンプレートを固定する

フェーズ2では、テストケースのテンプレートを強制します。

#### TC-<カテゴリ>-<番号>: <タイトル>

**前提条件:**
- <前提を書く>

**手順:**
1. <Step>
2. <Step>

**期待結果:**
- <Expected>

**成功条件:**
- <Success>

**失敗条件:**
- <Failure>

さらに、次のような禁止事項を書きました。

テンプレート項目の改名・追加・削除は禁止
独自フォーマットは禁止
テストケース ID を飛び番号にしてはいけない
1 回の出力で 10 ケース以上生成しない
「手順」「期待結果」「成功条件」「失敗条件」のいずれかが欠けてはいけない

こうすることで、GPT-5 が「後半で手順を省略してしまう」問題をかなり抑えることができました。

11. ここまでの知見を Appium＋モバイルアプリに展開するには

本記事の最初の目標は、「Playwright Test Agent の仕組みを理解し、Appium を使ったモバイルアプリのテスト仕様書自動生成につなげること」 でした。ここまでの整理を踏まえると、モバイル版に応用する際のポイントが見えてきます。

11.1 置き換えが必要な部分

Playwright MCP のブラウザ操作ツール
- → Appium の操作ツール（tap / swipe / sendKeys / back / rotate など）に置き換え
Seed テスト（seed.spec.ts）
- → Appium のテストフレームワーク（例えば WebDriverIO / Playwright for Mobile / Appium + Jest 等）で、アプリ起動〜ログイン〜初期画面表示までを行う 1 本の Seed テスト

11.2 流用できる部分

planner.chatmode.md の大枠の構造
- 「Navigate and Explore」
- 「Analyze User Flows」
- 「Design Comprehensive Scenarios」
- 「Structure Test Plans」
テストケースのテンプレート
フェーズ1/2 に分けるプロンプト設計

つまり、「ブラウザ UI を探索するツール一式」さえ「Appium のモバイル UI を探索するツール一式」に差し替えられれば、残りの 8 割はそのまま流用できる　というイメージです。

11.3 モバイルならではの追加観点

モバイルアプリでは、さらに次のようなテストカテゴリが必要になります。

ジェスチャー操作（スワイプ・ピンチ・長押しなど）
画面回転（縦横切り替え）
端末ごとの解像度・ DPI 差
通知との連携
オフライン / ネットワーク不安定時の挙動
バックグラウンド → フォアグラウンド復帰

Planner のカテゴリ設計に、これらを「モバイル専用カテゴリ」として足していくことで、 Appium 版のテスト仕様書自動生成にかなり近づけると考えられます。

12. まとめ

最後に、本記事のポイントを振り返ります。

Playwright Test Agent
- Playwright が特別な AI アルゴリズムを持っているわけではなく
- LLM＋VS Code ChatAgent＋MCP ツール＋chatmode.md の組み合わせで成立している
Planner の賢さ
- planner.chatmode.md に書かれた 役割・手順・出力例 によって生まれている
planner_setup_page
- Planner 専用の「最初の 1 手」を担うツールであり
- Seed テストを 1 回だけ実行して、ページをテストしやすい状態にする
GPT-5 と Claude でテスト仕様書を比較
- それぞれ得意・不得意な部分があり
- フェーズ分割とテンプレート固定で品質のバラつきを抑えられる
モバイルアプリへの応用では
- Playwright MCP のブラウザ操作ツールをモバイル UI 用のツールに置き換えることが第一歩
- chatmode.md やテストケーステンプレートの多くはそのまま流用できる

テストエンジニアとしては、「AI が自動で書いてくれた仕様書」を鵜呑みにするのではなく　どのような探索をした結果のアウトプットなのか 、 観点の抜けや過剰さがどこにあるか を理解した上でレビューすることが重要です。

今回見てきたように、「Playwright Test Agent のアーキテクチャをテスター目線で分解して理解する」 という視点は、モバイル・バックエンド含めた 今後のテスト自動化の共通基盤 になるはずです。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up