session.new Befehl

Syntax

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

Parameter

Das params Feld enthält:

capabilities

Ein Objekt, das die angeforderten Funktionen für die Sitzung spezifiziert. Es kann die folgenden Felder umfassen:

alwaysMatch Optional

Ein Objekt, das die angeforderten Funktionen spezifiziert, die alle vom Browser zur Sitzungserstellung erfüllt werden müssen. Wenn der Browser nicht alle angeforderten Funktionen in diesem Objekt erfüllen kann, wird die Sitzung nicht erstellt.

firstMatch Optional

Ein Array von Objekten, von denen jedes eine alternative Menge angeforderter Funktionen für die Sitzungserstellung spezifiziert. Der Browser versucht jede Menge in der angegebenen Reihenfolge und erstellt eine Sitzung mit der ersten, bei der alle angeforderten Funktionen erfüllt werden können. Wenn der Browser alle angeforderten Funktionen in keiner der Sätze erfüllen kann, wird die Sitzung nicht erstellt.

Die alwaysMatch und firstMatch Objekte können die folgenden Funktionen enthalten:

acceptInsecureCerts Optional

Ein Boolescher Wert, der angibt, ob nicht vertrauenswürdige TLS-Zertifikate (zum Beispiel selbstsignierte oder abgelaufene) für die Dauer der Sitzung akzeptiert werden.

browserName Optional

Ein String, der den Namen des zu verwendenden Browsers angibt (zum Beispiel, "firefox" oder "chrome").

browserVersion Optional

Ein String, der die zu verwendende Browserversion angibt (zum Beispiel, "120.0").

platformName Optional

Ein String, der das Betriebssystem angibt, das verwendet werden soll (zum Beispiel, "windows", "mac", "android" oder "linux").

proxy Optional

Ein Objekt, das die Proxy-Konfiguration spezifiziert, die der Browser für Netzwerkanforderungen verwenden soll.

unhandledPromptBehavior Optional

Ein Objekt, das das Standardverhalten spezifiziert, wenn während eines Befehls eine Benutzerabfrage (wie ein alert, confirm oder prompt Dialog) auftritt.

Rückgabewert

Die folgenden Felder im result Objekt der Antwort beschreiben die Eigenschaften der erstellten Sitzung:

sessionId

Ein String, der den eindeutigen Bezeichner für die neu erstellte Sitzung enthält.

capabilities

Ein Objekt, das die ausgehandelten und aktiven Funktionen für die Sitzung beschreibt. Es beinhaltet die folgenden Felder:

acceptInsecureCerts

Ein Boolescher Wert, der angibt, ob nicht vertrauenswürdige TLS-Zertifikate (zum Beispiel selbstsignierte oder abgelaufene) für die Dauer der Sitzung akzeptiert werden.

browserName

Ein String, der den Namen des Browsers enthält.

browserVersion

Ein String, der die Version des Browsers enthält.

platformName

Ein String, der den Namen des Betriebssystems enthält.

setWindowRect

Ein Boolescher Wert, der angibt, ob das Browserfenster mit dem Set Window Rect Befehl in der Größe verändert und repositioniert werden kann.

userAgent

Ein String, der die User-Agent-Zeichenkette des Browsers enthält (zum Beispiel, "Mozilla/5.0 (X11; Linux x86_64; rv:130.0) Gecko/20100101 Firefox/130.0").

proxy Optional

Ein Objekt, das die aktive Proxy-Konfiguration beschreibt. Ein leeres Objekt ({}) zeigt an, dass kein Proxy konfiguriert ist.

unhandledPromptBehavior Optional

Ein Objekt, das das Standardverhalten beschreibt, wenn während eines Befehls eine Benutzerabfrage (wie ein alert, confirm oder prompt Dialog) auftritt. Dieses Feld ist nur vorhanden, wenn es im capabilities Parameter spezifiziert wurde.

webSocketUrl Optional

Ein String, der die WebSocket-URL für die Sitzung enthält.

Der Browser kann auch browserspezifische Funktionen zurückgeben, die mit einem Browser-Bezeichner präfixiert sind (zum Beispiel, moz:buildID für Firefox).

Fehler

Sitzung nicht erstellt

Eine Sitzung existiert bereits, oder der Browser ist nicht in der Lage, eine neue Sitzung zu erstellen (zum Beispiel, weil eine angeforderte Funktion nicht erfüllt werden kann).

Beispiele

Erstellen einer Sitzung mit Standardfunktionen

Bei einer etablierten WebDriver BiDi-Verbindung senden Sie die folgende Nachricht, um eine neue Sitzung mit den Standardfunktionen zu erstellen:

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

Der Browser antwortet mit dem Sitzungsbezeichner und den ausgehandelten Funktionen:

{
  "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": {}
    }
  }
}

Erstellen einer Sitzung mit erforderlichen Funktionen

Um einen bestimmten Browser zu verwenden und unsichere Zertifikate mit alwaysMatch zu akzeptieren, senden Sie die folgende Nachricht:

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

Wenn der Browser die angeforderten Funktionen erfüllen kann, antwortet er mit dem Sitzungsbezeichner und den ausgehandelten Funktionen wie folgt:

{
  "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": {}
    }
  }
}

Versuch, eine Sitzung zu erstellen, wenn bereits eine existiert

In Browsern, die keine Mehrfachsitzungen unterstützen (z.B. Firefox), führt das Senden von session.new, wenn bereits eine Sitzung aktiv ist, zu einer Fehlermeldung:

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• session.status Befehl
• session.end Befehl