playwright-interactive-sandbox

コアワークフロー

1. テスト前に簡潔なQAインベントリを作成します:
   • インベントリを3つのソースから構築します: ユーザーが要求した要件、実装した目に見えるユーザーの機能または動作、最終的な回答で述べると予想される主張。
   • これら3つのソースのいずれかに現れるものは、すべてサインオフ前に少なくとも1つのQAチェックにマップされる必要があります。
   • サインオフする予定のユーザーに見える主張をリストアップします。
   • すべての意味のあるユーザー向けコントロール、モードスイッチ、実装されたインタラクティブ動作をリストアップします。
   • 各コントロールまたは実装された動作が引き起こすことができる状態変化またはビュー変化をリストアップします。
   • これを機能QAと視覚QAの両方の共有カバレッジリストとして使用します。
   • 各主張またはコントロール-状態ペアについて、意図した機能チェック、視覚チェックが発生する必要がある特定の状態、および予想される証拠をメモします。
   • 要件が視覚的に重要だが主観的である場合は、暗黙のままにするのではなく、観察可能なQAチェックに変換します。
   • 脆弱な動作を露出させる可能性のある探索的またはハッピーパスの外の最低2つのシナリオを追加します。
2. 永続的なTTYセッションで必要なdevサーバーを開始または確認します。
3. 変更されたフロー用に専用のPlaywrightベリフィケーションスクリプトを作成します。
4. デスクトップスクリプトを最初に実行してから、変更がモバイルレイアウトまたはタッチ動作に影響する場合、モバイルスクリプトを追加します。
5. コード変更後、クリーンなNode.jsプロセスからベリフィケーションスクリプトを再度実行します。
6. 通常のユーザー入力で機能QAを実行します。
7. 別の視覚QAパスを実行します。
8. ビューポートのフィットを確認し、主張をサポートするために必要なスクリーンショットをキャプチャします。
9. 成功したランからスクリーンショットアーティファクトを保存します。

デスクトップベリフィケーションスクリプト

TARGET_URLをデバッグしているアプリに設定します。ポート4444を使用し、localhostよりも127.0.0.1を優先します。

このサンドボックスでは、Playwrightブラウザは/ms-playwrightの下にプリインストールされており、PLAYWRIGHT_BROWSERS_PATHはすでにその場所に設定されている場合があります。デフォルトキャッシュパス~/.cache/ms-playwrightを想定しないでください。

このDebianサンドボックスでは、Playwrightにヘッドレスモードを使用してください。環境が明示的にXサーバーを提供しない限り、ヘッドモードを試すために試行を費やさないでください。

このDebianサンドボックスでは、Playwrightにヘッドレスモードを使用してください。環境が明示的にXサーバーを提供しない限り、ヘッドモードを試すために試行を費やさないでください。

このDebianサンドボックスでは、Playwrightにヘッドレスモードを使用してください。環境が明示的にXサーバーを提供しない限り、ヘッドモードを試すために試行を費やさないでください。

import { chromium } from 'playwright';

const TARGET_URL = 'http://127.0.0.1:4444';
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({
	viewport: { width: 1600, height: 900 }
});
const page = await context.newPage();

try {
	await page.goto(TARGET_URL, { waitUntil: 'domcontentloaded' });
	console.log('Loaded:', await page.title());

	// タスク固有のインタラクションとアサーションをここに追加します。

	await page.screenshot({ path: 'playwright-desktop.png', type: 'png' });
} finally {
	await context.close().catch(() => {});
	await browser.close().catch(() => {});
}

メインの変更されたフロー用にこのパターンを使用します。スクリプトを、検証する必要のある正確な動作に焦点を当てたままにしてください。

Playwrightブラウザパスとインストール済みブラウザペイロードを確認したい場合は、以下を実行できます:

echo "$PLAYWRIGHT_BROWSERS_PATH"
ls -al /ms-playwright

例のチェックラン:

node /tmp/playwright-verify-desktop.mjs

モバイルベリフィケーションスクリプト

タスクがレスポンシブレイアウトまたはタッチ動作に影響する場合、別のモバイルスクリプトを使用してください。

import { chromium } from 'playwright';

const TARGET_URL = 'http://127.0.0.1:4444';
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({
	viewport: { width: 390, height: 844 },
	isMobile: true,
	hasTouch: true
});
const page = await context.newPage();

try {
	await page.goto(TARGET_URL, { waitUntil: 'domcontentloaded' });
	console.log('Loaded mobile:', await page.title());

	// タスク固有のインタラクションとアサーションをここに追加します。

	await page.screenshot({ path: 'playwright-mobile.png', type: 'png' });
} finally {
	await context.close().catch(() => {});
	await browser.close().catch(() => {});
}

