Build remote Selenium capabilities without stringly typed surprises

A Chrome job works on a laptop but waits in Grid until the session request times out. CI says it requested Linux, Chrome 126, and headless=false; the actual JSON contains a string version, a truthy headless flag, and a top-level capability named headless that WebDriver does not recognize. The failure was assembled before Selenium sent its first command.

A useful capability builder does not make dictionaries convenient. It turns untrusted configuration text into one valid, inspectable session request and refuses ambiguous input before a scarce Grid slot is involved.

Understand what the remote end receives

Creating a remote driver begins with a new-session request. Selenium's Python binding converts a browser Options object into capabilities, then sends those capabilities to the remote WebDriver endpoint. The remote end processes the W3C alwaysMatch and firstMatch structure, selects a matching configuration, starts a browser, and returns the effective capabilities for the created session.

That sequence has three representations worth keeping separate:

1. CI inputs are strings, secrets, and job-matrix values.
2. Requested capabilities are the serialized WebDriver contract.
3. Returned capabilities describe what the server actually created.

Logging only the first representation is weak evidence. A line that says HEADLESS=false does not tell you whether the framework parsed the string correctly or placed it under the browser's options object. Logging only the third representation is too late when no session was created. A disciplined builder can produce a sanitized view of the second representation before the request and compare selected fields with the third after success.

Standard capability names include browserName, browserVersion, platformName, acceptInsecureCerts, pageLoadStrategy, and timeout settings defined by WebDriver. Browser-specific configuration belongs in a vendor namespace such as the Chrome options capability generated by ChromeOptions. Extension capability names must contain a colon. A bare top-level key like headless is neither a standard WebDriver capability nor a valid extension name.

Headless mode illustrates the distinction. It is a Chrome startup argument, so Selenium places it inside Chrome's vendor-specific options. It is not a Grid matching promise by itself. platformName, on the other hand, participates in matching when the Grid's slot stereotypes declare platforms. Treating every setting as a flat key confuses browser startup with Grid allocation.

The server does not have to echo the request exactly. If a request omits browserVersion, the server can select an available version and return the resolved value. Returned Chrome capabilities often include details that the client never requested. The comparison should assert the contract your test relies on, such as browser name and platform family, while recording the full sanitized result for diagnosis.

Local and remote execution can also assign different meaning to a version request. A local binding may invoke Selenium Manager when no driver is supplied and may manage a requested browser version. A Grid matches the request against registered slots and its own provisioning model. A value that causes local browser management does not guarantee a remote Grid has a corresponding slot.

The alwaysMatch and firstMatch names explain another class of confusing errors. Values in alwaysMatch apply to every candidate. Each object in firstMatch represents an alternative that can be merged with those required values. The remote end evaluates candidates in order and chooses the first one it can satisfy. If the same capability name appears in both parts for one candidate, the request is invalid rather than an override.

Most Python suites should let Selenium serialize a single browser Options object instead of hand-building that wire structure. Manual construction is justified when a framework truly needs alternatives in one new-session request, but it raises review costs. The author must prove which fields are mandatory, which combinations are legal, and how the selected alternative will be recognized in the returned capabilities. Sending separate, explicit matrix jobs is often easier to report than asking one request to mean "Chrome here or Firefox there."

Timeout capabilities deserve similar care. WebDriver timeouts control script execution, page loading, and implicit element lookup after a session exists. They do not configure how long Grid will keep a request in its new-session queue. A builder that exposes one generic TIMEOUT field invites an engineer to change the wrong layer. Name each timeout after the boundary it controls, and leave Grid queue policy in Grid configuration.

Convert environment text into a typed request

Environment variables are a transport format, not a configuration model. Parse them once at process startup. A frozen data class gives the rest of the test framework real booleans and constrained values instead of repeated calls to os.getenv scattered across fixtures.

from __future__ import annotations

import os
from dataclasses import dataclass
from urllib.parse import urlparse


def parse_bool(name: str, default: bool) -> bool:
    raw = os.getenv(name)
    if raw is None:
        return default

    normalized = raw.strip().lower()
    if normalized in {"true", "1", "yes"}:
        return True
    if normalized in {"false", "0", "no"}:
        return False
    raise ValueError(
        f"{name} must be true/false, 1/0, or yes/no; got {raw!r}"
    )


