webapp-testing

Webアプリケーションテスト

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

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

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

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

判断ツリー：アプローチの選択

ユーザータスク → 静的HTMLか？
    ├─ はい → HTMLファイルを直接読み取り、セレクタを特定
    │         ├─ 成功 → セレクタを使用したPlaywrightスクリプトを作成
    │         └─ 失敗/不完全 → 動的として扱う（以下へ）
    │
    └─ いいえ（動的Webアプリ） → サーバーは既に実行中か？
        ├─ いいえ → 実行: 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) # 常にchromiumをヘッドレスモードで起動
    page = browser.new_page()
    page.goto('http://localhost:5173') # サーバーは既に実行中で準備完了
    page.wait_for_load_state('networkidle') # 重要: JavaScriptの実行を待機
    # ... 自動化ロジック
    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 - 自動化中にコンソールログをキャプチャする