イテレーションモデル

• ベリフィケーションパスごとに1つのスタンドアロンNode.jsスクリプトを使用します。
• コード変更後、実行間での状態を保持しようとするのではなく、クリーンなプロセスからベリフィケーションスクリプトを再度実行します。
• 各スクリプトは細い内容にしてください: 1つの変更されたフロー、その主要なアサーション、およびそのスクリーンショットアーティファクト。
• デスクトップとモバイルの両方が重要な場合は、1つの大きなステートフルスクリプトではなく、別のスクリプトまたは別の呼び出しを実行します。

チェックリスト

セッションループ

• 現在のバリデーションラン用のNode.jsPlaywrightベリフィケーションスクリプトを作成して実行します。
• 現在のワークスペースからターゲットWebアプリを起動します。
• コード変更を行います。
• その変更の正しいパスを使用して、リロードまたは再起動します。
• 探索が追加のコントロール、状態、または目に見える主張を明らかにした場合、共有QAインベントリを更新します。
• 機能QAを再度実行します。
• 視覚QAを再度実行します。
• 最終的なアーティファクトは、評価している現在の状態がこの状態の後にのみキャプチャしてください。

リロード決定

• レンダラーのみの変更: 既存のページをリロードします。
• 現在のスクリプトが変更された動作に引き続きマッチするかについての新しい不確実性: 推測するのではなく、クリーンなスクリプトを再度実行します。

機能QA

• サインオフに実際のユーザーコントロールを使用します: キーボード、マウス、クリック、タッチ、または同等のPlaywright入力API。
• 少なくとも1つのエンドツーエンドの重要なフローを検証します。
• 内部状態だけでなく、そのフローの目に見える結果を確認します。
• リアルタイムまたはアニメーション満載のアプリの場合、実際のインタラクションタイミング下での動作を検証します。
• アドホックなスポットチェックではなく、共有QAインベントリを使用して実行します。
• サインオフの前に、メインのハッピーパスだけでなく、目に見えるすべてのコントロールを少なくとも1回カバーしてください。
• インベントリの可逆的なコントロールまたはステートフルなトグルについては、完全なサイクルをテストします: 初期状態、変更された状態、初期状態への復帰。
• スクリプト化されたチェックが完了した後、意図したパスに従うだけでなく、30-90秒間の短い探索的パスを通常の入力を使用して実行します。
• 探索的パスが新しい状態、コントロール、または主張を明かした場合、それを共有QAインベントリに追加してサインオフの前にカバーしてください。
• page.evaluate(...)は状態を検査またはステージングできますが、サインオフ入力としてカウントされません。

視覚QA

• 視覚QAを機能QAとは別のものとして扱います。
• テスト前に定義された同じ共有QAインベントリを使用し、QA中に更新します。異なる暗黙のリストから視覚カバレッジを開始しないでください。
• ユーザーに見える主張を再述べて、それぞれを明示的に検証します。機能パスが視覚的な主張を証明するよう仮定しないでください。
• ユーザーに見える主張は、それが認識されることを目的とした特定の状態で検査されるまで、サインオフされません。
• スクロール前に初期ビューポートを検査します。
• 初期ビューが目に見えるように、インターフェースの主要な主張をサポートしていることを確認します。約束された核心要素が明確に認識できない場合は、それをバグとして扱います。
• メインのインタラクションサーフェスだけでなく、必要なすべての目に見える領域を検査します。
• 共有QAインベントリで列挙された状態とモードを検査します。タスクがインタラクティブな場合は、意味のある相互作用後の状態を少なくとも1つ含めます。
• モーションまたはトランジションが経験の一部である場合は、定着したエンドポイントに加えてインフライト状態を少なくとも1つ検査します。
• ラベル、オーバーレイ、注釈、ガイド、またはハイライトが変更するコンテンツを追跡することを目的としている場合は、関連する状態変化後にその関係を検証します。
• 動的またはインタラクション依存のビジュアルの場合は、単一のスクリーンショットのサインオフに依存しないで、安定性、レイヤリング、および読みやすさを判断するのに十分な長さを検査します。
• ロード後またはインタラクション後により密集することができるインターフェースの場合、空の、ロード中の、または折りたたまれた状態だけでなく、QA中に到達できる最も密集した現実的な状態を検査します。
• 製品に定義された最小サポートされるビューポートまたはウィンドウサイズがある場合、別の視覚QAパスをそこで実行します。それ以外の場合は、より小さいが現実的なサイズを選択してそれを明示的に検査します。
• 存在と実装を区別します: 意図したアフォーダンスが技術的には存在していても、コントラストが弱い、遮蔽、クリッピング、または不安定さのために明確に認識できない場合は、それを視覚的な失敗として扱います。
• 必要な目に見える領域が、評価している状態でクリップされ、切り取られ、遮蔽され、またはビューポート外に押し出されている場合、ページレベルのスクロールメトリクスが許容可能に見えても、それをバグとして扱います。
• クリッピング、オーバーフロー、歪み、レイアウトの不均衡、一貫性のないスペーシング、配置の問題、読めないテキスト、弱いコントラスト、レイヤリングの破損、そして不格好なモーション状態を探します。
• 美的品質と正確性を判断します。UIはタスク向けに意図的で、一貫性があり、視覚的に心地よい感じがするべきです。
• サインオフにはビューポートスクリーンショットを優先します。フルページキャプチャは二次的なデバッグアーティファクトとしてのみ使用し、領域がより詳細な検査が必要な場合は焦点を絞ったスクリーンショットをキャプチャします。
• モーションがスクリーンショットを曖昧にする場合は、UIが落ち着くまで短く待ってから、実際に評価している画像をキャプチャします。
• サインオフの前に、明示的に尋ねてください: このインターフェースのどの目に見える部分をまだ詳細に検査していませんか?
• サインオフの前に、明示的に尋ねてください: ユーザーが注意深く見た場合、この結果を最も恥ずかしくさせるだろう目に見える欠陥は何ですか?