@dataclass(frozen=True, slots=True)
class RemoteChromeConfig:
    remote_url: str
    platform_name: str | None
    browser_version: str | None
    headless: bool
    accept_insecure_certs: bool
    page_load_strategy: str


def load_remote_chrome_config() -> RemoteChromeConfig:
    remote_url = os.environ["SELENIUM_REMOTE_URL"].strip()
    parsed_url = urlparse(remote_url)
    if parsed_url.scheme not in {"http", "https"} or not parsed_url.hostname:
        raise ValueError("SELENIUM_REMOTE_URL must be an absolute HTTP(S) URL")

    strategy = os.getenv("PAGE_LOAD_STRATEGY", "normal").strip().lower()
    if strategy not in {"normal", "eager", "none"}:
        raise ValueError("PAGE_LOAD_STRATEGY must be normal, eager, or none")

    platform = os.getenv("PLATFORM_NAME", "").strip() or None
    version = os.getenv("BROWSER_VERSION", "").strip() or None

    return RemoteChromeConfig(
        remote_url=remote_url,
        platform_name=platform,
        browser_version=version,
        headless=parse_bool("HEADLESS", True),
        accept_insecure_certs=parse_bool("ACCEPT_INSECURE_CERTS", False),
        page_load_strategy=strategy,
    )

There is intentionally no extra_capabilities dictionary. Every accepted value has a type, a default, and a validation rule. Adding a field becomes a code review event. That friction is useful when the field changes browser selection or security behavior.

Defaults need provenance. HEADLESS=true may be a sensible CI default and a surprising workstation default. Resolve that policy in one place and print the effective non-secret value. Do not let three layers supply competing defaults, such as a workflow, a shell script, and the Python parser. An engineer investigating a run should be able to identify whether a value was explicitly supplied or inherited.

Empty text is another policy decision. The loader above treats an empty platform or version as absent, which lets one workflow omit a restriction. It does not treat an empty boolean as false because that could hide a missing matrix substitution. A blank HEADLESS value is rejected. Apply this rule consistently: emptiness can mean "not requested" for optional strings, but it should not silently choose one side of a security or execution toggle.

Avoid overvalidation too. Platform names and browser-version formats depend on the remote service. Rejecting every value except linux, windows, and mac would make a generic client less portable and could reject a legitimate provider label. The builder should validate what it owns, such as empty strings and booleans, while letting the target service validate its documented vocabulary.

Construct ChromeOptions through public Selenium APIs:

from selenium.webdriver.chrome.options import Options


def build_chrome_options(
    config: RemoteChromeConfig,
    test_name: str,
) -> Options:
    options = Options()
    options.accept_insecure_certs = config.accept_insecure_certs
    options.page_load_strategy = config.page_load_strategy

    if config.platform_name is not None:
        options.platform_name = config.platform_name
    if config.browser_version is not None:
        options.browser_version = config.browser_version
    if config.headless:
        options.add_argument("--headless=new")

    # Selenium Grid displays this metadata in its UI and GraphQL data.
    options.set_capability("se:name", test_name)
    return options

Using options.browser_version and options.platform_name keeps standard capabilities visible. add_argument lets ChromeOptions put the headless switch in the correct vendor-specific structure. set_capability is appropriate for the namespaced Grid metadata field.

Do not set browserName to a second value through a generic merge. ChromeOptions already identifies Chrome. Conflicting values in overlapping capability objects can cause an invalid-argument response before matching. The W3C rules reject duplicate keys between alwaysMatch and a firstMatch entry rather than guessing which value should win.

Provider options need the same discipline. If a cloud service documents an extension object, create a typed provider-specific adapter and put only its documented fields under its documented namespace. Do not invent a universal vendor:options key. Namespaced syntax makes a capability structurally valid, but it does not make an unknown provider interpret it.

Keep the request and the result in the same record

A pytest fixture is a useful ownership point. It has the test node ID, creates one session, records the request, records the effective result, and closes the session. Sanitization must happen before output because remote URLs and provider options may carry credentials.

