validate-ui-scenario

UI シナリオを検証する

実際の VS Code インスタンスをシナリオに沿って操作し、再現可能な証拠を記録します。

報告されたバグを再現したり、修正が機能することを示したり、テスト計画項目に録画を添付したりする際に使用します。すべてのビルドで実行される決定論的な回帰テストが必要な場合は、代わりにスモークテストを作成してください（smoke-tests スキルを参照）。このスキルは、単発の問題に基づく検証用です。

シナリオは、test/scenario/out/runScenario.js で実行する小さな JavaScript ファイルです。ほかに設定する必要はありません。ランナーが VS Code を起動し、動画とトレースを記録し、各ステップの境界でスクリーンショットを撮影し、レポートを書き出します。また、各ステップとその結果を録画にキャプションとして付けます。

準備

npm install                             # once
npm --prefix test/scenario run compile  # after any change under test/scenario

実行前に、ffmpeg と ffprobe が利用可能であることを確認してください。 ランナーは PATH と一般的なインストール先を検索するため、エディターの起動後にインストールした ffmpeg も検出できます。これらがなくてもシナリオは実行され、生の録画は保持されますが、動画にステップのタイトルは付きません。ランナーは起動時に警告します。見つからない場合は、注釈のない動画を黙って返すのではなく、インストール方法をユーザーに伝えてください。

プラットフォーム	インストール
Windows	winget install Gyan.FFmpeg
macOS	brew install ffmpeg
Linux	sudo apt install ffmpeg

PATH に反映するため、新しいターミナルが必要になる場合があります。または、FFMPEG_PATH と FFPROBE_PATH を設定してください。既存の実行結果には、後から node test/scenario/out/renderEvidenceChapters.js <run-dir> を使って注釈を付けられます。

対象	フラグ	ほかに必要なもの	用途
インストール済み Insiders。なければ Stable	(なし — 既定)	なし	リリース済みの動作を基準に報告を再現する
このチェックアウトからの開発ビルド	--dev	一致する Electron ランタイム、npm run build-fast	マージ前の変更を検証する
特定のインストール	--build <app-root>	なし	特定のビルドに固定する
Web	--web --headless	npm run build-fast -- --client-only	ブラウザーのみの動作

一致する Electron ランタイムがあれば再利用してください。見つからない場合、または互換性がない場合にのみ npm run electron を実行します。高速ビルドでは型チェックを行わずに出力を更新するため、必要に応じて別途型を検証してください。

対象を指定するフラグがない場合、ランナーはインストール済みの VS Code Insiders を探し、見つからなければ Stable を使用して、選択したものをログに記録します。--build にはアプリケーションのルートを指定します。Windows と Linux ではインストールディレクトリ、macOS では .app バンドルです。

# Windows
--build "C:/Users/<you>/AppData/Local/Programs/Microsoft VS Code Insiders"
# macOS
--build "/Applications/Visual Studio Code - Insiders.app"

各対象は独自のプロファイルと拡張機能ディレクトリを使用するため、拡張機能や設定が録画に混入することはありません。また、録画キャンバスに合わせてウィンドウのサイズを調整するため、キャプチャに余白ができません。証拠には、実際に実行したビルドの品質（Insiders、Stable、Dev）が記録されるため、レポートには検証対象の製品が必ず明記されます。インストール済みビルドで再現できるのはリリース済みの動作のみです。マージ前の変更を検証するには、その変更を含むチェックアウトで --dev を使用してください。

シナリオを書く

生成される実行結果と同じ場所にファイルを保存します。たとえば、.build/vscode-playwright-mcp/<issue>.cjs のようにします。.cjs 拡張子が重要です。このパッケージは ES モジュールパッケージなので、CommonJS シナリオを .js という名前にすると読み込みに失敗します。デフォルトエクスポートを使用する ES モジュールシナリオも使えます。

const os = require('os');
const path = require('path');
const fs = require('fs');

const workspacePath = path.join(os.tmpdir(), 'issue-250159-workspace');
fs.mkdirSync(workspacePath, { recursive: true });