サインオフ

• 機能パスは通常のユーザー入力で合格しました。
• カバレッジは共有QAインベントリに対して明示的です: どの要件、実装された機能、コントロール、状態、および主張が実行されたかをメモし、意図的な除外を呼び出します。
• 視覚QAパスは、関連するインターフェース全体をカバーしていました。
• 各ユーザーに見える主張は、対応する視覚チェックとその主張が重要なビューポートまたはウィンドウサイズの状態からのレビュー済みスクリーンショットアーティファクトを持っています。
• ビューポートフィットチェックは、意図した初期ビューと必要な最小サポートされるビューポートサイズの両方で合格しました。
• UIは単に機能するだけでなく、視覚的に一貫性があり、タスク向けに美的に弱くありません。
• 機能の正確性、ビューポートのフィット、および視覚品質は、それぞれ独自に合格する必要があります。1つが他を意味しません。
• インタラクティブな製品については短い探索的パスが完了し、応答ではそのパスでカバーされたことがメンションされています。
• スクリーンショットレビューと数値チェックがいかなる時点でも一致しない場合、その不一致はサインオフの前に調査されました。スクリーンショットの目に見えるクリッピングは、メトリクスが覆い隠すことができない何かではなく、解決する失敗です。
• 確認して見つからなかった主要な欠陥クラスの簡潔な否定確認を含めます。
• 証拠として必要な最終的な成功したスクリーンショットアーティファクトを保持し、失敗した実行または中間実行から古い、または廃止されたイメージアーティファクトを削除します。

スクリーンショットキャプチャ

証拠とデバッグに通常のPlaywrightスクリーンショットを使用します。

デスクトップスクリーンショット:

await page.screenshot({ path: 'playwright-desktop.png', type: 'png' });

モバイルスクリーンショット:

await mobilePage.screenshot({ path: 'playwright-mobile.png', type: 'png' });

焦点を絞った領域のクリップされたスクリーンショット:

const clip = await page.locator('[data-testid="target"]').boundingBox();
if (clip) {
	await page.screenshot({ path: 'playwright-target.png', type: 'png', clip });
}

デフォルトではサインオフにはビューポートスクリーンショットを使用します。必要な場合の二次的なデバッグアーティファクトとしてのみフルページスクリーンショットを使用してください。

ビューポートフィットチェック (必須)

メインウィジェットが見えるだけだからといって、スクリーンショットが許容可能であると仮定しないでください。サインオフの前に、スクリーンショットレビューと数値チェックの両方を使用して、意図した初期ビューが製品要件と一致することを明示的に検証します。

