browsingContext.traverseHistory command

The browsingContext.traverseHistory command of the browsingContext module navigates back or forward in the session history of the specified top-level context, similar to a user clicking the browser's back and forward buttons.

Syntax

json
{
  "method": "browsingContext.traverseHistory",
  "params": {
    "context": "<contextId>",
    "delta": <integer>
  }
}

Parameters

The params field contains:

context

A string that contains the ID of the top-level context whose session history is to be navigated. Context IDs are returned by commands such as browsingContext.getTree.

delta

An integer that specifies the number of history entries to move in the session history. A positive value moves the context forward in history; a negative value moves it backward.

Return value

The result field in the response is an empty object ({}). The command returns once the traversal has been queued, before the resulting navigation is complete. The browsingContext.historyUpdated event fires when the traversal is complete.

Errors

invalid argument

A required parameter is missing or has an invalid type. This error is also returned when the specified context is not a top-level context.

no such frame

No context with the given context ID is found.

no such history entry

The position in the session history specified by delta does not exist.

Examples

undefined

Assume you have a WebDriver BiDi connection and an active session.

Suppose you created a tab using browsingContext.create and navigated it through several pages using browsingContext.navigate: from https://example.com/page1.html to https://example.com/page2.html, and then to https://example.com/page3.html. To navigate two history entries back, that is, to skip https://example.com/page2.html and land at https://example.com/page1.html, send the following message:

json
{
  "id": 1,
  "method": "browsingContext.traverseHistory",
  "params": {
    "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa",
    "delta": -2
  }
}

The browser queues the history traversal and responds as follows:

json
{
  "id": 1,
  "type": "success",
  "result": {}
}

Continuing from the previous example, to navigate one history entry forward, landing at https://example.com/page2.html, send the following message:

json
{
  "id": 2,
  "method": "browsingContext.traverseHistory",
  "params": {
    "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa",
    "delta": 1
  }
}

The browser queues the history traversal and responds as follows:

json
{
  "id": 2,
  "type": "success",
  "result": {}
}

Specifications

See also