Web Application Testing

ローカル Web アプリケーションをテストするために、ネイティブな Python Playwright スクリプトを作成します。

利用可能なヘルパースクリプト:

• scripts/with_server.py - サーバーライフサイクルを管理（複数サーバーに対応）

常にスクリプトを --help で最初に実行してください。使用方法を確認してからご利用ください。カスタマイズされたソリューションが絶対に必要になるまで、ソースコードを読まないでください。これらのスクリプトは非常に大きい場合があるため、コンテキストウィンドウを圧迫する可能性があります。これらはコンテキストウィンドウに取り込まれるのではなく、ブラックボックススクリプトとして直接呼び出すために存在します。

Decision Tree: アプローチの選択

ユーザータスク → 静的な HTML ですか？
    ├─ はい → HTML ファイルを直接読んでセレクターを特定
    │         ├─ 成功 → セレクターを使用して Playwright スクリプトを作成
    │         └─ 失敗/不完全 → 動的として扱う（下記参照）
    │
    └─ いいえ（動的 webapp） → サーバーはすでに実行中ですか？
        ├─ いいえ → 実行: python scripts/with_server.py --help
        │          その後、ヘルパーを使用して、簡略化された Playwright スクリプトを作成
        │
        └─ はい → 情報収集してから行動:
            1. ナビゲートして networkidle を待機
            2. スクリーンショット撮影または DOM を検査
            3. レンダリング済みの状態からセレクターを特定
            4. 特定したセレクターでアクションを実行

例: with_server.py の使用

サーバーを起動するには、最初に --help を実行してから、ヘルパーを使用します：

シングルサーバー:

python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py

複数サーバー（例：バックエンド＋フロントエンド）:

python scripts/with_server.py \
  --server "cd backend && python server.py" --port 3000 \
  --server "cd frontend && npm run dev" --port 5173 \
  -- python your_automation.py

オートメーションスクリプトを作成するには、Playwright ロジックのみを含めてください（サーバーは自動的に管理されます）：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
    page = browser.new_page()
    page.goto('http://localhost:5173') # サーバーはすでに実行中で準備完了
    page.wait_for_load_state('networkidle') # 重要: JS の実行を待機
    # ... あなたのオートメーションロジック
    browser.close()

情報収集してから行動パターン

1. レンダリング済み DOM を検査:

   page.screenshot(path='/tmp/inspect.png', full_page=True)
   content = page.content()
   page.locator('button').all()
   

2. 検査結果からセレクターを特定

3. 特定したセレクターを使ってアクションを実行

よくある落とし穴

❌ 動的アプリでは networkidle を待たずに DOM を検査しないでください ✅ 検査する前に page.wait_for_load_state('networkidle') を待つようにしてください

ベストプラクティス

• バンドルされたスクリプトをブラックボックスとして使用 - タスクを完成させるために、scripts/ で利用可能なスクリプトのいずれかが役立つかどうかを検討してください。これらのスクリプトは、一般的で複雑なワークフローを確実に処理し、コンテキストウィンドウを汚染しません。--help で使用方法を確認してから、直接実行してください。
• 同期スクリプトには sync_playwright() を使用
• 完了時は常にブラウザーを閉じる
• 説明的なセレクターを使用：text=、role=、CSS セレクター、または ID
• 適切な待機を追加：page.wait_for_selector() または page.wait_for_timeout()

リファレンスファイル

• examples/ - 一般的なパターンを示す例：
  • element_discovery.py - ページ上のボタン、リンク、入力要素の検出
  • static_html_automation.py - ローカル HTML に対する file:// URL の使用
  • console_logging.py - オートメーション中のコンソールログの取得

使用時期

このスキルは、概要に記載されたワークフローまたはアクションを実行する場合に適用されます。

制限事項

• このスキルは、上記で説明されたスコープと明確に一致するタスク場合にのみ使用してください。
• 出力を環境固有の検証、テスト、または専門家によるレビューの代替としてみなさないでください。
• 必要な入力、権限、安全境界、または成功基準が不足している場合は、停止して明確化を求めてください。