Selenium Grid 4 Router Distributor Node Architecture

Architecture note on Selenium Grid 4 distributed WebDriver execution with Router Distributor Node for parallel browser tests covering requirements minimal design trust boundaries operational checks and failure modes.

Problem: distributed WebDriver execution without client knowledge of node locations

Teams need parallel test execution across multiple browsers and operating systems, isolated sessions per test, and a single entry point that hides node locations from test code. The useful takeaway is that Selenium Grid 4 separates concerns into Router, Distributor and Node roles.

Requirements for distributed execution

Parallel test execution across browsers and OSes with session isolation per test.
A single client entry point so test code does not need to hard-code node addresses.
Dynamic scaling of browser capacity by adding or removing Nodes.
Session creation based on advertised capabilities, with commands proxied back to the client.

Smallest suitable design

Grid 4 uses a three-role topology. Router receives new session requests and proxies commands. Distributor matches requests to Nodes. Node runs browsers and executes WebDriver commands.

Session flow: Client to Router to Distributor to Node for creation. Subsequent WebDriver commands flow Client to Router to Node; the Distributor is not in the data path after session assignment.

Minimal deployment options:

Standalone mode: one Java process runs Router, Distributor and Node together for local validation.
Separate processes: Router, Distributor and Node run as distinct processes or containers for production.

java -jar selenium-server.jar router --port 4444\njava -jar selenium-server.jar distributor --port 5556\njava -jar selenium-server.jar node --distributor http://:5556 --port 5557

Replace with the reachable address of the Distributor. Nodes register via heartbeat. The Grid status UI at the Router address shows registered Nodes and their capabilities.

Trust and data boundaries

Client space is untrusted: test code and WebDriver commands originate from CI jobs or developer machines.

Control plane is trusted infrastructure: Router and Distributor hold session metadata, routing tables and queue state. They should run in a secured network segment with access controls.

Node execution is semi-trusted sandbox: browser processes run on Nodes. Capabilities and session metadata cross network boundaries. Test data should not be logged by Grid. Avoid logging request bodies or screenshots in Grid logs.

Grid does not provide transport encryption itself. Protect secrets and test traffic with external TLS termination and network controls such as mTLS between Router and Distributor and between Distributor and Nodes.

Operational checks

Node heartbeat and readiness reporting. A Node that stops heartbeating is removed from the pool. Check the Grid UI or distributor metrics for registration churn.

Session queue length and wait time. Growing queue indicates capacity starvation for a capability set.

Active session count per Node. Sustained high utilization suggests need for additional Nodes with matching capabilities.

Log monitoring for node registration churn and distributor errors. Sudden deregistration often precedes session loss.

Failure modes

Node crash or OOM causes in-flight session loss. The client receives a WebDriver error and must recreate the session. No automatic session migration exists.

Network partition between Router and Distributor leads to session creation failures. Existing sessions that already have a Node route may continue until the connection drops.

Capability starvation when demand exceeds registered browser types. Requests queue or time out. This is visible as increased wait time in the queue metrics.

Browser mismatch. Nodes require browsers matching advertised capabilities to be preinstalled. If a capability is advertised but the binary is missing, session creation fails at the Node.

Conditions that change the design

Multi-tenant isolation needs. Per-tenant queues or separate Grid instances prevent capability contention and noisy neighbor effects.

Strict security requirements. Add mTLS between components, network segmentation for Nodes, and TLS termination in front of Router. Consider running Nodes in isolated containers with restricted egress.

Session affinity requirements. For tests needing sticky routing or session pinning, avoid designs that rebalance sessions. Grid 4 does not provide built-in session affinity; design changes may include a dedicated Node pool per test suite.

Limitations and practical verification

Grid does not automatically install browsers on Nodes. Provisioning must ensure browser versions match the capabilities you advertise.

Transport encryption is external. Verify TLS is enforced at the ingress and between internal components.

Start a minimal Grid deployment and observe node registration and session creation via the Grid status UI to confirm Router-Distributor-Node topology is active.
Run parallel WebDriver sessions with different capabilities and confirm they are allocated to distinct Nodes and can execute commands concurrently.
Simulate node removal by stopping a Node process and verify new session creation fails or recovers as expected while existing sessions are terminated.

Selenium Grid 4 Router Distributor Node Architecture for Parallel Browser Tests