webdriver

WebDriver

WebDriver is the W3C standard protocol for controlling web browsers. It is the underlying technology behind Selenium, Appium, WebdriverIO, and more. Even if you use a high-level tool, understanding WebDriver helps debug low-level issues.

When to Use

Direct W3C Browser Protocol Interaction: Interfacing directly with browser automation engines over the standardized W3C WebDriver specification.
Custom Automation Tool Authoring: Building custom test runners, web scrapers, or browser orchestration engines.
Multi-Browser Driver Compatibility: Controlling ChromeDriver, GeckoDriver, SafariDriver, and EdgeDriver over standard JSON HTTP requests.
Low-Level Browser Session Management: Managing browser capabilities, window handles, frame switching, and raw screenshot streams.

Quick Start

import { remote } from "webdriverio";

const browser = await remote({ capabilities: { browserName: "chrome", "goog:chromeOptions": { args: ["headless", "disable-gpu"] }, }, });

await browser.url("https://webdriver.io"); const title = await browser.getTitle(); console.log(title); // outputs: "WebdriverIO · Next-gen browser and mobile automation test framework for Node.js"

await browser.deleteSession();


## Core Concepts

### W3C Standardized Endpoint Endpoints

All actions map to standardized REST endpoints defined in the W3C Recommendation:

```http
POST /session                  # Create new browser session
POST /session/{id}/url         # Navigate to URL
POST /session/{id}/element     # Locate element
POST /session/{id}/element/{el}/click # Click element
DELETE /session/{id}           # Terminate browser session

Raw HTTP Session Orchestration

Interacting with ChromeDriver directly using curl or raw HTTP:

# 1. Start Chrome Session
curl -X POST http://localhost:9515/session \
  -H "Content-Type: application/json" \
  -d '{"capabilities": {"alwaysMatch": {"browserName": "chrome"}}}'
# Returns {"value": {"sessionId": "8f3d1e1c..."}}

# 2. Navigate to URL
curl -X POST http://localhost:9515/session/8f3d1e1c/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

WebdriverIO Standalone Client

Consuming WebDriver directly in TypeScript without full test runner frameworks:

import { remote } from "webdriverio";

const browser = await remote({
  capabilities: { browserName: "chrome" },
});

await browser.url("https://example.com");
const title = await browser.getTitle();
console.log("Page Title:", title);
await browser.deleteSession();

Common Patterns

Remote WebDriver Session with Desired Capabilities

Problem: Running tests against a centralized Selenium Grid or cloud browser provider.

Solution: Configure RemoteWebDriver using standard W3C options:

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

chrome_options = Options()
chrome_options.add_argument("--headless=new")
chrome_options.add_argument("--disable-gpu")

driver = webdriver.Remote(
    command_executor="http://grid-server:4444/wd/hub",
    options=chrome_options
)
driver.get("https://example.com")
print(driver.title)
driver.quit()

Best Practices

Do:

Ensure ChromeDriver and Chrome Major Versions Match: Use automated driver managers or match major version releases strictly.
Always Delete Sessions on Exit: Call DELETE /session/{id} to prevent headless browser processes from leaking memory.
Use W3C Compliant Capabilities: Define capabilities under alwaysMatch and firstMatch according to the W3C spec.
Handle StaleElementReferenceException Gracefully: Re-fetch elements if the underlying DOM re-renders between lookup and action.

Don't:

Use legacy JSON Wire Protocol: JSONWP is deprecated; ensure drivers run in strict W3C mode.
Hardcode local ports: Assign dynamic ports when running parallel browser driver binaries on CI runners.
Leave browser drivers exposed to public networks: Bind driver daemons to localhost (127.0.0.1).

Troubleshooting

Error	Cause	Solution
`WebDriverException: Message: Service chromedriver unexpectedly exited`	Missing system dependencies (glibc, Xvfb) on headless runner.	Install missing libraries or verify driver binary matches architecture.
`MaxSessionException: All nodes are currently busy`	Selenium Grid capacity exceeded by concurrent test jobs.	Increase grid node replicas or configure queue timeouts.
`InvalidSessionIdException`	Browser process crashed or session timed out due to inactivity.	Verify memory usage on host and reduce session idle times.

About this skill