大网数据广告活动
Web 标准与前端开发

`session.new` command

· 52CE 我爱测

The `session.new` command of the `session` module creates a new BiDi session with the browser.

The session.new command of the session module creates a new BiDi session with the browser.

Since this command is used to create a new session, it runs without an already active session. (In BiDi, such a command is called a static command.)

[!NOTE] A session created this way is only accessible over WebSocket and cannot be managed using classic WebDriver HTTP commands.

Syntax

/* With required parameters */
{
  "method": "session.new",
  "params": {
    "capabilities": {}
  }
}

/* With required and optional parameters */
{
  "method": "session.new",
  "params": {
    "capabilities": {
      "alwaysMatch": {
        "acceptInsecureCerts": true,
        "proxy": {
          "proxyType": "manual",
          "httpProxy": "127.0.0.1:80"
        },
        "unhandledPromptBehavior": {
          "default": "accept"
        }
      },
      "firstMatch": [
        {
          "browserName": "firefox",
          "platformName": "mac"
        },
        {
          "browserName": "chrome",
          "platformName": "windows"
        }
      ]
    }
  }
}

Parameters

The params field contains:

  • capabilities
    • : An object that specifies the requested features for the session. It can include the following fields:
      • alwaysMatch
        • : An object that specifies the requested features that must all be satisfied by the browser for session creation. If the browser cannot satisfy all requested features in this object, the session is not created.
      • firstMatch
        • : An array of objects, each specifying an alternative set of requested features for session creation. The browser tries each set in the order specified and creates a session using the first where all requested features can be satisfied. If the browser cannot satisfy all requested features in any of the sets, the session is not created.

The alwaysMatch and firstMatch objects can include the following features:

  • acceptInsecureCerts
    • : A boolean that controls whether untrusted TLS certificates (for example, self-signed or expired) are accepted for the duration of the session.
  • browserName
    • : A string that specifies the name of the browser to use (for example, "firefox" or "chrome").
  • browserVersion
    • : A string that specifies the browser version to match (for example, "120.0").
  • platformName
    • : A string that specifies the operating system to match (for example, "windows", "mac", "android", or "linux").
  • proxy
    • : An object that specifies the proxy configuration the browser should use for network requests.
  • unhandledPromptBehavior
    • : An object that specifies the default behavior when a user prompt (such as an alert, confirm, or prompt dialog) is encountered during a command.

Return value

The following fields in the result object of the response describe the characteristics of the created session:

  • capabilities
    • : An object that describes the capabilities that were negotiated and are active for the session. It includes the following fields:
      • acceptInsecureCerts
        • : A boolean that indicates whether untrusted TLS certificates (for example, self-signed or expired) are accepted for the duration of the session.
      • browserName
        • : A string that contains the name of the browser.
      • browserVersion
        • : A string that contains the version of the browser.
      • platformName
        • : A string that contains the name of the operating system.
      • proxy
        • : An object that describes the active proxy configuration. An empty object ({}) indicates no proxy is configured.
      • setWindowRect
        • : A boolean that indicates whether the browser window can be resized and repositioned using the Set Window Rect command.
      • unhandledPromptBehavior
        • : An object that describes the default behavior when a user prompt (such as an alert, confirm, or prompt dialog) is encountered during a command. This field is present only when specified in the capabilities parameter.
      • userAgent
        • : A string that contains the browser's user agent string (for example, "Mozilla/5.0 (X11; Linux x86_64; rv:130.0) Gecko/20100101 Firefox/130.0").
      • webSocketUrl
        • : A string that contains the WebSocket URL for the session.
  • sessionId
    • : A string that contains the unique identifier for the newly created session.

The browser may also return vendor-specific capabilities prefixed with a browser identifier (for example, moz:buildID for Firefox).

Errors

  • session not created
    • : A session already exists, or the browser is unable to create a new session (for example, because a requested capability cannot be satisfied).

Examples

Creating a session with default capabilities

With a WebDriver BiDi connection established, send the following message to create a new session with default capabilities:

{
  "id": 1,
  "method": "session.new",
  "params": {
    "capabilities": {}
  }
}

The browser responds with the session identifier and the negotiated capabilities:

{
  "id": 1,
  "type": "success",
  "result": {
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "capabilities": {
      "acceptInsecureCerts": false,
      "browserName": "firefox",
      "browserVersion": "147.0.4",
      "platformName": "mac",
      "setWindowRect": true,
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:147.0) Gecko/20100101 Firefox/147.0",
      "proxy": {}
    }
  }
}

Creating a session with required capabilities

To require a specific browser and accept insecure certificates using alwaysMatch, send the following message:

{
  "id": 1,
  "method": "session.new",
  "params": {
    "capabilities": {
      "alwaysMatch": {
        "browserName": "firefox",
        "acceptInsecureCerts": true
      }
    }
  }
}

If the browser can satisfy the requested capabilities, it responds with the session identifier and negotiated capabilities as follows:

{
  "id": 1,
  "type": "success",
  "result": {
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "capabilities": {
      "acceptInsecureCerts": true,
      "browserName": "firefox",
      "browserVersion": "147.0.4",
      "platformName": "mac",
      "setWindowRect": true,
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:147.0) Gecko/20100101 Firefox/147.0",
      "proxy": {}
    }
  }
}

Attempting to create a session when one already exists

In browsers that don't support multiple sessions (e.g., Firefox), sending session.new when a session is already active results in an error response:

{
  "type": "error",
  "id": 1,
  "error": "session not created",
  "message": "Maximum number of active sessions",
  "stacktrace": ""
}

Specifications

Browser compatibility

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。