feat: implement browsingContext.traverseHistory (#1537)

Fixed: #1532

src/bidiMapper/BidiNoOpParser.ts

@@ -65,6 +65,11 @@ export class BidiNoOpParser implements IBidiParser {
   ): BrowsingContext.SetViewportParameters {
     return params as BrowsingContext.SetViewportParameters;
   }
+  parseTraverseHistoryParams(
+    params: unknown
+  ): BrowsingContext.TraverseHistoryParameters {
+    return params as BrowsingContext.TraverseHistoryParameters;
+  }
   // keep-sorted end
 
   // CDP domain

src/bidiMapper/BidiParser.ts

@@ -43,6 +43,9 @@ export interface IBidiParser {
   parseSetViewportParams(
     params: unknown
   ): BrowsingContext.SetViewportParameters;
+  parseTraverseHistoryParams(
+    params: unknown
+  ): BrowsingContext.TraverseHistoryParameters;
   // keep-sorted end
 
   // CDP domain

src/bidiMapper/CommandProcessor.ts

@@ -181,7 +181,9 @@ export class CommandProcessor extends EventEmitter<CommandProcessorEventsMap> {
           this.#parser.parseSetViewportParams(command.params)
         );
       case 'browsingContext.traverseHistory':
-        break;
+        return await this.#browsingContextProcessor.traverseHistory(
+          this.#parser.parseTraverseHistoryParams(command.params)
+        );
       // keep-sorted end
 
       // CDP domain

src/bidiMapper/domains/context/BrowsingContextImpl.ts

@@ -22,6 +22,7 @@ import {
   ChromiumBidi,
   InvalidArgumentException,
   NoSuchElementException,
+  NoSuchHistoryEntryException,
   Script,
   UnableToCaptureScreenException,
   UnknownErrorException,
@@ -962,6 +963,28 @@ export class BrowsingContextImpl {
   async close(): Promise<void> {
     await this.#cdpTarget.cdpClient.sendCommand('Page.close');
   }
+
+  async traverseHistory(delta: number): Promise<void> {
+    if (delta === 0) {
+      return;
+    }
+
+    const history = await this.#cdpTarget.cdpClient.sendCommand(
+      'Page.getNavigationHistory'
+    );
+    const entry = history.entries[history.currentIndex + delta];
+    if (!entry) {
+      throw new NoSuchHistoryEntryException(
+        `No history entry at delta ${delta}`
+      );
+    }
+    await this.#cdpTarget.cdpClient.sendCommand('Page.navigateToHistoryEntry', {
+      entryId: entry.id,
+    });
+
+    this.#resetDeferredsIfFinished();
+    await this.lifecycleLoaded();
+  }
 }
 
 function getImageFormatParameters(

src/bidiMapper/domains/context/BrowsingContextProcessor.ts

@@ -196,6 +196,19 @@ export class BrowsingContextProcessor {
     return {};
   }
 
+  async traverseHistory(
+    params: BrowsingContext.TraverseHistoryParameters
+  ): Promise<BrowsingContext.TraverseHistoryResult> {
+    const context = this.#browsingContextStorage.getContext(params.context);
+    if (!context) {
+      throw new InvalidArgumentException(
+        `No browsing context with id ${params.context}`
+      );
+    }
+    await context.traverseHistory(params.delta);
+    return {};
+  }
+
   async handleUserPrompt(
     params: BrowsingContext.HandleUserPromptParameters
   ): Promise<EmptyResult> {

src/bidiTab/BidiParser.ts

@@ -64,6 +64,11 @@ export class BidiParser implements IBidiParser {
   ): BrowsingContext.SetViewportParameters {
     return Parser.BrowsingContext.parseSetViewportParams(params);
   }
+  parseTraverseHistoryParams(
+    params: unknown
+  ): BrowsingContext.TraverseHistoryParameters {
+    return Parser.BrowsingContext.parseTraverseHistoryParams(params);
+  }
   // keep-sorted end
 
   // CDP domain

src/protocol-parser/protocol-parser.ts

@@ -215,6 +215,15 @@ export namespace BrowsingContext {
     );
   }
 
+  export function parseTraverseHistoryParams(
+    params: unknown
+  ): Protocol.BrowsingContext.TraverseHistoryParameters {
+    return parseObject(
+      params,
+      WebDriverBidi.BrowsingContext.TraverseHistoryParametersSchema
+    );
+  }
+
   export function parseHandleUserPromptParameters(
     params: unknown
   ): Protocol.BrowsingContext.HandleUserPromptParameters {

tests/browsing_context/test_traverse_history.py

@@ -0,0 +1,80 @@
+# Copyright 2023 Google LLC.
+# Copyright (c) Microsoft Corporation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+from test_helpers import execute_command, goto_url
+
+HISTORY_LENGTH = 2
+
+
+@pytest.mark.asyncio
+async def test_traverse_history(websocket, context_id, html):
+    for i in range(HISTORY_LENGTH + 1):
+        await goto_url(websocket, context_id, html(i))
+
+    await traverse_history(websocket, context_id, -2)
+    await assert_href_equals(websocket, context_id, html(HISTORY_LENGTH - 2))
+
+    await traverse_history(websocket, context_id, 2)
+    await assert_href_equals(websocket, context_id, html(HISTORY_LENGTH))
+
+    await traverse_history(websocket, context_id, -1)
+    await assert_href_equals(websocket, context_id, html(HISTORY_LENGTH - 1))
+
+    await traverse_history(websocket, context_id, 1)
+    await assert_href_equals(websocket, context_id, html(HISTORY_LENGTH))
+
+    await traverse_history(websocket, context_id, 0)
+    await assert_href_equals(websocket, context_id, html(HISTORY_LENGTH))
+
+
+@pytest.mark.asyncio
+async def test_traverse_history_no_entry(websocket, context_id, html):
+    await goto_url(websocket, context_id, html())
+
+    with pytest.raises(Exception,
+                       match=str({
+                           "error": "no such history entry",
+                           "message": "No history entry at delta -2"
+                       })):
+        await traverse_history(websocket, context_id, -2)
+
+
+async def traverse_history(websocket, context_id, delta):
+    await execute_command(
+        websocket, {
+            "method": "browsingContext.traverseHistory",
+            "params": {
+                "context": context_id,
+                "delta": delta
+            }
+        })
+
+
+async def assert_href_equals(websocket, context_id, href):
+    result = await execute_command(
+        websocket, {
+            "method": "script.evaluate",
+            "params": {
+                "expression": "window.location.href",
+                "target": {
+                    "context": context_id
+                },
+                "resultOwnership": "none",
+                "awaitPromise": True
+            }
+        })
+
+    assert result["result"]["value"] == href