Workflow:SeleniumHQ Selenium Browser Session Setup
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Testing, WebDriver |
| Last Updated | 2026-02-11 23:00 GMT |
Overview
End-to-end process for initializing a W3C WebDriver browser session, navigating to pages, interacting with elements, and cleanly terminating the session across any supported browser and language binding.
Description
This workflow describes the standard procedure for setting up and using a Selenium WebDriver session to automate a web browser. It covers the full lifecycle from configuring browser-specific options (Chrome, Firefox, Edge, Safari), through automatic driver binary discovery via Selenium Manager, to creating a session, performing browser interactions, and properly shutting down. The workflow is the foundational use case for all Selenium-based browser automation and test execution.
Key outputs:
- An active WebDriver session connected to a browser instance
- Ability to navigate, find elements, interact, and extract data
- Clean session termination with resource cleanup
Scope:
- Covers local browser execution (remote Grid execution is a separate workflow)
- Applies to all supported browsers: Chrome, Firefox, Edge, Safari
- Consistent across all language bindings: Java, Python, Ruby, JavaScript, .NET
Usage
Execute this workflow when you need to automate browser interactions for functional testing, scraping, or any web-based task automation. This is the correct starting point when you have a test scenario that requires opening a browser, navigating to URLs, interacting with page elements, and verifying page state.
Execution Steps
Step 1: Configure Browser Options
Create a browser-specific options object to customize the browser session. Options control the browser binary path, command-line arguments (such as headless mode), extensions, proxy settings, and W3C capability preferences.
Key considerations:
- Each browser has its own Options class (ChromeOptions, FirefoxOptions, EdgeOptions, SafariOptions)
- Chromium-based browsers share a common base class for arguments, extensions, and experimental options
- Options are serialized into W3C-compliant capabilities when the session is created
- Common arguments include headless mode, window size, and disabling GPU acceleration
Step 2: Resolve Driver Binary
Locate or download the browser driver executable (chromedriver, geckodriver, msedgedriver) that matches the installed browser version. Selenium Manager handles this automatically.
What happens:
- Selenium Manager is a Rust-based CLI tool bundled with Selenium
- It detects the installed browser version and finds a compatible driver
- Drivers are cached locally (default: ~/.cache/selenium/) for reuse
- If no compatible driver is found in cache, it downloads one automatically
- Platform detection handles Windows, macOS, and Linux variants
Key considerations:
- The SE_MANAGER_PATH environment variable can override the manager binary location
- The SE_CACHE_PATH environment variable controls the cache directory
- For CI/CD, pre-caching drivers avoids network calls during test runs
Step 3: Start Driver Service
Launch the browser driver as a local HTTP server process. The driver service manages the lifecycle of the driver binary, including starting it on an available port, health checking, and eventual shutdown.
What happens:
- A DriverService object is created (or defaulted) for the target browser
- The service finds a free port and starts the driver binary as a subprocess
- Output streams are captured for logging and debugging
- The service polls the driver endpoint until it responds with HTTP 200
Key considerations:
- Each browser has its own DriverService implementation (ChromeDriverService, GeckoDriverService, EdgeDriverService)
- Log level and output file can be configured on the service builder
- Service startup includes a configurable timeout for health checks
Step 4: Create WebDriver Session
Establish a new browser session by sending a POST request to the driver service with the desired capabilities. The driver launches a browser instance and returns a session identifier along with the negotiated capabilities.
What happens:
- A W3C New Session command is sent with capabilities derived from the options
- The driver validates capabilities and launches a browser instance
- A unique session ID is generated and returned
- The response includes the actual capabilities of the created session
- The WebDriver client stores the session ID for all subsequent commands
Key considerations:
- Capability negotiation follows W3C WebDriver specification rules
- Invalid or unsupported capabilities will cause SessionNotCreatedException
- The AcceptedW3CCapabilityKeys predicate validates capability key names
Step 5: Perform Browser Interactions
Use the WebDriver API to navigate to URLs, find elements, interact with page content, and extract information. All commands are sent as HTTP requests to the driver service using the session ID.
What happens:
- Navigation: load URLs, go back/forward, refresh pages
- Element location: find elements by ID, CSS selector, XPath, class name, link text, tag name
- Element interaction: click, send keys, clear, submit forms
- State queries: get text, attributes, CSS values, element visibility, selection state
- JavaScript execution: run synchronous or asynchronous scripts in the browser context
- Window management: resize, maximize, switch between windows and tabs, manage frames
Key considerations:
- Elements are referenced by opaque identifiers that become stale when the DOM changes
- Explicit waits (WebDriverWait) should be used instead of implicit waits or sleep calls
- The SearchContext interface is shared by both WebDriver and WebElement for nested searches
Step 6: Terminate Session
Close all browser windows and end the WebDriver session, releasing all associated resources. The driver service process is also shut down.
What happens:
- The quit() method sends a DELETE request to /session/{id}
- All browser windows and tabs are closed
- The driver service subprocess is terminated
- Temporary files and profiles created for the session are cleaned up
Key considerations:
- Always call quit() in a finally block or test teardown to prevent resource leaks
- The close() method only closes the current window; quit() ends the entire session
- Selenium Manager cleanup hooks run at JVM/process shutdown