JavaScript Execution, Browser Capabilities, Profiles, and Preferences: Diagnostics, Failure Modes, and Production Practices

1. Failure taxonomy

The following table organizes the key choices and evidence for Failure taxonomy. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

2. Diagnostic sequence

1. Preserve first-failure exception, screenshot/DOM/config manifest as available.
2. Confirm Selenium 4.47.0, browser/driver versions, local versus Grid, headed/headless mode.
3. Confirm loopback target, expected test data, current URL/frame/window.
4. Inspect requested options and returned capabilities.
5. Inspect DOM/readiness/interactability before adding scripts.
6. Inspect AUT/browser/network evidence if the script/config depends on them.
7. For remote runs, inspect Grid/CI environment and resource state.
8. Apply the smallest correction at the owning layer.
9. Rerun the smallest controlled scenario once and compare evidence.

3. Intentionally broken example: return a cyclic object

The following script cannot be represented as a normal JSON-like return value because the object refers to itself. Drivers typically surface a JavaScript/serialization failure. The fix is not to retry; return a small plain object containing only the evidence you need.

from selenium import webdriver
from selenium.common.exceptions import JavascriptException

driver = webdriver.Chrome()
try:
    driver.get("http://127.0.0.1:8777/")
    try:
        driver.execute_script("const x = {}; x.self = x; return x;")
    except JavascriptException as exc:
        print("EXPECTED script serialization failure", type(exc).__name__)

    fixed = driver.execute_script("return {title: document.title, ready: !!window.__academyReady};")
    print("FIXED", fixed)
finally:
    driver.quit()

4. Script before app readiness

document.readyState can be complete while application boot remains unfinished. A script that immediately assumes window.__academyReady.state exists can fail with a page-side JavaScript error. Repair by waiting on the app contract using an explicit WebDriver condition or the bounded app-owned async callback demonstrated earlier—not by adding a giant sleep.

5. JS click hiding an interactability bug

If element.click() reports interception but execute_script("arguments[0].click()", element) “works,” you have evidence that the script bypassed WebDriver semantics. Preserve the screenshot and inspect overlays, animation/readiness, disabled state, scroll position, or wrong element targeting. Repair the cause; do not keep the forced click.

6. Never concatenate untrusted values into script source

Arguments supplied to execute_script() are transported separately from the script source. Use them instead of generating code strings from runtime/test data.

synthetic_value = "academy'; not-code"
output = driver.find_element(By.ID, "draft")
# Safe transport: data is an argument, not source text.
driver.execute_script("arguments[0].textContent = arguments[1];", output, synthetic_value)

This example changes only a disposable lab output node. For business-state setup, prefer a supported API/fixture instead of page mutation.

7. Invalid capability: negotiation is supposed to fail

W3C capabilities require recognized standard names or vendor-prefixed extension names. An arbitrary unprefixed key can be rejected by the driver/remote end. That failure is useful: it prevents silent configuration drift.

from selenium import webdriver
from selenium.common.exceptions import WebDriverException

options = webdriver.ChromeOptions()
options.set_capability("academyMadeUpCapability", True)  # deliberately invalid/unprefixed
print("requested", options.to_capabilities())
try:
    webdriver.Chrome(options=options)
except WebDriverException as exc:
    print("EXPECTED capability negotiation failure", type(exc).__name__)

# Repair: remove the unsupported key; use a documented standard capability
# or a correctly namespaced browser-vendor option only when required.

8. Invalid or ignored browser preference

Some browser preferences are version-, policy-, or environment-dependent. An invented key such as academy.nonexistent.preference may simply be stored/ignored rather than producing a useful browser effect. Treat “session started” as insufficient evidence. If the requested option appears in options.to_capabilities() but runtime behavior does not change, do not keep adding random flags. Confirm the browser vendor documentation, enterprise policy, profile path, and whether the preference is valid for this browser/version.

9. Profile lock/contention is an ownership failure

Two browser sessions must not write the same profile directory. Depending on browser/platform, the second session may fail to start, create corruption risk, or behave unpredictably. The production fix is not a retry loop; allocate one disposable profile per session/worker.

from pathlib import Path
import tempfile

worker_id = "worker-03"  # synthetic framework/CI worker identifier
root = Path(tempfile.mkdtemp(prefix=f"selenium-{worker_id}-"))
profile = root / "profile"
profile.mkdir()
print("exclusive profile", profile.resolve())
# Pass only this worker's profile to its browser; never share it with another session.

10. Capability applied at the wrong layer

A CI environment variable named PAGE_LOAD=eager does nothing by itself. The test/bootstrap code must read it, validate it, and set options.page_load_strategy before session creation. Conversely, an AUT feature flag should not be stuffed into browser capabilities merely because capabilities are convenient.

11. Performance: attribute cost to the right layer

Separate test-runner overhead, browser/profile startup, navigation/page-load blocking, AUT/network latency, script execution, evidence I/O, and Grid queue time. A faster pageLoadStrategy does not fix slow application readiness; a persistent shared profile might reduce startup cost but destroy isolation. Measure before changing semantics.

12. Security-sensitive configuration

Proxy credentials, profile contents, extensions, certificate overrides, browser binary paths, remote Grid endpoints, and cloud capability metadata can be sensitive. Use fake values in labs, avoid logging secrets, keep Grid private, and do not experiment with production accounts or trust settings.

13. Summary and next step

Configuration incidents become tractable when you preserve the first failure and identify the owning layer. Scripts fail because of page readiness/return contracts; capabilities fail during negotiation; preferences fail at browser/policy layers; profiles fail from ownership contention.

Knowledge check

Official references and version notes

• Selenium 4.47 release notes — stable baseline pinned for this chapter.
• Selenium downloads — stable bindings/Grid versus 4.48 snapshot artifacts.
• Python WebDriver API — synchronous/asynchronous JavaScript execution and session capabilities.
• Browser options — standard capabilities including page-load strategy and insecure-certificate behavior.
• Chrome-specific functionality — Chromium option/configuration boundary.
• Python Chrome Options API — arguments, experimental options, capabilities, and to_capabilities().
• Python common Options API — page-load strategy and cross-browser option properties.
• Avoid sharing state — fresh-session isolation guidance.