Selenium Grid Architecture is the structure used by Selenium Grid to distribute WebDriver test execution across different machines, browsers, operating systems, and environments. It allows automation tests to send browser commands to remote machines instead of running every test only on the local computer.
Selenium Grid is especially useful for parallel testing, cross-browser testing, cross-platform testing, distributed execution, and scalable automation frameworks. In Selenium Grid 4, the architecture is built from several components such as Router, Distributor, New Session Queue, Session Map, Event Bus, and Node.
In a typical Grid execution, the test sends a new WebDriver session request to the Grid. The Router receives the request, the Distributor identifies a suitable Node and slot, and the Node creates the browser session. After the session is created, subsequent WebDriver commands are routed to the Node where the session is running.
Course Resource: Selenium Training | Register for Course Demo
Selenium Grid is a Selenium component that allows WebDriver tests to execute on remote machines. Instead of running every browser session on one computer, Grid can distribute sessions across multiple machines and browser environments.
For example, an organization may have the following testing requirements:
Without Grid, these tests may need to run sequentially or require separate local environments. Grid provides a centralized mechanism for distributing WebDriver sessions.
Understanding Grid architecture is important because Selenium Grid is not simply a single server. Modern Selenium Grid consists of multiple logical components that cooperate to receive requests, queue sessions, find available execution slots, maintain session information, and communicate with browser machines.
A simplified Selenium Grid architecture can be represented as follows:
Test Automation Code
|
v
RemoteWebDriver
|
v
Router
|
v
New Session Queue
|
v
Distributor
|
v
Available Slot
|
v
Node
|
v
Browser Instance
Additional components such as the Session Map and Event Bus help the Grid maintain session information and communication between Grid components.
The major components of the Selenium Grid architecture are:
| Component | Primary Responsibility |
|---|---|
| Router | Acts as the main entry point and routes incoming WebDriver requests. |
| New Session Queue | Stores new session requests waiting to be assigned. |
| Distributor | Finds a suitable Node and slot for a new session. |
| Node | Runs the actual WebDriver browser sessions. |
| Session Map | Maps session IDs to the Nodes running those sessions. |
| Event Bus | Provides asynchronous communication between Grid components. |
The Router acts as the front-facing component of Selenium Grid. It receives incoming WebDriver requests and determines where those requests should be sent.
For a new session request, the Router directs the request toward the session-creation flow. For commands belonging to an existing session, it uses session information to route the request toward the appropriate Node.
Client
|
v
Router
|
+---- New Session Request ----> Session Queue
|
+---- Existing Session ------> Correct Node
The Router therefore provides a single entry point for clients communicating with a Grid.
The New Session Queue maintains incoming requests for new WebDriver sessions that have not yet been assigned to a Node.
When many tests start at the same time, there may not be an immediately available slot for every requested session. The queue allows those requests to wait until the Distributor can assign them to appropriate slots.
Test 1 ----\
Test 2 -----\
Test 3 ------> New Session Queue
Test 4 -----/
Test 5 ----/
The queue is particularly useful when a Grid is processing many concurrent test requests.
The Distributor is responsible for deciding where a new session should run. It maintains information about available Nodes and their slots and attempts to match incoming session capabilities with suitable slots.
For example, if a test requests Chrome, the Distributor looks for a Node containing a compatible Chrome slot.
New Session Request
|
v
Distributor
|
+---- Chrome Slot ----> Node A
|
+---- Firefox Slot ---> Node B
|
+---- Edge Slot ------> Node C
A Node is the machine or execution endpoint where WebDriver sessions actually run. A Node can provide one or more browser execution slots.
A Node may be configured to support browsers such as:
Example:
Node 1
|
+-- Chrome Slot
+-- Chrome Slot
+-- Firefox Slot
Node 2
|
+-- Edge Slot
+-- Firefox Slot
+-- Chrome Slot
The Distributor selects an appropriate available slot based on the requested capabilities.
A slot represents a place where a WebDriver session can run. A Node can have one or more slots.
For example:
Node
|
+-- Slot 1 - Chrome
+-- Slot 2 - Chrome
+-- Slot 3 - Firefox
+-- Slot 4 - Edge
If four compatible sessions can run concurrently, the Node can provide four available execution slots, subject to its configuration and resources.
The Session Map maintains a mapping between a WebDriver session ID and the Node where that session is running.
For example:
| Session ID | Node |
|---|---|
| session-001 | Node-1 |
| session-002 | Node-2 |
| session-003 | Node-1 |
When a WebDriver command arrives for an existing session, the Grid can determine the Node responsible for that session.
The Event Bus provides asynchronous communication between Grid components. Components can publish events and other components can listen for those events.
For example, Node registration and status-related communication can use the Event Bus as part of the Grid's internal communication architecture.
Node
|
| Event
v
Event Bus
|
+--------> Distributor
|
+--------> Other Grid Components
The Event Bus helps reduce direct coupling between components that need to communicate asynchronously.
Test Client
|
v
RemoteWebDriver
|
v
Router
/ \
/ \
v v
New Session Queue Session Map
|
v
Distributor
|
+---------+---------+
| | |
v v v
Node 1 Node 2 Node 3
| | |
Chrome Firefox Edge
Firefox Chrome Chrome
| | |
+---------+---------+
|
v
Browser Sessions
Event Bus
|
Internal Component
Communication
When a Selenium test requests a new browser session, the request passes through several Grid components.
Test Starts
|
v
RemoteWebDriver
|
v
Router
|
v
New Session Queue
|
v
Distributor
|
v
Capability Matching
|
v
Available Slot
|
v
Node
|
v
Browser
|
v
WebDriver Session Created
Once a session has been created, WebDriver commands are associated with the session ID.
Test
|
v
Router
|
v
Session ID
|
v
Session Map
|
v
Correct Node
|
v
Browser Session
|
v
WebDriver Command Executed
This allows commands such as click, sendKeys, navigation, JavaScript execution, and element interaction to reach the browser session that belongs to the test.
Grid needs to determine whether a Node can satisfy the capabilities requested by the test.
For example, a test may request:
Chrome
Windows
Specific Browser Configuration
The Distributor checks available slots and looks for a compatible configuration.
| Requested Capability | Available Slot | Possible Match |
|---|---|---|
| Chrome | Chrome | Yes |
| Firefox | Chrome | No |
| Edge | Edge | Yes |
The browserName capability can be used to identify the requested browser.
ChromeOptions options = new ChromeOptions();
WebDriver driver =
new RemoteWebDriver(
new URL("http://localhost:4444"),
options
);
The requested capabilities are evaluated against the capabilities available on Grid Nodes.
RemoteWebDriver is commonly used when the browser is running remotely through Selenium Grid.
WebDriver driver = new RemoteWebDriver(
new URL("http://localhost:4444"),
new ChromeOptions()
);
In this model, the Java test code and browser execution environment do not have to be located on the same machine.
| Feature | Local WebDriver | RemoteWebDriver |
|---|---|---|
| Browser Location | Usually local machine | Remote/Grid machine |
| Grid Required | No | Typically when using Grid |
| Parallel Scaling | Limited by local resources | Can scale across Nodes |
| Cross-Machine Execution | Not the primary model | Yes |
| Typical Use | Local development | Distributed/remote automation |
Selenium Grid can be operated in different configurations depending on the requirements of the automation environment.
Standalone mode provides a simple Grid setup in which the required Grid functionality runs through a single server process.
Test
|
v
Standalone Grid
|
v
Browser
Hub-Node mode provides a central Hub with one or more Nodes. The Hub provides the central Grid endpoint while Nodes provide browser execution capacity.
Hub
|
+-------+-------+
| | |
Node 1 Node 2 Node 3
| | |
Chrome Firefox Edge
In a fully distributed architecture, the Grid components can be started separately and communicate over the network.
Router
|
+---- Session Queue
|
+---- Distributor
|
+---- Session Map
|
+---- Event Bus
|
+---- Nodes
Standalone mode is useful for simpler Grid environments where separate deployment of individual components is unnecessary.
Test Client
|
v
Standalone Server
|
v
Browser
It provides a simple entry point while still allowing remote WebDriver execution.
In Hub-Node architecture, the Hub acts as the central coordination point and Nodes provide browser execution environments.
Hub
|
+-------------+-------------+
| | |
v v v
Node 1 Node 2 Node 3
Chrome Firefox Edge
Windows Linux Windows
This architecture is useful when different machines provide different browser or operating-system combinations.
Fully distributed Grid architecture separates the major Grid components. This architecture can be useful for larger or more complex environments where individual components need independent deployment and scaling.
Router
|
+-------------+-------------+
| | |
v v v
Session Queue Session Map Distributor
| |
| v
| Nodes
| +------+------+
| | | |
| Node1 Node2 Node3
|
+---------- Event Bus ----------+
|
Grid Components
Selenium Grid uses both synchronous and asynchronous communication mechanisms.
Synchronous communication is useful when a component needs a response to a request, such as WebDriver commands and other request-response operations.
Asynchronous communication is useful when information needs to be published as an event and the sender does not need to wait for an immediate response.
When a Node joins the Grid, it provides information about its status, capabilities, and available slots. The Distributor uses this information to maintain its model of the available Grid resources.
Node Starts
|
v
Node Announces Status
|
v
Distributor Detects Node
|
v
Node Status Checked
|
v
Capabilities / Slots Registered
|
v
Node Available for Sessions
The Grid maintains information about Nodes so that session requests can be assigned appropriately.
Important Node concepts include:
A Node can provide multiple slots depending on its configuration and available resources.
Node 1
|
+-- Slot 1 - Chrome
+-- Slot 2 - Chrome
+-- Slot 3 - Firefox
+-- Slot 4 - Edge
Parallel Sessions
|
+-- Test A - Slot 1
+-- Test B - Slot 2
+-- Test C - Slot 3
+-- Test D - Slot 4
The exact concurrency that should be configured depends on the machine's CPU, memory, browser workload, and test characteristics.
One of the primary reasons for using Grid is to execute independent tests concurrently.
Test Suite
|
+---- Test 1 ----> Node 1
|
+---- Test 2 ----> Node 2
|
+---- Test 3 ----> Node 3
|
+---- Test 4 ----> Node 1
Instead of waiting for every test to complete sequentially, multiple sessions can execute at the same time when sufficient Grid capacity is available.
Selenium Grid can be used to test the same application against multiple browsers.
| Test | Browser | Node |
|---|---|---|
| Login Test | Chrome | Node 1 |
| Login Test | Firefox | Node 2 |
| Login Test | Edge | Node 3 |
This helps teams validate browser compatibility without maintaining all browser environments on one developer machine.
Grid can also distribute tests across different operating systems.
Selenium Grid
|
+---------------+---------------+
| | |
v v v
Windows Node Linux Node Other Node
Chrome Firefox Browser
Edge Chrome Configuration
This is useful when an application needs to be validated across multiple operating-system and browser combinations.
The Grid URL is the endpoint used by the test client to communicate with the Grid. In common Selenium Grid configurations, the default endpoint is based on port 4444.
http://localhost:4444In a remote environment, the URL can point to the address of the Grid Router or the relevant Grid entry point.
import java.net.URL;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
public class GridTest {
public static void main(String[] args) throws Exception {
ChromeOptions options = new ChromeOptions();
WebDriver driver = new RemoteWebDriver(
new URL("http://localhost:4444"),
options
);
driver.get("https://example.com");
System.out.println(driver.getTitle());
driver.quit();
}
}
Here, the test creates a RemoteWebDriver session using the Grid endpoint rather than directly creating a local ChromeDriver session.
import java.net.URL;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.firefox.FirefoxOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
public class FirefoxGridTest {
public static void main(String[] args) throws Exception {
FirefoxOptions options = new FirefoxOptions();
WebDriver driver = new RemoteWebDriver(
new URL("http://localhost:4444"),
options
);
driver.get("https://example.com");
System.out.println(driver.getTitle());
driver.quit();
}
}
import java.net.URL;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.edge.EdgeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
public class EdgeGridTest {
public static void main(String[] args) throws Exception {
EdgeOptions options = new EdgeOptions();
WebDriver driver = new RemoteWebDriver(
new URL("http://localhost:4444"),
options
);
driver.get("https://example.com");
System.out.println(driver.getTitle());
driver.quit();
}
}
1. Test starts
|
v
2. RemoteWebDriver created
|
v
3. Request reaches Router
|
v
4. New Session Queue
|
v
5. Distributor receives request
|
v
6. Capabilities are matched
|
v
7. Suitable Node selected
|
v
8. Slot allocated
|
v
9. Browser session created
|
v
10. WebDriver commands execute
|
v
11. Test finishes
|
v
12. Session is terminated
Selenium Grid is frequently combined with TestNG for parallel browser automation.
TestNG
|
+---- Test 1
|
+---- Test 2
|
+---- Test 3
|
v
RemoteWebDriver
|
v
Selenium Grid
|
+---- Chrome Node
+---- Firefox Node
+---- Edge Node
TestNG controls test execution while Selenium Grid provides remote browser execution infrastructure.
A TestNG Data Provider can be used to supply browser or test-data combinations while Grid provides the execution environment.
@DataProvider(name = "browsers")
public Object[][] browsers() {
return new Object[][] {
{"chrome"},
{"firefox"},
{"edge"}
};
}
@Test(dataProvider = "browsers")
public void browserTest(String browser) {
// Create the appropriate browser options
// and start a RemoteWebDriver session.
}
This allows one logical test method to execute with different browser configurations.
Grid can be combined with the Page Object Model to separate test logic, page interaction logic, and browser infrastructure.
Test Class
|
v
Page Object
|
v
WebDriver
|
v
RemoteWebDriver
|
v
Selenium Grid
|
v
Node
|
v
Browser
Large automation frameworks commonly use a Driver Factory to centralize WebDriver creation.
DriverFactory
|
+---- Local Chrome
|
+---- Local Firefox
|
+---- Remote Chrome
|
+---- Remote Firefox
|
+---- Remote Edge
|
v
WebDriver Instance
A factory can hide browser creation details from individual test classes and make the framework easier to maintain.
public class DriverFactory {
public static WebDriver createRemoteChrome() throws Exception {
ChromeOptions options = new ChromeOptions();
return new RemoteWebDriver(
new URL("http://localhost:4444"),
options
);
}
}
The exact factory design can be extended to support multiple browsers, environments, and execution modes.
Selenium Grid can be integrated with CI/CD systems so that automated tests run against a remote browser infrastructure during pipeline execution.
Developer
|
v
Git Repository
|
v
CI/CD Pipeline
|
v
Build
|
v
TestNG / JUnit / PyTest
|
v
RemoteWebDriver
|
v
Selenium Grid
|
+---- Node 1
+---- Node 2
+---- Node 3
|
v
Test Results
|
v
Reports
A Jenkins pipeline can trigger Selenium tests that connect to a remote Grid.
Jenkins
|
v
Maven / Test Runner
|
v
Automation Tests
|
v
RemoteWebDriver
|
v
Selenium Grid
|
v
Browser Nodes
This architecture allows centralized automated execution without requiring every CI worker to contain every browser environment locally.
Selenium Grid provides a status endpoint that can be used to inspect the state of the Grid.
GET http://localhost:4444/statusThe status information can include information about registered Nodes, sessions, and slots.
Monitoring Grid Nodes is important in distributed automation environments. Teams should monitor:
A Node may need to be removed from new session scheduling while allowing existing sessions to complete. This is known as draining the Node.
Node Active
|
v
Drain Requested
|
v
No New Sessions
|
v
Existing Sessions Complete
|
v
Node Can Shut Down / Restart
This approach is useful during maintenance or controlled infrastructure changes.
One of the major benefits of Grid architecture is that browser execution capacity can be increased by adding more Nodes.
Small Grid
Router
|
Node 1
Expanded Grid
Router
|
+-----+-----+-----+
| | | |
Node 1 Node 2 Node 3 Node 4
| | | |
Chrome Firefox Edge Chrome
Adding Nodes can increase the number of available browser execution slots, subject to infrastructure capacity and Grid configuration.
Test Framework
|
+---------+---------+
| |
TestNG DataProvider
| |
+---------+---------+
|
Driver Factory
|
RemoteWebDriver
|
Router
|
+---------------+---------------+
| | |
Distributor Session Map Session Queue
|
Event Bus
|
+-----+-----+-----+
| | | |
Node Node Node Node
| | | |
Chrome Firefox Edge Chrome
|
v
Application
| Feature | Local Execution | Grid Execution |
|---|---|---|
| Execution Location | Local machine | Remote/Distributed machines |
| Parallel Capacity | Limited by local resources | Can use multiple Nodes |
| Cross-Browser | Requires local browsers | Can distribute across Nodes |
| Cross-Platform | Limited to available local OS | Can use different OS environments |
| Infrastructure | Simple | More components |
| Scalability | Limited | Can add Nodes |
| Remote Execution | No | Yes |
| Concept | Hub-Node | Fully Distributed Grid |
|---|---|---|
| Central Hub | Yes | No single monolithic Hub is required |
| Router | Part of Hub functionality | Separate component |
| Distributor | Part of Hub functionality | Separate component |
| Session Map | Part of Hub functionality | Separate component |
| Session Queue | Part of Hub functionality | Separate component |
| Event Bus | Part of Hub functionality | Separate component |
| Deployment | Simpler | More distributed |
selenium-grid-project
|
|-- src
| |-- test
| |-- java
| |-- tests
| | |-- LoginTest.java
| | |-- SearchTest.java
| | |-- CheckoutTest.java
| |
| |-- pages
| | |-- LoginPage.java
| | |-- SearchPage.java
| | |-- CheckoutPage.java
| |
| |-- utilities
| |-- DriverFactory.java
| |-- ConfigReader.java
| |-- WaitUtility.java
|
|-- pom.xml
|-- testng.xml
import java.net.URL;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.testng.Assert;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Test;
public class GridTest {
private WebDriver driver;
@BeforeMethod
public void setup() throws Exception {
ChromeOptions options = new ChromeOptions();
driver = new RemoteWebDriver(
new URL("http://localhost:4444"),
options
);
driver.manage().window().maximize();
}
@Test
public void verifyPageTitle() {
driver.get("https://example.com");
String title = driver.getTitle();
Assert.assertNotNull(title);
System.out.println("Title: " + title);
}
@AfterMethod
public void tearDown() {
if (driver != null) {
driver.quit();
}
}
}
TestNG
|
v
Browser Configuration
|
+----------+----------+
| | |
v v v
Chrome Firefox Edge
Options Options Options
| | |
+----------+----------+
|
v
RemoteWebDriver
|
v
Selenium Grid
|
+-------+-------+
| | |
Node 1 Node 2 Node 3
| | |
Chrome Firefox Edge
Consider an e-commerce application that needs to execute the same checkout test across multiple browsers.
Checkout Test
|
+---- Chrome ----> Grid Node 1
|
+---- Firefox ---> Grid Node 2
|
+---- Edge ------> Grid Node 3
Each test execution can create its own remote browser session while the same checkout test logic is reused.
Grid becomes particularly useful when browser combinations and test data combinations are both involved.
Test Data
|
+---- User 1
+---- User 2
+---- User 3
|
v
TestNG DataProvider
|
+---- Chrome
+---- Firefox
+---- Edge
|
v
RemoteWebDriver
|
v
Selenium Grid
|
+---- Node 1
+---- Node 2
+---- Node 3
When designed correctly, this combination can provide broad test coverage while reducing overall execution time.
Possible causes include:
Check the Grid URL, port, network connectivity, and whether the Grid server is running.
Check browser installation, driver configuration, Node configuration, permissions, and available system resources.
Check whether WebDriver, test data, temporary files, or other mutable resources are incorrectly shared between threads.
| Component | Remember This |
|---|---|
| Router | Front door of the Grid and request router. |
| New Session Queue | Waits for new session requests to be assigned. |
| Distributor | Finds a matching Node and slot. |
| Node | Runs browser sessions. |
| Slot | Represents a place where a session can run. |
| Session Map | Maps session IDs to Nodes. |
| Event Bus | Provides asynchronous communication. |
| RemoteWebDriver | Allows the test to communicate with a remote browser. |
Selenium Grid is a Selenium component used to execute WebDriver tests on remote machines and distribute browser sessions across available execution environments.
It is commonly used for parallel execution, cross-browser testing, cross-platform testing, and remote browser execution.
A Node is an execution endpoint that runs WebDriver browser sessions.
The Router is the entry point that routes incoming WebDriver requests to the appropriate Grid component.
The Distributor determines which Node and slot should receive a new session request.
The Session Map maintains the relationship between a session ID and the Node running that session.
It stores new session requests that are waiting to be assigned to an appropriate Node.
The Event Bus provides asynchronous communication between Grid components.
A slot represents a place on a Node where a WebDriver session can run.
RemoteWebDriver is used to communicate with a browser running on a remote execution environment such as Selenium Grid.
Yes. Grid can provide multiple browser sessions across available Nodes and slots, allowing independent tests to execute concurrently.
Cross-browser testing means executing the same application tests against different browsers such as Chrome, Firefox, and Edge.
Cross-platform testing means executing tests across different operating-system environments.
Local WebDriver normally starts a browser on the local machine, while RemoteWebDriver communicates with a remote browser execution environment.
The Distributor evaluates available slots and matches the new session request against the capabilities supported by those slots.
It helps Grid determine which Node owns a particular WebDriver session.
It allows Grid components to communicate asynchronously through events.
Yes. TestNG can manage test execution and parallelization while Selenium Grid provides remote browser execution.
Yes. Page Objects can interact with a WebDriver instance that happens to be a RemoteWebDriver connected to Grid.
It allows Grid components and browser execution resources to be distributed across infrastructure, which can support larger and more scalable automation environments.
CI/CD Pipeline
|
v
Test Framework
|
+--------+--------+
| |
TestNG DataProvider
| |
+--------+--------+
|
Driver Factory
|
RemoteWebDriver
|
v
Router
|
+---------------+---------------+
| | |
v v v
Session Queue Session Map Distributor
|
Event Bus
|
+---------------------+---------------------+
| | |
v v v
Node 1 Node 2 Node 3
| | |
Chrome Firefox Edge
| | |
+---------------------+---------------------+
|
v
Application
|
v
Assertions
|
v
Reports
Selenium Grid Architecture provides the infrastructure required to execute Selenium WebDriver sessions remotely and distribute them across multiple browser environments.
The main Selenium Grid components include the Router, New Session Queue, Distributor, Node, Session Map, and Event Bus. The Router receives requests, the New Session Queue holds pending session requests, the Distributor selects suitable execution slots, Nodes run browser sessions, the Session Map tracks session ownership, and the Event Bus provides asynchronous communication between components.
Understanding Grid architecture is important for building scalable Selenium automation frameworks because it explains how a RemoteWebDriver request travels from the test framework to the actual browser session.
Grid can be combined with TestNG, Data Providers, Page Object Model, Driver Factory, Maven, CI/CD pipelines, and reporting systems to create maintainable and scalable automation infrastructure.
Learn more about Selenium WebDriver, Selenium Grid, automation testing, and related concepts:
Final Takeaway: Selenium Grid distributes WebDriver execution across browser Nodes and provides the architecture required for remote, parallel, cross-browser, and scalable Selenium automation. The key flow to remember is Client → Router → Session Queue → Distributor → Slot → Node → Browser, while the Session Map tracks running sessions and the Event Bus supports internal asynchronous communication.
