Workflow:SeleniumHQ Selenium Selenium Grid Deployment
| Knowledge Sources | |
|---|---|
| Domains | Distributed_Testing, Infrastructure, Selenium_Grid |
| Last Updated | 2026-02-11 23:00 GMT |
Overview
End-to-end process for deploying Selenium Grid as distributed test infrastructure, enabling parallel browser test execution across multiple machines with centralized session routing, capability-based node matching, and session queue management.
Description
This workflow covers the deployment and operation of Selenium Grid 4, the distributed test execution infrastructure built into the Selenium project. Grid enables running tests on remote machines by routing WebDriver session requests to nodes that match the desired browser capabilities. It supports multiple deployment topologies: Standalone (all-in-one), Hub-and-Node (distributed), and fully distributed with separate Router, Distributor, Session Map, Session Queue, and Event Bus components.
Key outputs:
- A running Grid endpoint that accepts WebDriver session requests
- Distributed browser node pool with automatic capability matching
- Session queue for managing concurrent test demand
- GraphQL API and web UI for monitoring grid status
Scope:
- Covers Standalone, Hub-and-Node, and fully distributed topologies
- Includes session routing, capability negotiation, and node health monitoring
- Supports Docker-based deployment via Selenium Docker images
Usage
Execute this workflow when you need to run browser tests across multiple machines or browsers simultaneously, scale test execution beyond a single machine, centralize browser infrastructure for a team, or integrate browser testing into CI/CD pipelines with remote execution capabilities.
Execution Steps
Step 1: Build the Grid Server
Compile the Selenium Grid server JAR from the monorepo source, or obtain a pre-built release artifact. The Grid is a self-contained Java application.
What happens:
- The Grid server is built via Bazel using the target //java/src/org/openqa/selenium/grid:executable-grid
- The build alias "grid" provides a shortcut: bazel build grid
- The output is a fat JAR containing all Grid components and dependencies
- Release builds use the ./go java:release task with stamping for version metadata
Key considerations:
- Grid requires Java 17 or later at runtime
- The JAR includes an embedded HTTP server (Netty-based)
- All Grid roles (Router, Distributor, Node, Queue, Event Bus) are included in a single JAR
- The Bootstrap class handles JVM startup with optional extension class loading
Step 2: Choose Deployment Topology
Select the appropriate Grid architecture based on scale requirements. Three topologies are supported, each trading simplicity for scalability.
Standalone topology:
- All roles run in a single JVM process
- Simplest setup: single command to start
- Suitable for local development and small teams
- Components: Router, Distributor, Session Queue, Event Bus, and Node
Hub-and-Node topology:
- Hub runs Router, Distributor, Session Queue, and Event Bus
- Nodes register with the Hub and execute sessions
- Nodes can run on separate machines for horizontal scaling
- Suitable for medium-scale deployments
Fully distributed topology:
- Each role runs as a separate process
- Maximum flexibility and fault isolation
- Components communicate via Event Bus (message queue)
- Suitable for large-scale production deployments
Step 3: Configure Grid Components
Set up configuration for the selected topology using TOML configuration files, command-line flags, or environment variables.
What happens:
- Configuration covers network addresses, ports, timeouts, and capability matching
- Node configuration specifies which browsers are available and their maximum concurrent sessions
- Session queue parameters control request timeout and retry behavior
- Optional Redis-backed session storage enables distributed state management via GridRedisClient
Key considerations:
- TOML configuration files provide the most readable format for complex setups
- Network settings must allow communication between Hub/Router and all Nodes
- Browser drivers (chromedriver, geckodriver) must be available on Node machines
- Selenium Manager on Nodes can auto-resolve driver binaries
Step 4: Start Grid Components
Launch the Grid server with the chosen topology. The Bootstrap class routes to the appropriate command handler based on the CLI subcommand.
Standalone start:
- A single process is launched with all roles
- The Standalone command initializes Router, Distributor, local Node, Session Queue, and Event Bus
- A web UI is served at the Grid URL (default port 4444)
Hub-and-Node start:
- The Hub process is started first with the "hub" subcommand
- One or more Node processes are started with the "node" subcommand, pointing to the Hub URL
- Nodes register with the Hub via the Event Bus and advertise their capabilities
Key considerations:
- The Main class acts as the CLI command router dispatching to Standalone, Hub, or individual role commands
- Each role has a default configuration (DefaultStandaloneConfig, etc.) that can be overridden
- Grid health can be verified by checking the /status endpoint
Step 5: Route Session Requests
When a test client sends a new session request, the Grid routes it through the Session Queue to the Distributor, which matches capabilities to available Node slots.
What happens:
- The client sends POST /session with desired capabilities to the Router
- The Router forwards the request to the Session Queue (NewSessionQueue)
- The Distributor polls the queue and matches requests to Node slots via SlotSelector
- A matching Node receives the session creation request and launches a browser
- The session ID and actual capabilities are returned to the client via the Router
- Subsequent commands are routed via the Session Map, which maps session IDs to Node endpoints
Key considerations:
- Capability matching follows W3C rules: browserName, browserVersion, platformName
- Custom capabilities with vendor prefixes (e.g., goog:chromeOptions) are passed through
- If no Node matches, the request stays queued until a slot becomes available or times out
- The Distributor maintains a model of all registered Nodes and their available slots
Step 6: Monitor Grid Status
Track Grid health, active sessions, and node availability through the built-in monitoring interfaces.
What happens:
- The Grid web UI provides a visual dashboard of nodes, sessions, and queue status
- The /status HTTP endpoint returns JSON with component health information
- A GraphQL API enables programmatic queries for sessions, nodes, and capabilities
- Node health checks run periodically to detect and remove unresponsive nodes
Key considerations:
- The web UI is a React application served from the Grid server
- External monitoring tools can poll /status for health checks
- Session timeouts and idle timeouts prevent leaked sessions from consuming slots