from __future__ import annotations

import json
from collections.abc import Iterator

import pytest
from selenium import webdriver
from selenium.webdriver.remote.webdriver import WebDriver


def printable_capabilities(values: dict[str, object]) -> str:
    redacted = dict(values)
    for key in ("accessKey", "token", "password"):
        if key in redacted:
            redacted[key] = "[redacted]"
    return json.dumps(redacted, sort_keys=True, default=str)


@pytest.fixture
def driver(request: pytest.FixtureRequest) -> Iterator[WebDriver]:
    config = load_remote_chrome_config()
    options = build_chrome_options(config, request.node.nodeid)
    requested = options.to_capabilities()
    print(f"requested_capabilities={printable_capabilities(requested)}")

    remote = webdriver.Remote(
        command_executor=config.remote_url,
        options=options,
    )
    print(f"session_id={remote.session_id}")
    print(
        "returned_capabilities="
        f"{printable_capabilities(remote.capabilities)}"
    )

    try:
        yield remote
    finally:
        remote.quit()

The simple redactor is adequate only for this narrow standard request. A provider object can nest credentials, so a production redactor should recursively match an allowlist or known secret fields. Better still, keep authentication in the endpoint client configuration or CI secret mechanism and out of capabilities entirely when the provider supports it.

Pytest captures standard output by default. On a failure, the report retains these lines; during a focused investigation, -s shows them live. Structured logging is preferable in a large suite, but preserve the same fields: test node ID, requested capabilities, session ID if one exists, returned capabilities, and teardown outcome.

After success, assert only meaningful invariants. A test that requested Chrome should fail fast if driver.capabilities["browserName"] reports another browser. A broad version request such as 126 may legitimately return a full build number. Compare the major version when that is your contract. Do not assert every server-added field, because node upgrades will create noise without changing coverage.

Call the contract assertion immediately after session creation, before a page object or application fixture runs. If it fails, classify the job as environment setup rather than a product failure. Still execute quit() through the fixture's finally block. A wrong but live session consumes capacity just like a correct one.

Keep the raw request and comparison result attached to the same test attempt. A rerun can land on a different node and return a different patch version. Overwriting the first record with the passing attempt destroys evidence that the Grid inventory or routing was inconsistent. Session ID is the join key for server logs; test node ID is the join key for pytest output.

One practical check makes misrouting obvious:

def assert_session_contract(
    driver: WebDriver,
    config: RemoteChromeConfig,
) -> None:
    actual = driver.capabilities
    if actual.get("browserName") != "chrome":
        raise AssertionError(f"expected chrome, got {actual.get('browserName')!r}")

    if config.browser_version:
        requested_major = config.browser_version.split(".", 1)[0]
        actual_version = str(actual.get("browserVersion", ""))
        actual_major = actual_version.split(".", 1)[0]
        if requested_major.isdigit() and actual_major != requested_major:
            raise AssertionError(
                f"requested Chrome {requested_major}, got {actual_version!r}"
            )

    if config.platform_name:
        actual_platform = str(actual.get("platformName", ""))
        if actual_platform.lower() != config.platform_name.lower():
            raise AssertionError(
                f"requested platform {config.platform_name!r}, "
                f"got {actual_platform!r}"
            )

The version comparison deliberately handles numeric major requests only. Labels such as stable, beta, or provider-specific values cannot be verified by comparing the returned string to the label. Define a separate policy if your service supports those labels instead of forcing them through a numeric assertion.

Tell matching failures from similar startup failures

A missing session ID is the first important boundary. If webdriver.Remote raises before returning, no test command reached an application page. Preserve the exception type, remote response, elapsed session-creation time, and serialized request.

An InvalidArgumentException that names an unrecognized capability points to request shape or unsupported vocabulary. Inspect options.to_capabilities(). If headless appears at the top level, move it into ChromeOptions with add_argument. If a custom key lacks a colon, either use the service's documented namespace or remove it.

A request that remains queued has a different mechanism. Grid accepted the new-session request but has not found an available compatible slot. Check Grid status for registered nodes and stereotypes, then compare browser name, version, and platform with the request. A version can be installed on a node but absent from its advertised stereotype, so checking the executable alone is insufficient.