// The settings tree is virtualized, so only the rows near the viewport exist in
// the DOM. Scroll the whole list, otherwise "the setting is absent" cannot be
// told apart from "the setting is below the fold".
const COLLECT_TITLES = `(async () => {
	const editor = document.querySelector('.settings-editor');
	const scrollable = editor.querySelector('.settings-tree-container .monaco-scrollable-element');
	const titles = new Set();
	const collect = () => editor.querySelectorAll('.setting-item-label')
		.forEach(node => titles.add(node.textContent.trim()));
	collect();
	for (let previous = -1; scrollable && scrollable.scrollTop !== previous;) {
		previous = scrollable.scrollTop;
		scrollable.scrollTop = previous + scrollable.clientHeight;
		await new Promise(resolve => setTimeout(resolve, 180));
		collect();
	}
	return [...titles];
})()`;

module.exports = {
	id: 'vscode-250159-settings-search',
	title: 'Settings search matches across title and description',
	source: 'https://github.com/microsoft/vscode/issues/250159',
	workspacePath,
	steps: [
		{
			id: 'SS-01',
			title: 'Open the Settings editor',
			async run(context) {
				await context.workbench.quickaccess.runCommand('workbench.action.openSettings2');
				await context.page.waitForSelector('.settings-editor', { state: 'visible', timeout: 20000 });
				return 'The Settings editor is visible.';
			}
		},
		{
			id: 'SS-02',
			title: 'Search across title and description',
			async run(context) {
				await context.workbench.settingsEditor.searchSettingsUI('chat confirm');
				const titles = await context.page.evaluate(COLLECT_TITLES);
				if (!titles.some(title => /max\s*requests/iu.test(title))) {
					throw new Error(`Max Requests is absent. Found: ${titles.join(', ')}`);
				}
				return 'Max Requests is present in the results.';
			}
		}
	]
};

フィールド	意味
id, title	実行を識別します。id はエビデンスディレクトリの名前になります
source	シナリオの元になった課題またはテスト計画の項目です
workspacePath	開く使い捨てフォルダーです
userSettings	起動前にプロファイルに設定する項目です。--agents を使う場合は、組み込みの Agents プロファイルも含みます
extraArgs	VS Code の追加のコマンドライン引数です
extraEnv	起動するアプリの環境変数の上書き設定です。undefined は変数を解除します。自動化ランナーの HOME は変更せず、このフィールドを使ってアプリケーションの検出を分離してください。
stepPauseMs	各ステップの終了後、キャプションを読みやすくするために表示を保持する時間です。デフォルトは 1000 です。シナリオのタイミングが重要な場合は 0 に設定します

各ステップには、app、workbench、code、page、および skip(reason, options) を含む context が渡されます。workbench は機能ヘルパー（settingsEditor、quickaccess、editors、terminal、chat など）を提供します。ヘルパーで対応できない操作には page の Playwright ページを使用します。

レスポンシブレイアウトのシナリオでは、context.code.driver.resizeWindow({ width, height }) を使用します。現在のネイティブ Electron ウィンドウ（Web ではブラウザーのビューポート）のサイズを変更し、復元用に変更前のサイズを返します。

• 文字列を返す：ステップの検証内容を説明します。レポートに表示されます。
• 例外をスローする：ステップを失敗として扱います。メッセージが記録され、実行は停止します。
• skip(reason, { needs }) を呼び出す：ステップを自動で検証できない場合に使用します。実行は停止し、成功ではなく aborted として報告されます。

自動化できないステップ

シナリオを書く前の計画段階で判断し、それぞれを分類してください。次の 2 種類では、結果が異なります。

needs	意味	対応方法
human	物理的なハードウェア、主観的な判断、スクリプト化できないサインインなど、人の作業が必要です	担当者が手動で確認できるよう、ステップを報告します
infrastructure	原理上は自動化できますが、ハーネスがまだ対応していません	不足している機能を明記し、このスキルの機能拡張として報告します

ctx.skip('Comparing physical print output requires a person with a printer.', { needs: 'human' });
ctx.skip('The harness cannot drive native OS file dialogs.', { needs: 'infrastructure' });

ブロックされたステップは manifest.json に記録され、report.html の 要確認 セクションで強調表示されます。動画のキャプションには SKIPPED - NEEDS HUMAN と表示され、実行の最後に出力されます。概要にも必ず記載してください。実行できなかったステップを黙って省略したり、アサーションを弱めて成功させたりしないでください。

実行する

node test/scenario/out/runScenario.js <scenario.cjs>