• サインオフの前に意図した初期ビューを定義します。スクロール可能なページの場合、これはミラル上の経験です。アプリケーションシェル、ゲーム、エディタ、ダッシュボード、またはツールの場合、これは完全なインタラクティブサーフェスプラス、それを使用するために必要なコントロールとステータスです。
• スクリーンショットを使用してフィットの主要な証拠として使用します。数値チェックはスクリーンショットをサポートします。それらは目に見えるクリッピングを覆い隠しません。
• サインオフは、ページレベルのスクロールメトリクスが許容可能に見えても、意図した初期ビューで任意の必要な目に見える領域がクリップされ、切り取られ、遮蔽され、またはビューポート外に押し出されている場合に失敗します。
• スクロールは、製品がスクロールするように設計され、初期ビューが依然として核心経験を伝達し、プライマリコールトゥアクションまたは必要な開始コンテキストを公開する場合に許容可能です。
• 固定シェルインターフェースの場合、プライマリインタラクティブサーフェスまたは本質的なコントロールの一部に到達するために必要な場合、スクロールは許容可能な回避方法ではありません。
• ドキュメントスクロールメトリクスだけに依存しないでください。 固定高シェル、内部ペイン、隠されたオーバーフロー、コンテナはページレベルのスクロールチェックが依然としてクリーンに見えるように見える間に必要なUIをクリップできます。
• ドキュメント境界ではなく、領域の境界をチェックします。スタートアップ状態でビューポート内に各必要な目に見える領域が適合することを確認します。
• ビューポートフィットチェックの合格は、意図した初期ビューが意図しないクリッピングまたはスクロールなしに目に見えることを証明するだけです。UIが視覚的に正しいまたは美的に成功していることを証明しません。

Webまたはレンダラーチェック:

console.log(
	await page.evaluate(() => ({
		innerWidth: window.innerWidth,
		innerHeight: window.innerHeight,
		clientWidth: document.documentElement.clientWidth,
		clientHeight: document.documentElement.clientHeight,
		scrollWidth: document.documentElement.scrollWidth,
		scrollHeight: document.documentElement.scrollHeight,
		canScrollX: document.documentElement.scrollWidth > document.documentElement.clientWidth,
		canScrollY: document.documentElement.scrollHeight > document.documentElement.clientHeight
	}))
);

クリッピングがあなたの特定のUIで現実的な失敗モードである場合は、数値チェックを必要な目に見える領域のgetBoundingClientRect()チェックで増やします。ドキュメントレベルのメトリクスだけは固定シェルには十分ではありません。

Devサーバー

ローカルWebデバッグでは、永続的なTTYセッションでアプリを実行したままにしてください。短時間のシェルからの1回限りのバックグラウンドコマンドに依存しないでください。

最初にビルドしてから、ポート4444でのみビルドされたアプリを開始します:

npm run build
PORT=4444 npm run start

page.goto(...)の前に、ポート4444がリッスンしていることと、アプリが応答していることを確認します。

• インタラクティブなベリフィケーションが完了した後、ポート4444で開始したサーバープロセスを停止して、サンドボックスをタスクの残りの部分に対して清潔に保ちます。
• このDebianサンドボックスではfuserは利用できません。ss -ltnp | rg ":4444"を使用してリッスンしているPIDを見つけ、kill <pid>を実行し、ss -ltnp | rg ":4444"を再度実行してポート4444がもうリッスンしていないことを確認します。
• クリーンアップ後に古い、または廃止されたインタラクティブなイメージアーティファクトを削除して、最終的な成功した証拠のみが残るようにしてください。
• インタラクティブなベリフィケーションが完了した後、ポート4444で開始したサーバープロセスを停止して、サンドボックスをタスクの残りの部分に対して清潔に保ちます。
• このDebianサンドボックスではfuserは利用できません。ss -ltnp | rg ":4444"を使用してリッスンしているPIDを見つけ、kill <pid>を実行し、ss -ltnp | rg ":4444"を再度実行してポート4444がもうリッスンしていないことを確認します。
• インタラクティブなベリフィケーションが完了した後、ポート4444で開始したサーバープロセスを停止して、サンドボックスをタスクの残りの部分に対して清潔に保ちます。

よくある失敗モード

• Cannot find module 'playwright': 現在のワークスペースでPlaywrightパッケージがインストールされていることを確認し、Node.jsスクリプトを実行する前にインポートを検証します。
• Playwrightパッケージはインストールされていますが、ブラウザ実行可能ファイルが見つからないようです: 最初にecho $PLAYWRIGHT_BROWSERS_PATHとls -al /ms-playwrightを確認します。このサンドボックスでは、ブラウザは~/.cache/ms-playwrightではなく/ms-playwrightで想定されています。ディレクトリが実際に不在であるまたは使用不可の場合にのみnpx playwright install chromiumを実行します。
• page.goto: net::ERR_CONNECTION_REFUSED: devサーバーが永続的なTTYセッションで引き続き実行されていることを確認し、ポートを再チェックし、http://127.0.0.1:<port>を優先します。
• Node.jsプロセスが予期せず終了またはリセットされました: クリーンなプロセスからベリフィケーションスクリプトを再度実行します。