skip to content

In Selenium 4, which capability keys does a new-session request use to ask for a specific browser?

level: juniorimportance: should knowfreq 68%

answer

  1. Four keys decide, the rest configure
  2. Named in the new-session capabilities object
  3. A missing key is not a default
  4. Browser, version, platform, certificate tolerance
  5. A colon in a name means extension

basics

~10 s

browserName names the browser, browserVersion asks for a build, platformName asks for an operating system, and acceptInsecureCerts asks to tolerate bad certificates. Any key you leave out places no constraint at all.

solid answer

~40 s

Selenium 4 sends one `capabilities` object on `POST /session`, and the browser is chosen by standard W3C keys inside it. `browserName` picks the browser, with string values such as `chrome`, `firefox`, `MicrosoftEdge` or `safari`; `browserVersion` narrows it to a build; `platformName` names the operating system in lower case, such as `linux` or `windows`; and `acceptInsecureCerts` asks the browser to load pages behind an invalid certificate. These four are compared by the remote end, so a mismatch means no session. Anything you omit is not defaulted - it simply places no requirement, so a request naming only `browserName` accepts any version on any platform. Other keys in the same object, such as `pageLoadStrategy` and `timeouts`, configure the session rather than choose it, and the response returns a second `capabilities` object describing what you actually got.

code

java · 22 lines
java
import java.net.URI;
import org.openqa.selenium.Capabilities;
import org.openqa.selenium.MutableCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;

public class TicketQueueSession {
  public static void main(String[] args) throws Exception {
    MutableCapabilities requested = new MutableCapabilities();
    requested.setCapability("browserName", "chrome");
    requested.setCapability("acceptInsecureCerts", true);

    RemoteWebDriver driver =
        new RemoteWebDriver(URI.create("http://localhost:4444").toURL(), requested);
    try {
      driver.get("https://tickets.example.com/queue");
      Capabilities negotiated = driver.getCapabilities();
      System.out.println(negotiated.getBrowserName() + " " + negotiated.getBrowserVersion());
    } finally {
      driver.quit();
    }
  }
}

go deeper

for a junior

Recall the four keys that choose a browser - browserName, browserVersion, platformName and acceptInsecureCerts - and that anything you leave out places no constraint at all.

for a middle

Explain which keys the remote end compares during matching and which merely configure the session, and why the capabilities that come back differ from the ones you sent.

for a senior

Demonstrate putting the negotiated capabilities into run records, so a failure can be attributed to a browser and build without rerunning the suite to find out.

for a principal

Set the standard for what suites across a fleet are allowed to request, so capability maps do not drift into per-team dialects nobody can reconcile later.

## Where capabilities live in the protocol Every Selenium 4 session begins with one `POST /session` request whose body is a `capabilities` object, and everything you can ask for about the browser is a **capability**: a named key with a JSON value. Keys defined by the W3C WebDriver specification are **standard capabilities** and carry no prefix; anything a vendor adds is an **extension capability** and carries one. A support-ticket queue suite that wants Chrome on Linux, tolerating the staging server's self-signed certificate, expresses all three wishes as three keys in that one object. There is no other channel: no client-side switch and no file the remote end reads on your behalf. ## The keys that choose a browser Four standard keys decide whether a session can be created at all. | Key | Type | What it asks for | Omitting it means | |---|---|---|---| | `browserName` | string | the browser to launch, spelled `chrome`, `firefox`, `MicrosoftEdge` or `safari` | any browser the other side offers can serve the request | | `browserVersion` | string | a particular browser build | any version is acceptable | | `platformName` | string | the operating system, in lower case, such as `linux` or `windows` | any operating system is acceptable | | `acceptInsecureCerts` | boolean | permission to load pages behind an invalid or self-signed certificate | certificate errors are not tolerated | Two things in that table trip people up on their first Selenium 4 suite: - **An absent key is not a default; it is the absence of a requirement.** Sending only `browserName` does not quietly pin the version you happen to have locally. - **The values are compared as strings**, so `Chrome` is not `chrome`, and the Edge browser name is `MicrosoftEdge` rather than `edge`. ## Keys that configure rather than choose Other standard keys ride in the same object but do not decide which browser you get. They configure the session that is created: - `pageLoadStrategy` — a string carried in the map that the created session then honours. - `timeouts` — an object whose members are `implicit`, `pageLoad` and `script`, each a number of milliseconds, so a session can start already configured rather than being adjusted by a later call. - Further standard keys cover proxying, window sizing, prompt handling and the BiDi socket. Getting one of these wrong rarely stops a session from starting; it changes how the session behaves once your ticket-queue test is already running, which is a slower and more confusing kind of failure than a session that never opens. ## Standard names versus prefixed names An **extension capability** is a key whose name contains a colon, and the part before the colon is its namespace. `goog:chromeOptions` and `moz:firefoxOptions` carry browser-specific settings for Chrome and Firefox, and the `se:` namespace belongs to Selenium's own Grid. The prefix exists so a remote end that has never heard of a particular key can tell a vendor extension apart from a standard capability it ought to have implemented. The shape is the thing to recognise: no colon means the specification defines it and every remote end understands it; a colon means somebody's extension. ## Reading back what you were actually given The new-session response carries a `sessionId` and a second `capabilities` object, and that object describes the session that was actually created rather than echoing what you asked for. Ask for `browserName` alone and the answer comes back with `browserVersion` and `platformName` filled in with real values. In Java that object is `driver.getCapabilities()`, and the `Capabilities` it returns exposes `getBrowserName()`, `getBrowserVersion()` and `getPlatformName()`. Printing those three at the start of a ticket-queue run costs one line and answers "which browser was this?" a week later without a rerun. ## Where this goes wrong first 1. Asking for a `browserVersion` that no longer exists because the machines updated overnight. The request is perfectly well formed and still cannot be served; the answer is `session not created` and no browser ever starts. 2. Spelling a browser name the way a person would rather than the way the specification does, then wondering why a remote end that clearly has Edge refuses the request. 3. Assuming a capability that was accepted was also honoured. A key the other end ignores is not the same as a key it applied, which is why reading the response back matters more than checking your own request. 4. Treating `acceptInsecureCerts` as a general "skip the security problem" switch. It tolerates certificate errors on the pages the session loads, and nothing else. The through-line is simple: capabilities are a request, the response is the answer, and a suite that never reads the answer is guessing about the browser it just tested.

  • If you send only browserName, what version and platform do you get?
    Whatever the remote end offers. An absent capability places no constraint, so the request accepts any `browserVersion` on any `platformName`. The response's `capabilities` object reports what was actually created, so read `getBrowserVersion()` and `getPlatformName()` from it when the run needs to record which browser it tested.
  • What tells you a capability key is an extension rather than a standard one?
    The colon. Standard keys defined by the W3C WebDriver specification, such as `browserName` and `acceptInsecureCerts`, carry no prefix. An extension key's name contains a colon whose left-hand side names the namespace, as in `goog:chromeOptions`, `moz:firefoxOptions` and Selenium's own `se:` keys.

saying these in an interview costs you the question

  • Thinks capabilities come from a client flag or config file rather than the new-session request
  • Spells the Edge browser name as edge instead of MicrosoftEdge
  • Assumes omitting browserVersion pins the version installed locally
  • Cannot tell a standard key from a prefixed extension key such as goog:chromeOptions
  • Treats the returned capabilities as an echo of the request rather than what was created