終了コード 0 はすべてのステップが成功したことを、1 は実行が失敗または中断されたことを、2 は使用方法に誤りがあったことを意味します。

エビデンスは .build/vscode-playwright-mcp/evidence/<run-id>/ に書き込まれます。

ファイル	内容
report.html	ステップの表、結果、埋め込み動画
manifest.json	ステップのタイムスタンプ、ステータス、アーティファクトのパス、環境
videos/annotated.mp4	各ステップとその検証結果を示すキャプション帯付きの録画
videos/*.webm	元の録画
*.png	ステップごとのスクリーンショット
logs/	Playwright のトレース、ウィンドウログ、サーバーログ

キャプション帯は録画フレームに重ねず、その上に追加されるため、録画されたピクセルが隠れることはなく、録画の長さも変わりません。各キャプションには、ステップ番号と ID、ステータス、ステップのタイトル、ステップで報告された検証の詳細が含まれます。マニフェストを編集した後は、node test/scenario/out/renderEvidenceChapters.js <run-dir> を実行して再レンダリングしてください。

信頼できる証拠とは

• DOM の状態、アクセシビリティ、フォーカス、またはテキストを検証します。スクリーンショットは主張を裏付けますが、それを立証するものではありません。
• アクションとは別のシグナルで検証します。自動化の呼び出しが正常に完了しても、それは結果ではありません。
• 仮想化されたリストに注意してください。設定ツリーや長いリストでは、ビューポート付近の行だけが描画されるため、何かが存在しないと結論づける前に、リスト全体をスクロールしてください。
• バグが競合状態の場合は、タイミングを明示します。強制的な遅延や繰り返しのループを使い、運に頼るのではなく、発生する時間帯が記録に残るようにしてください。
• 可能であれば、修正前に不具合の動作を記録してください。成功した実行だけでは、そのシナリオでバグを検出できたかどうかは分かりません。

結果を報告する

結果を要約し、失敗またはスキップした手順を列挙し、report.html へのリンクを記載して、OS、VS Code のバージョンと品質（どちらも manifest.json に記載されています）、および元の issue を明記してください。動画をコメント欄にドラッグして、issue またはプルリクエストに添付してください。

合否の結果とは分けて、必ず次の点を明記してください。

• 人手が必要な手順。未検証の内容が分かるようにしてください。
• ハーネスの機能不足でブロックされた手順。このスキルへの具体的な機能追加として示してください。
• 証拠の質を損ねた要因。たとえば、ffmpeg がなく、動画にキャプションが付かなかった場合などです。

関連項目

• 対話的な調査。 test/mcp では、これらのツールを MCP（vscode_automation_*）経由でも利用できます。何を検証すべきか分かる前に UI を調査する必要がある場合に便利です。cwd を test/mcp、コマンドを npm run start-stdio にして、MCP サーバーとして設定してください。
• プルリクエストでの自動検証。 microsoft/vscode-engineering は CI で同じハーネスを実行します。プルリクエストに ~requires-ui-validation ラベルを付けると、変更を調査し、正確なマージ候補に対してシナリオを実行して、キャプション付き動画と各手順の結果を投稿します。シナリオがまだそこでカバーされていない場合や、提案前にローカルで反復検証する場合は、このスキルを使用してください。

ユーザー: "/validate-ui-scenario reproduce https://github.com/microsoft/vscode/issues/250159"

1. ffmpeg／ffprobe が利用できることを確認します。利用できない場合は、動画にステップタイトルが表示されないことをユーザーが予期できるよう、実行前にその旨を伝え、インストールコマンドを示します。
2. issue を読み、観測可能な主張を特定します。Settings エディターで chat confirm を検索すると、説明に確認について記載された Max Requests が一致するはずです。
3. ベースラインの手順（max requests で設定が見つかる）を追加します。これにより、設定がビルドに含まれていないことが原因で失敗した可能性を排除できます。
4. .build/vscode-playwright-mcp/issue-250159.cjs を作成し、ターゲットフラグを指定せずに実行します。これにより、インストール済みの Insiders が使われます。表示されたレポートのパスを確認します。
5. 各手順の結果を報告し、report.html へのリンクを記載して、videos/annotated.mp4 を添付します。

検索手順で実行が失敗した場合、それが答えです。issue は再現しています。シナリオの失敗ではなく、再現に成功したと報告してください。