A matched slot can still fail while starting the browser. In that case Grid or node logs usually show allocation followed by a driver-process or browser-process error. Common causes include an incompatible driver, a missing browser binary, an unwritable profile directory, insufficient shared memory, or a crashed browser. Loosening capabilities may send the request to another slot and make the symptom disappear, but it does not repair the unhealthy node.

Here are three worked failures that often get combined under "bad capabilities."

First, CI provides HEADLESS=false, and framework code uses bool(os.getenv("HEADLESS")). The value is a non-empty string, so Python produces True. The session starts successfully in headless mode. There is no Grid error. The proof is the serialized Chrome argument and the absence of a visible browser where one was expected. Explicit boolean parsing fixes it; the trade-off is that formerly tolerated spellings now fail the job early.

Second, a matrix requests BROWSER_VERSION=126, while the Grid has only Chrome 125 and 127 slots. The request can wait until the queue timeout because no stereotype matches. Removing the version makes the job pass on 127, but coverage has changed. The honest choices are to add a 126 slot, update the matrix, or deliberately broaden the test contract and report the returned version.

Third, the endpoint is behind a proxy that returns an HTML login page or an HTTP 401. Client output may still say that session creation failed. Capabilities are not the first broken boundary. Capture the HTTP status safely, verify the configured URL without printing embedded credentials, and check whether /status reaches Selenium. A capability edit cannot repair authentication or routing.

A fourth near-miss involves acceptInsecureCerts. A team enables it to get past a certificate error in a test environment, and the session begins working. That result proves the browser accepted a certificate it would otherwise reject. It does not prove the certificate deployment is healthy. The trade-off is reduced production fidelity and the possibility of concealing an expired, misnamed, or incomplete certificate chain. Keep the option false for coverage intended to exercise real trust behavior, and use it only for environments whose certificate exception is an explicit test precondition.

Page-load strategy can create a similarly deceptive pass. Changing from normal to eager returns navigation control after the document is interactive without waiting for all resources. A job that previously timed out may continue, but elements backed by late scripts can still be unavailable. Measure navigation time and wait for the application condition that matters. Do not describe eager as a faster equivalent of normal; it changes the point at which Selenium considers navigation complete.

Provider extension errors sit between syntax and service policy. A correctly namespaced object can still contain an unsupported region, tunnel name, or account feature. The W3C layer permits the extension key, then the provider rejects its contents. Preserve the provider's response and validate only fields covered by its current official documentation. Copying an option from another provider because both use Selenium creates a structurally neat request with the wrong contract.

Use a small smoke test to separate endpoint health from the application suite:

curl --fail --silent --show-error \
  "${SELENIUM_REMOTE_URL%/}/status"

pytest -q -s tests/smoke/test_remote_session.py::test_session_contract

Some hosted services do not expose the standard Grid status endpoint, so a failed /status call is not universal proof of outage. Follow the service's documented health check. The focused session test remains valuable because it uses the same authentication and capability path as the suite without adding application fixtures.

Record elapsed time around session creation. An immediate 400 response supports invalid input. A long wait ending at the configured Grid session-request timeout supports queue or matching investigation. A quick allocation followed by a browser startup exception supports node investigation. Timing does not prove the cause alone, but it tells you which evidence to collect next.

Roll the builder into CI without hiding coverage changes

Begin by running the new parser in observation mode against current CI values. Build the options and print the sanitized request, but let the existing driver factory create the session. Compare the two for a week of job variants. This exposes undocumented inputs before the new builder starts rejecting them.

Next, migrate one browser and one Grid target. Keep requested and returned fields in the report. Disable automatic retries for the focused rollout job, because a retry can land on a different node and conceal a stereotype or startup problem. Once the route is stable, apply the normal retry policy while retaining every attempt's session record.

Make matrix values explicit and quoted. YAML has its own scalar typing rules, while environment variables ultimately arrive as text. Quoting communicates that the Python parser owns conversion:

jobs:
  remote-chrome:
    strategy:
      fail-fast: false
      matrix:
        platform: ["linux"]
        chrome: ["126", "127"]
    env:
      SELENIUM_REMOTE_URL: http://127.0.0.1:4444
      PLATFORM_NAME: ${{ matrix.platform }}
      BROWSER_VERSION: ${{ matrix.chrome }}
      HEADLESS: "true"
      ACCEPT_INSECURE_CERTS: "false"
      PAGE_LOAD_STRATEGY: "normal"
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install --requirement requirements.txt
      - run: pytest -q tests/remote

The matrix above is only valid when the Grid really offers those versions. Do not copy it as a promise about public images. The Grid inventory and CI matrix should be updated in one reviewed change, with a smoke session proving each requested combination.

Version the configuration contract alongside test code. If PAGE_LOAD_STRATEGY was previously free text and becomes constrained, announce the accepted values and fail with a message that names the offending variable. Silent fallback to normal turns a typo into different navigation behavior.

Keep one escape hatch only if you have a named owner and a removal plan. Teams sometimes need a provider-specific field before a typed adapter is ready. A temporary JSON merge should be restricted to a namespaced object, recursively redacted, and prevented from overwriting standard capabilities. Without those limits, the escape hatch becomes the permanent API.

The builder itself deserves unit tests because it has no browser dependency. Cover unset defaults, whitespace, each accepted boolean spelling, rejected booleans, invalid URLs, invalid page-load strategies, and the exact result of to_capabilities(). Do not snapshot the entire dictionary if binding updates add harmless defaults. Assert the keys whose placement and type matter.

One unit test should demonstrate the original boolean bug instead of merely checking happy paths. Set HEADLESS=false, build the options, and assert that the Chrome argument list does not contain the headless switch. Another should set a numeric browser version and verify that browserVersion remains a string. A third should verify that se:name contains the pytest node ID, because losing that metadata makes Grid-side correlation harder even though the session still works.

Add a contract smoke job for each supported target, but keep it separate from product tests. The smoke job creates a session, runs assert_session_contract, loads a neutral page, and quits. If it fails, the product suite can be skipped or marked blocked by infrastructure without producing hundreds of duplicate errors. The trade-off is an extra session per target and a little pipeline latency. That cost is usually lower than diagnosing a wall of failures caused by one malformed request.

When the Grid inventory changes, run old and new capability contracts side by side for a short window. For example, request Chrome 126 and 127 in separate jobs, record the returned versions, then remove 126 only after its coverage consumers move. Do not change the Grid image, builder defaults, and test matrix in one opaque deployment. Separate records make it possible to tell a client contract change from a node provisioning change.

Accept the trade-offs and stop before abstraction takes over

Strict parsing moves failures earlier, which is good for diagnosis but can break jobs that relied on accidental coercion. A team may discover that False, FALSE, empty strings, and misspellings all behaved differently. Publish the contract, add clear errors, and migrate matrix values before enforcing it everywhere.

Centralization creates coupling. One builder for local Chrome, Grid Chrome, Firefox, mobile relays, and several cloud providers tends to accumulate conditional branches and meaningless optional fields. Prefer a small shared parser plus browser-specific and provider-specific adapters. Code duplication is cheaper than a universal object nobody can reason about.

Capability logging can expose secrets and internal topology. Remote URLs may embed credentials. Provider extension objects may include access keys. Returned capabilities can contain debugger addresses, node names, profile paths, or service metadata. Store the minimum needed for the incident, redact recursively, and apply the same retention policy as other CI artifacts.

Do not use a builder to disguise an intentionally flexible exploratory script. If an engineer is manually trying one documented provider capability, a direct Options object beside the experiment is clearer. Promote fields into the builder only when CI or multiple tests depend on a stable contract.

Avoid asserting returned values that do not affect test meaning. A patch-level browser build can change during a qualified image refresh. Pinning and asserting the complete string adds maintenance without necessarily adding coverage. Conversely, do assert a major version when the test exists to cover that release.

Finally, do not "fix" a Grid mismatch by deleting every restrictive capability. That reduces queue failures by allowing any slot, but it may send a Windows-only test to Linux or a regression test to the wrong browser. Every relaxed field is a coverage decision. Put that decision in the matrix and report the effective session, rather than letting a convenient builder quietly make it for you.