fix: add cdp.resolveRealm command (#1882)

`cdp.resolveRealm` resolves a realm ID to an executionContextId.

This is needed for Puppeteer to adopt nodes from ARIA queries.

This is a workaround for https://crbug.com/326258571

README.md

@@ -66,6 +66,25 @@ CdpGetSessionResult = {
 
 The command returns the default CDP session for the selected browsing context.
 
+### Command `cdp.resolveRealm`
+
+```cddl
+CdpResolveRealmCommand = {
+   method: "cdp.resolveRealm",
+   params: ScriptEvaluateParameters,
+}
+
+CdpResolveRealmParameters = {
+   realm: Script.Realm,
+}
+
+CdpResolveRealmResult = {
+   executionContextId: text,
+}
+```
+
+The command returns resolves a BiDi realm to its CDP execution context ID.
+
 ### Events `cdp`
 
 ```cddl

src/bidiMapper/BidiNoOpParser.ts

@@ -79,6 +79,9 @@ export class BidiNoOpParser implements BidiCommandParameterParser {
   parseGetSessionParams(params: unknown): Cdp.GetSessionParameters {
     return params as Cdp.GetSessionParameters;
   }
+  parseResolveRealmParams(params: unknown): Cdp.ResolveRealmParameters {
+    return params as Cdp.ResolveRealmParameters;
+  }
   parseSendCommandParams(params: unknown): Cdp.SendCommandParameters {
     return params as Cdp.SendCommandParameters;
   }

src/bidiMapper/BidiParser.ts

@@ -53,6 +53,7 @@ export interface BidiCommandParameterParser {
   // CDP domain
   // keep-sorted start block=yes
   parseGetSessionParams(params: unknown): Cdp.GetSessionParameters;
+  parseResolveRealmParams(params: unknown): Cdp.ResolveRealmParameters;
   parseSendCommandParams(params: unknown): Cdp.SendCommandParameters;
   // keep-sorted end
 

src/bidiMapper/CommandProcessor.ts

@@ -112,6 +112,7 @@ export class CommandProcessor extends EventEmitter<CommandProcessorEventsMap> {
     );
     this.#cdpProcessor = new CdpProcessor(
       browsingContextStorage,
+      realmStorage,
       cdpConnection,
       browserCdpClient
     );
@@ -217,6 +218,10 @@ export class CommandProcessor extends EventEmitter<CommandProcessorEventsMap> {
         return this.#cdpProcessor.getSession(
           this.#parser.parseGetSessionParams(command.params)
         );
+      case 'cdp.resolveRealm':
+        return this.#cdpProcessor.resolveRealm(
+          this.#parser.parseResolveRealmParams(command.params)
+        );
       case 'cdp.sendCommand':
         return await this.#cdpProcessor.sendCommand(
           this.#parser.parseSendCommandParams(command.params)

src/bidiMapper/domains/cdp/CdpProcessor.ts

@@ -15,21 +15,25 @@
  * limitations under the License.
  */
 
-import type {Cdp} from '../../../protocol/protocol.js';
+import {UnknownErrorException, type Cdp} from '../../../protocol/protocol.js';
 import type {CdpClient, CdpConnection} from '../../BidiMapper.js';
 import type {BrowsingContextStorage} from '../context/BrowsingContextStorage.js';
+import type {RealmStorage} from '../script/RealmStorage.js';
 
 export class CdpProcessor {
   readonly #browsingContextStorage: BrowsingContextStorage;
+  readonly #realmStorage: RealmStorage;
   readonly #cdpConnection: CdpConnection;
   readonly #browserCdpClient: CdpClient;
 
   constructor(
     browsingContextStorage: BrowsingContextStorage,
+    realmStorage: RealmStorage,
     cdpConnection: CdpConnection,
     browserCdpClient: CdpClient
   ) {
     this.#browsingContextStorage = browsingContextStorage;
+    this.#realmStorage = realmStorage;
     this.#cdpConnection = cdpConnection;
     this.#browserCdpClient = browserCdpClient;
   }
@@ -44,6 +48,15 @@ export class CdpProcessor {
     return {session: sessionId};
   }
 
+  resolveRealm(params: Cdp.ResolveRealmParameters): Cdp.ResolveRealmResult {
+    const context = params.realm;
+    const realm = this.#realmStorage.getRealm({realmId: context});
+    if (realm === undefined) {
+      throw new UnknownErrorException(`Could not find realm ${params.realm}`);
+    }
+    return {executionContextId: realm.executionContextId};
+  }
+
   async sendCommand(
     params: Cdp.SendCommandParameters
   ): Promise<Cdp.SendCommandResult> {

src/bidiTab/BidiParser.ts

@@ -78,6 +78,9 @@ export class BidiParser implements BidiCommandParameterParser {
   parseGetSessionParams(params: unknown): Cdp.GetSessionParameters {
     return Parser.Cdp.parseGetSessionRequest(params);
   }
+  parseResolveRealmParams(params: unknown): Cdp.ResolveRealmParameters {
+    return Parser.Cdp.parseResolveRealmRequest(params);
+  }
   parseSendCommandParams(params: unknown): Cdp.SendCommandParameters {
     return Parser.Cdp.parseSendCommandRequest(params);
   }

src/protocol-parser/protocol-parser.ts

@@ -330,6 +330,10 @@ export namespace Cdp {
     context: WebDriverBidi.BrowsingContext.BrowsingContextSchema,
   });
 
+  const ResolveRealmRequestSchema = z.object({
+    realm: WebDriverBidi.Script.RealmSchema,
+  });
+
   export function parseSendCommandRequest(
     params: unknown
   ): Protocol.Cdp.SendCommandParameters {
@@ -344,6 +348,12 @@ export namespace Cdp {
   ): Protocol.Cdp.GetSessionParameters {
     return parseObject(params, GetSessionRequestSchema);
   }
+
+  export function parseResolveRealmRequest(
+    params: unknown
+  ): Protocol.Cdp.ResolveRealmParameters {
+    return parseObject(params, ResolveRealmRequestSchema);
+  }
 }
 
 export namespace Permissions {

src/protocol/cdp.ts

@@ -17,7 +17,11 @@
 import type {Protocol} from 'devtools-protocol';
 import type {ProtocolMapping} from 'devtools-protocol/types/protocol-mapping.js';
 
-import type {BrowsingContext, JsUint} from './generated/webdriver-bidi.js';
+import type {
+  BrowsingContext,
+  JsUint,
+  Script,
+} from './generated/webdriver-bidi.js';
 
 export type EventNames = Event['method'];
 
@@ -26,14 +30,20 @@ export type Message = CommandResponse | Event;
 export type Command = {
   id: JsUint;
 } & CommandData;
-export type CommandData = SendCommandCommand | GetSessionCommand;
+export type CommandData =
+  | SendCommandCommand
+  | GetSessionCommand
+  | ResolveRealmCommand;
 
 export type CommandResponse = {
   type: 'success';
   id: JsUint;
   result: ResultData;
 };
-export type ResultData = SendCommandResult | GetSessionResult;
+export type ResultData =
+  | SendCommandResult
+  | GetSessionResult
+  | ResolveRealmResult;
 
 export type SendCommandCommand = {
   method: 'cdp.sendCommand';
@@ -67,6 +77,19 @@ export type GetSessionResult = {
   session?: Protocol.Target.SessionID;
 };
 
+export type ResolveRealmCommand = {
+  method: 'cdp.resolveRealm';
+  params: ResolveRealmParameters;
+};
+
+export type ResolveRealmParameters = {
+  realm: Script.Realm;
+};
+
+export type ResolveRealmResult = {
+  executionContextId: Protocol.Runtime.ExecutionContextId;
+};
+
 export type Event = {
   type: 'event';
 } & EventData;

tests/script/test_realm.py

@@ -14,7 +14,7 @@
 # limitations under the License.
 
 import pytest
-from anys import ANY_STR
+from anys import ANY_NUMBER, ANY_STR
 from test_helpers import (execute_command, read_JSON_message,
                           send_JSON_command, subscribe, wait_for_event,
                           wait_for_filtered_event)
@@ -205,3 +205,33 @@ async def test_realm_dedicated_worker(websocket, context_id, html):
     # Wait for confirmation that worker was destroyed
     event = await wait_for_event(websocket, 'script.realmDestroyed')
     assert event['params'] == {'realm': worker_realm}
+
+
+@pytest.mark.asyncio
+async def test_realm_cdpResolveRealm(websocket, context_id, html):
+    url = html()
+
+    await subscribe(websocket, ["script.realmCreated"])
+
+    await send_JSON_command(
+        websocket, {
+            "method": "browsingContext.navigate",
+            "params": {
+                "context": context_id,
+                "url": url,
+                "wait": "complete",
+            }
+        })
+
+    response = await read_JSON_message(websocket)
+
+    realm = response["params"]["realm"]
+
+    result = await execute_command(websocket, {
+        "method": "cdp.resolveRealm",
+        "params": {
+            "realm": realm
+        }
+    })
+
+    assert result == {'executionContextId': ANY_NUMBER}