ブラウザ操作を止めない：CDP を活用した act:evaluate のリファクタリング

ブラウザ自動化を実装していると、特定のスクリプト実行が原因でタブ全体の操作が固まってしまうことがあります。Playwright を使っている場合、一つの evaluate が長時間実行されると、その後のクリックや入力操作がすべてキュー待ちになり、ブラウザが「ハング」したように見えてしまいます。これは開発者にとって非常にストレスフルな問題です。

この問題を解決するために、act:evaluate を Playwright から切り離し、CDP（Chrome DevTools Protocol）を直接利用して実行する新しいアーキテクチャを導入します。

必要なもの

このリファクタリングを進めるにあたって、以下の要素が必要になります。

• act:evaluate API の利用環境
• Playwright
• CDP (Chrome DevTools Protocol) へのアクセス権限
• browser.evaluateEnabled ゲートの設定

クイックスタート

5 分で新しい実行エンジンの流れを理解しましょう。ポイントは、Playwright のコマンドキューをバイパスすることです。

1. 共通の Budget 管理を導入する

まず、タイムアウトと中断（Abort）を一つの「予算（Budget）」として管理します。これにより、すべてのレイヤーで一貫したタイムアウト挙動を実現します。

// src/browser/client-fetch.ts や src/node-host/runner.ts で利用
const budget = createBudget({ timeoutMs, signal });
// budget.signal, budget.deadlineAtMs, budget.remainingMs() を使用

2. CDP ベースの Evaluate エンジンを構築する

次に、Playwright とは別の WebSocket 接続を使用して CDP セッションを開始します。

• Target.attachToTarget を使用して sessionId を取得します。
• ページレベルの実行には Runtime.evaluate を使用します。
• 特定の要素に対する実行には DOM.resolveNode と Runtime.callFunctionOn を組み合わせます。

3. 要素のターゲット指定を拡張する

既存の Playwright locator との互換性を保つため、メタデータに backendDOMNodeId を追加します。

1. スナップショット作成時に Accessibility.getFullAXTree を使用して AX tree を取得します。
2. (role, name, nth) の組み合わせから backendDOMNodeId へのマッピングを計算します。
3. 成功した場合は、この ID を使用して CDP 経由で直接要素を操作します。

4. 実行パスのルーティング

act:evaluate が呼ばれた際、以下の優先順位で実行します。

• ref がない場合：常に CDP を使用します。
• ref が backendDOMNodeId を持っている場合：CDP を使用します。
• それ以外の場合：従来の Playwright パスへフォールバックします。

トラブルシューティング

実装中によく遭遇する問題と解決策です。

マッピングに失敗して CDP が使えない

要素の特定ができない場合は、自動的に Playwright パスへフォールバックされます。この際、PR #13498 で導入された安全策（実行の制限と復旧処理）が適用されるため、最低限の安全性は確保されます。

Runtime.terminateExecution の副作用

タイムアウト時に実行を強制終了すると、ページ上の JavaScript 状態に影響を与える可能性があります。これは仕様上のトレードオフですが、タブ全体がロックされるよりは安全です。エラーログでこの挙動を明示することをおすすめします。

パフォーマンスへの影響

AX tree の取得は負荷がかかるため、スナップショットが要求された時のみ実行し、ターゲットごとにキャッシュを保持することでオーバーヘッドを最小限に抑えます。

---

さらなる詳細は AI Setup Assistant で確認できます。

次のステップ

• Browser Action API Reference
• CDP Integration Guide