Repository navigation
session settings
open_session is the one call that makes a browser, and it is where a browser's shape is chosen:
which browser and version, its window, its two timeouts, whether it accepts a bad certificate, runs
headless, is recorded or captured, and any raw WebDriver capability nothing else covers. This area
holds what each setting is called on every surface, where its value comes from when several are
given, what a workspace remembers, how the capabilities sent to the Grid are built, and what a
refused open says.
- An operator sets
session.browser,session.versionandsession.capabilitiesonce, so every new browser lands on the right Grid node class without an agent knowing about it. - A client pins its own browser or window in its connection config (
?browser=,Sf-Browser) and never passes them in a call. - An agent opens Firefox 152 at 1400 by 900, and a browser the Grid reaps comes back the same.
- An agent opens
headless=truefor a fast task and is told at once that it cannot also record. - An agent adds a Chrome flag through raw
capabilities, and a key a named option controls is refused with the option to use.
SET-1. The record, its store and the reopen after a reap are in
workspaces-and-sessions.md. Site data restored into a new browser is
in site-data.md. The live view that a headless browser lacks is in
live-view-and-control.md. The tool, route and header machinery (the
Sf- names, X-Workspace, the request schema) is in surfaces.md. How the Session
tab draws what this file serves is in admin-ui.md. Recording and capture themselves
are in workspace-files.md and capture.md; this file holds only
how they are asked for. Configuration loading is in config.md.
SET-2. An open takes the settings in the table. url, fresh and restore_site_data are
arguments of the call, not settings, and are never remembered.
| Setting | Argument | Query | Header | Config key | Value |
|---|---|---|---|---|---|
browser |
browser |
?browser= |
Sf-Browser |
session.browser |
chrome (default) or firefox
|
version |
version |
?version= |
Sf-Version |
session.version |
a string, or latest
|
width |
width |
?width= |
Sf-Window-Width |
session.width |
integer |
height |
height |
?height= |
Sf-Window-Height |
session.height |
integer |
page_load_timeout |
page_load_timeout |
?page_load_timeout= |
Sf-Page-Load-Timeout |
session.page_load_timeout |
seconds |
script_timeout |
script_timeout |
?script_timeout= |
Sf-Script-Timeout |
session.script_timeout |
seconds |
insecure |
insecure |
none | none | none | boolean |
headless |
headless |
none | none | none | boolean |
record |
record |
none | none | none | boolean |
capture |
capture |
none | none | none | boolean |
capabilities |
capabilities |
none | none |
session.capabilities (separate source, SET-27) |
object |
The argument is a tool argument on /mcp and a body field of POST /browser. The config keys take
the environment spellings SESSION_BROWSER, SESSION_VERSION and so on.
SET-3. A header wins over the query parameter of the same setting. A blank or unusable header
falls through to the parameter, and a repeated header or parameter counts as its last value. A
header or parameter outside the table is not a setting. The retired X- names are refused
(SURF-10).
SET-4. No bound is checked on width, height or either timeout, by the server or by the
config. A value the browser or the Grid cannot honour fails the open, which quits the browser it
made.
SET-5. browser is the only setting whose bad value is refused everywhere it is explicit.
An explicit browser that is not chrome or firefox (any casing, surrounding space dropped) is
a ValueError, a 400 reading unknown browser 'x'; known browsers: chrome, firefox. A bad
session.browser stops the server at load. A bad client default (a header or parameter) is
ignored with a warning, so a typo in a connection config does not stop a browser opening. The MCP
tool's schema takes only the lowercase names, and a blank browser there means unset.
SET-6. A client default or explicit value that cannot be read as the setting's type (a non-numeric width, say) is dropped with a warning and the setting reads as unset. An unset window or timeout leaves the browser's own default; selenium-flow invents no number for it.
SET-7. A setting's value is the first of these that names it, highest first:
- the call's own argument;
- what this workspace's caller passed to an earlier open;
- the client's default (header or parameter);
- the operator's config.
workspace/settings.py walks the layers, and each setting's winning layer is its source:
config, client or caller. The call's argument and the workspace's memory are both
caller.
SET-8. A workspace keeps only what a caller passed. The config and the client's defaults are
read afresh at every explicit open_session, so a changed session.* value or a dropped header
reaches the next open and never a browser already running. The workspace's record holds the
resolved settings with a source for each key (set_by); an explicit open inherits only the keys
whose source is caller.
SET-9. insecure, headless, record, capture and capabilities have no client or config
layer. false is a value: insecure=false or headless=false beats a remembered true, and is
remembered in its turn. {} is a value for capabilities and clears the remembered object.
SET-10. record and capture are never inherited by an explicit open: each is asked for again
for the next browser. All other settings are.
SET-11. A call that passes version with no browser (other than latest) is stored with the
browser in effect at that open as the caller's, so a later change of session.browser does not
move the version onto the other browser.
SET-12. A version belongs to its browser. Walking the layers from the lowest, a layer that names
a browser different from the one in effect drops every version from the layers below it. A version
in that same layer stands. The same browser keeps its version. So session.version=152 with
open_session(browser="firefox") asks for Firefox with no version.
SET-13. version="latest" (any casing) is a value: it beats a remembered, client or config
version and is never sent to the Grid. version that is blank or only space reads as unset.
Beyond that, version is any string; the Grid decides whether it has one.
SET-14. The window and the timeouts are WebDriver commands sent after the browser starts, not capabilities. Width and height are set together, and one given alone keeps the browser's other dimension. A timeout of 0 or unset sends no command. The window is set before the restore of site data and before the first page loads, so it holds for both.
SET-15. resize marks width and height as the caller's in the stored settings, so a resized
window is carried over and replayed after a reap.
SET-16. Every setting takes effect at the next browser. Nothing here changes a browser that is
already open, apart from resize (SET-15).
SET-17. After a reap, the reopen replays the whole stored set, whoever set each value, and each keeps its source. A config value stays the config's, so the next explicit open still reads the config afresh. A browser never changes shape mid-task.
SET-18. The reopen drops record when recording is switched off on the server and capture
when capture is, and replays them otherwise.
SET-19. The record also keeps, for the Session tab:
-
sent, the capabilities that browser's open sent with their sources (SET-31); -
ran, the version, node name and live-view flag the Grid reported (browserVersion,se:containerName,se:vncEnabled; each null when absent); -
ended, how the last browser ended.
A new browser clears ended. Ending a browser keeps sent, ran, the settings and their
sources.
SET-20. A stored record whose set_by is missing, malformed or does not name exactly the keys
of its settings reads with no settings and no browser. Its history, site data, sent and ran
stay. The next call is told to call open_session, which starts from the config, the client and its
arguments.
SET-21. fresh=true drops only the remembered page. The settings still come through the
cascade, and an explicit url is never overridden by it.
SET-22. open_session validates before it ends the browser the workspace holds, so a rejected
argument costs nothing. In order, it refuses: a person controlling the held browser (409); an
explicit bad browser (SET-5) or a capabilities that is not an object, reading
capabilities must be an object (400); record on a server with recording off (400); record
with headless (SET-23); capture on a server with capture off (400); an owned key or malformed
vendor block in capabilities (SET-28 to SET-30); a url that is not allowed (400).
SET-23. A headless browser cannot be recorded. record=true with headless in effect is a 400
that says where headless came from. Passed in this call: a headless browser draws nothing to film: record=true cannot be asked with headless=true. Remembered: this workspace's browser is headless, remembered from an earlier open: pass headless=false to record. A server with recording off says
that first.
SET-24. A headless browser has no live view for as long as it lives. The live view's mint and
socket refuse it with this browser is headless: it has no live view, after the no-browser reason
and before the Grid-has-no-VNC reason. The check reads the record's headless setting, so ran's
live-view flag stays what the Grid said.
SET-25. headless=true sends --headless=new in goog:chromeOptions.args on Chrome and
-headless in moz:firefoxOptions.args on Firefox, with source option. headless=false sends
nothing.
SET-26. insecure always sends acceptInsecureCerts, true or false, on both browsers, so
Firefox refuses a bad certificate as Chrome does. A browser opened insecure is not restored saved
site data: when the workspace has any, the open's site_data.skipped says an insecure browser gets no saved site data, and nothing is deleted.
SET-27. What an open sends is built in one place, session_caps.build, from four layers, in
this order: flow (what selenium-flow always sends), option (what a named setting produces),
config (session.capabilities, the operator's) and raw (the call's capabilities). The config
object is its own source, merged under the raw one at every open; it is not a lower layer of the
stored raw setting, so a config change reaches the next open of a workspace that remembers a raw
object. What is built is exactly what is sent: Selenium's own extra keys (pageLoadStrategy, and on
Firefox moz:debuggerAddress) are not sent.
SET-28. Flow always sends unhandledPromptBehavior: ignore, se:downloadsEnabled: true and
webSocketUrl: true, plus its own block entries: on Chrome the args --no-sandbox and
--disable-dev-shm-usage and four prefs, on Firefox five prefs. Option sends browserName;
browserVersion unless unset or latest; acceptInsecureCerts; and for record, se:recordVideo
and, with a video name, se:videoName.
SET-29. Owned keys cannot be set by capabilities or session.capabilities. A raw key is a
400, a config key stops the server at load, and the message is <key> cannot be sent in capabilities: <what to use> (where is session.capabilities for config), several joined with
; :
| Key | Use instead |
|---|---|
browserName |
browser= |
browserVersion |
version= |
acceptInsecureCerts |
insecure=true or insecure=false
|
se:recordVideo, se:videoName
|
record=true |
timeouts |
page_load_timeout= and script_timeout=
|
unhandledPromptBehavior, se:downloadsEnabled, webSocketUrl
|
none: selenium-flow needs them |
SET-30. Both vendor blocks are checked whatever browser opens, because stored capabilities
survive a switch of browser. A block that is not an object, args that is not a list of strings
and prefs that is not an object are each a 400 naming the path. A headless flag is refused in
either block: an args entry that reads headless once leading dashes and any =value are
stripped, in any case (--headless, --headless=new, -headless, -HEADLESS), and any
moz:firefoxOptions.env.MOZ_HEADLESS. The message reads <block>.args <arg> cannot be sent in <where>: use headless=true or headless=false instead.
SET-31. A raw or config key that is not owned replaces the other layer's value, raw over config,
and its source is the layer that won. The other browser's vendor block is sent untouched. sent
lists every key with its value and sources in the order: option keys, config and raw keys, the
browser's own block, flow keys.
SET-32. The browser's own vendor block (goog:chromeOptions or moz:firefoxOptions) is merged
and its sources are every layer that fed it. args are listed flow, option, config, raw, with exact
duplicates removed. prefs merge as one object: flow beats config and raw, and raw beats
config. Any other key in the block comes from config, then raw.
SET-33. ignored lists <block>.prefs.<name> for each config or raw pref whose value differs
from the one that won. Args are never ignored. The open's result carries ignored only when it is
not empty.
SET-34. A stored raw key that a later release makes owned is refused, not dropped, on an
explicit open that did not pass capabilities and on a reap's reopen alike. The message adds
; this workspace remembers it, so clear it with open_session(capabilities={}). The same suffix
follows a refused headless flag.
SET-35. A headless flag in session.capabilities stops the server at load with the same
sentence, because a config flag would be a default for headless, which has none.
SET-49. Both browsers open with their save-password prompt switched off by preferences. The
prompt is a browser popup that takes the input focus and keeps it, so every later click and
keystroke goes to the popup and nothing happens, with no error. On Chrome
credentials_enable_service, profile.password_manager_enabled and
profile.password_manager_leak_detection are false. On Firefox signon.rememberSignons is
false. They are among the prefs of SET-28, so a raw or config pref of the same name loses to
them and, when its value differs, is listed in ignored (SET-33).
SET-36. The open sets no client timeout of its own, so it waits as long as the Grid's queue
does. A request the queue gives up on (New session request timed out or Timed out creating session) is a 503 reading no Grid node took this browser before the Grid gave up waiting: it asked for <asked>. The Grid may have no node with these capabilities, or none free; see the
troubleshooting reference.
SET-37. <asked> is browserName, browserVersion, then platformName and every key with a
: outside goog:, moz:, ms:, safari: and se:, those being the keys the Grid matches on.
A scalar is quoted as key=value, anything else as the key alone. A vendor block or proxy is
never quoted.
SET-38. The Grid's own failures (Unable to find owning node for slot, Interrupted when creating the session, An error occurred creating the session, No capabilities found in session request payload, Client has gone away) stay the plain 503 with the Grid's words.
SET-39. Any other SessionNotCreatedException is a node refusing the browser. It is a 400 when
the open sent raw keys or a version the caller owns, and a 503 when it sent neither. The message
carries the node's reason with the Grid's host and build lines removed.
SET-40. A version is the caller's when it came from the call, from Sf-Version or ?version=,
or from this workspace's memory (SET-17 keeps the source across a reap). A version from config alone
is the operator's: it never makes the refusal a 400, and the 503 names session.version. The 400
says where the version came from: from this call's version=, from Sf-Version or ?version= or
remembered by this workspace (version="latest" forgets it). Config capabilities never blame the
caller. latest sends no version, so it is never blamed.
SET-41. A page whose certificate the browser does not trust, on the first page of an open or
on navigate, is Untrusted, a 400 (ERR-17). The message never carries the browser's own text,
which quotes the URL.
SET-42. A script run by execute_script, or an assertion script, that outlives the session's
script timeout is ScriptTimedOut, a 400, on both browsers (ERR-17).
SET-43. A browser an open made is never left behind: anything that fails after the Grid created it (a hook, the window, the first page) quits it, and the failure is what propagates.
SET-44. open_session's result has workspace, browser, version (the version that ran, or
null), url, title, width, height (measured on the new browser), recording, capture,
settings, and when they apply ignored, site_data and flows_here.
SET-45. The result's settings is what this browser opened with: browser, the measured
width and height, a timeout when set, insecure, headless, record and capture only when
true, version as asked (latest included) and capabilities when not empty. The Grid's session
id and sent and ran are never in a caller's result.
SET-46. workspace://current (WS-43) shows the record's settings as stored, which keeps a
flag passed false and the window as asked, and version as it ran beside browser. It shows no
sources.
SET-47. The admin's workspace row carries insecure, headless, set_by (the source of each
setting), asked_version, sent, ran, ended and grid_listed. grid_listed is false when the
Grid's listing failed, and then a row's recording stands on its stored setting instead of
turning off.
SET-48. open_session's description is the prompt a model reads: it presents the named options
as one set, says each is remembered when passed and that an option left out comes from the server's
and connection's defaults at each open, and presents raw capabilities last as the escape hatch.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network