Selenium Grid Setup Guide

Welcome to my new blog on Selenium Grid, a powerful tool that allows you to run automated tests across multiple machines and browsers simultaneously. If you’ve been exploring Selenium for automation testing, you might have heard about running tests in parallel to save time. Selenium Grid takes this a step further by distributing tests across different machines, making your testing process faster and more efficient. In this blog, we’ll cover what Selenium Grid is, how it works, how to set it up. Let’s get started!

What is Selenium Grid?

Selenium Grid is a smart proxy server that enables you to run your automated tests in parallel on multiple machines. Normally, when you run tests (for example, using TestNG), you can execute them in parallel on a single machine. However, if you have many test cases say, 15 and you try to run them all at once on one machine, it can overload your system. Multiple browser instances (like 15 Chrome browsers) may consume too much memory, causing your system to slow down or tests to fail due to performance issues.

Selenium Grid solves this problem by distributing tests across multiple machines. For instance, instead of running all 15 tests on one machine, you can split them, running 3 tests per machine across 5 machines. This approach ensures that each machine handles a manageable load, improving performance and reducing flaky test failures (tests that fail unpredictably due to system issues).

With Selenium Grid, you control the test execution from a single machine, but the actual test runs are distributed to other machines, called nodes. The results are then consolidated and reported back to your main machine. Sounds exciting, right? Let’s explore how it works and how to set it up.

How Does Selenium Grid Work? The Architecture Explained

Selenium Grid operates using a hub-and-node architecture. Here’s a simple breakdown of its components and how they interact:

1. Hub: The Central Control System

The hub is the central point where you initiate your test execution. It’s typically set up on the machine where you write and run your Selenium code (like in Eclipse or IntelliJ).
The hub receives test requests, distributes them to the appropriate machines (nodes), and consolidates the results to display in your console.
Internally, the hub contains several components (explained below) that work together to manage test distribution.

2. Nodes: The Physical Machines

Nodes are the physical or virtual machines where the tests actually run. Each node can have different browsers (like Chrome, Firefox, or Edge) and operating systems (like Windows or macOS).
For example, if one node has Chrome installed and another has Firefox, the hub will send Chrome-specific tests to the Chrome node and Firefox-specific tests to the Firefox node.

3. Internal Components of the Hub

The hub contains several internal components that manage the test execution process, introduced in Selenium 4 for better transparency and troubleshooting:

Router: The first point of contact for test requests. It forwards new requests to the Distributor and uses the Session Map for subsequent requests in the same test session.
Distributor: Assigns tests to nodes based on requirements (e.g., browser or operating system) and balances the load to avoid overloading any single machine.
Session Map: Tracks each test session using a unique session ID and the node’s IP address, ensuring subsequent requests go to the correct node.
New Session Queue: Holds additional test requests in a queue if the Distributor is busy, ensuring smooth handling of multiple simultaneous tests.
Event Bus: Facilitates communication between the Router, Distributor, Session Map, and other components.

How Test Execution Works

You run a test from your local machine (client) using a tool like Eclipse.
The test request goes to the Router in the hub.
For a new test, the Router sends the request to the Distributor.
The Distributor assigns the test to a suitable node based on the test’s requirements (e.g., browser or operating system).
The Distributor updates the Session Map with the session ID and node’s IP address.
For subsequent requests from the same test, the Router uses the Session Map to send the request directly to the assigned node.
The test executes on the node, and the results are sent back to the hub, which displays them in your console.

This architecture ensures efficient test distribution and load balancing across multiple machines.

Setting Up Selenium Grid: Step-by-Step Guide

Let’s set up Selenium Grid using the Hub-and-Node configuration, the most beginner-friendly approach. Thanks to Selenium Manager, you no longer need to manually download browser drivers in many cases, simplifying the process. We’ll also cover traditional manual setup for completeness.

Prerequisites

Java installed (e.g., Java 17 or later, as it’s common in 2025).
Selenium Server JAR downloaded from the official Selenium website (selenium.dev) or added via Maven. Use the latest version (e.g., 4.33.0 as of May 2025).
Browsers installed on node machines (e.g., Chrome, Firefox). Selenium Manager can download browsers like Chrome for Testing if needed.
A folder (e.g., C:\Grid or /Users/Grid) to store the Selenium Server JAR (and drivers, if managing manually).
TestNG installed in Eclipse for parallel test execution.

Step 1: Download the Selenium Server JAR

Visit selenium.dev and download the latest Selenium Server JAR (e.g., selenium-server-4.33.0.jar).
Place it in a folder (e.g., C:\Grid or /Users/Grid).
Note: With Selenium Manager, you typically don’t need to download browser drivers (e.g., ChromeDriver, GeckoDriver) unless you’re managing them manually. If manual management is preferred, download drivers matching your browser versions and place them in the same folder.

Step 2: Start the Hub

The hub coordinates test execution. To start it:

Open a command prompt (Windows) or terminal (macOS/Linux).
Navigate to the folder containing the Selenium Server JAR (e.g., cd /Users/Grid).
Run the following command:
```
 java -jar selenium-server-<version>.jar hub
```
Replace <version> with the actual version (e.g., selenium-server-4.33.0.jar).
Press Enter. You’ll see logs indicating the hub is starting, including messages like “sockets ready” and “Selenium Hub is started.”
Verify the hub is running by opening a browser and navigating to http://localhost:4444. You’ll see a status page confirming the hub is active but has no registered nodes yet.

Step 3: Start a Node on the Same Machine

Let’s start a node on the same machine as the hub:

Open a new command prompt or terminal tab (keep the hub running).
Navigate to the same folder (e.g., cd /Users/Grid).

Run the following command:

 java -jar selenium-server-<version>.jar node

Press Enter. Logs will confirm the node has started and registered with the hub, showing available browsers (e.g., Chrome, Firefox, Safari).
Refresh the hub’s status page (http://localhost:4444). It will show one node registered, with details like the number of browser instances it supports (e.g., 10 Chrome, 10 Firefox, 1 Safari on macOS).

Step 4: Start a Node on a Different Machine

To distribute tests to another machine:

Prepare the node machine:
- Download the Selenium Server JAR to a folder on the node machine.
- Ensure browsers (e.g., Chrome, Firefox) are installed.
- If managing drivers manually, download compatible drivers and place them in the folder.
Connect to the node machine (e.g., via TeamViewer, RDP, or SSH).
Open a command prompt or terminal on the node machine and navigate to the folder.
Run the following command to start the node and register it with the hub:
```
 java -jar selenium-server-<version>.jar node --publish-events tcp://<hub-ip>:4442 --subscribe-events tcp://<hub-ip>:4443
```
- Replace <hub-ip> with the hub machine’s IP address (e.g., 192.168.1.139), found in the hub’s logs.
- The --publish-events and --subscribe-events flags enable TCP communication on ports 4442 and 4443.
- Selenium Manager: If no drivers are in the PATH, Selenium Manager will handle driver downloads automatically.
Press Enter. The node will register with the hub.
Refresh the hub’s status page (http://localhost:4444) on the hub machine to confirm the new node and its capabilities (e.g., Chrome support).

Step 5: Write and Run Tests with Selenium Grid

Let’s create a Selenium project to test the Grid setup, using Selenium Manager to simplify driver management.

Create a Project in Eclipse

Open Eclipse and create a new Java Project (e.g., SeleniumGrid).

Add the Selenium dependency via Maven:

Create a pom.xml file and add:

  <dependency>
      <groupId>org.seleniumhq.selenium</groupId>
      <artifactId>selenium-java</artifactId>
      <version>4.33.0</version>
  </dependency>
  <dependency>
      <groupId>org.testng</groupId>
      <artifactId>testng</artifactId>
      <version>7.8.0</version>
      <scope>test</scope>
  </dependency>

Install TestNG via Eclipse Marketplace if not already installed.

Write Test Cases

Create two test classes to run on different browsers, using RemoteWebDriver to connect to the Grid:

GoogleTest.java (runs on Chrome):

 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.remote.DesiredCapabilities;
 import org.openqa.selenium.remote.RemoteWebDriver;
 import org.testng.annotations.Test;
 import java.net.URI;

 public class GoogleTest {
     @Test
     public void HomePageCheck() throws Exception {
         DesiredCapabilities caps = new DesiredCapabilities();
         caps.setBrowserName("chrome");
         WebDriver driver = new RemoteWebDriver(new URI("http://localhost:4444").toURL(), caps);
         driver.get("https://www.google.com");
         driver.findElement(By.name("q")).sendKeys("selenium");
         System.out.println(driver.getTitle());
         driver.quit();
     }
 }

Key Points:
- Uses RemoteWebDriver to connect to the hub at http://localhost:4444.
- Sets chrome via DesiredCapabilities.
- Uses URI.toURL() for Java 20+ compatibility.
- Selenium Manager: No need to specify ChromeDriver; Selenium Manager handles it if not in the PATH.

SeleniumTest.java (runs on Firefox):

 import org.openqa.selenium.CapabilityType;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.remote.DesiredCapabilities;
 import org.openqa.selenium.remote.RemoteWebDriver;
 import org.testng.annotations.Test;
 import java.net.URI;

 public class SeleniumTest {
     @Test
     public void HomePageCheck() throws Exception {
         DesiredCapabilities caps = new DesiredCapabilities();
         caps.setCapability(CapabilityType.BROWSER_NAME, "firefox");
         WebDriver driver = new RemoteWebDriver(new URI("http://localhost:4444").toURL(), caps);
         driver.get("https://selenium.dev/");
         System.out.println(driver.getTitle());
         driver.quit();
     }
 }

Key Points:
- Uses CapabilityType.BROWSER_NAME for Firefox.
- Selenium Manager automatically manages GeckoDriver if not provided.

Configure TestNG for Parallel Execution

Right-click the project > TestNG > Convert to TestNG.
Select Parallel mode: classes to run both test classes simultaneously.

Generate a testng.xml file:

 <!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
 <suite name="Suite" parallel="classes">
     <test name="Test">
         <classes>
             <class name="GoogleTest"/>
             <class name="SeleniumTest"/>
         </classes>
     </test>
 </suite>

Save the file.

Step 6: Run the Tests

Right-click testng.xml > Run As > TestNG Suite.
The hub distributes tests:
- GoogleTest (Chrome) may run on the remote node if it supports Chrome.
- SeleniumTest (Firefox) may run on the local node if the remote node lacks GeckoDriver.
Selenium Manager ensures the correct drivers are available, downloading them to ~/.cache/selenium if needed.
Observe browsers opening on the respective machines (e.g., via TeamViewer or RDP for the remote node).
Check the Eclipse console for results, showing page titles and pass/fail status.

Step 7: Verify the Results

The hub consolidates results from all nodes and displays them in Eclipse.
Use the hub’s status page (http://localhost:4444) to monitor live node activity and session details.

If Selenium Manager detects an incompatible driver in the PATH (e.g., ChromeDriver 113 with Chrome 115), it displays a warning like:

  WARN: The chromedriver version (113.0.5672.63) detected in PATH might not be compatible with the detected chrome version (115.0.5790.110); currently, chromedriver 115.0.5790.102 is recommended.

This helps you update drivers manually if needed.

Real-World Applications of Selenium Grid

Selenium Grid is widely used to speed up test execution in real-world projects:

Scale Testing: Distribute 100 tests across 5–10 machines to reduce execution time from hours to minutes.
Cross-Browser Testing: Test on multiple browsers (e.g., Chrome, Firefox, Edge) and operating systems using different nodes.
Cloud Integration: Modern setups integrate with cloud services like Sauce Labs, BrowserStack, or Docker containers for scalability.
CI/CD Pipelines: Run tests from any machine by pointing to the hub’s IP, integrating with Jenkins or GitHub Actions.

To set up Selenium Grid in a project:

Request multiple physical or virtual machines (or use cloud-based nodes).
Install the Selenium Server JAR on each node machine. Selenium Manager handles drivers automatically.
Start the hub on one machine and nodes on others, registering them with the hub’s IP.
Write tests in Eclipse, configure TestNG for parallel execution, and run them.

Tips for Beginners

Leverage Selenium Manager: Avoid manual driver downloads; let Selenium Manager handle driver and browser management for Chrome, Firefox, and Edge.
Ensure Browser Compatibility: If managing drivers manually, ensure drivers match browser versions to avoid errors.
Monitor the Hub’s Status: Check http://localhost:4444 for live node activity and session details.
Use Hub-and-Node Setup: It’s simpler than Distributed mode for beginners.
Handle Java 20+: Use URI.toURL() for RemoteWebDriver to avoid deprecation warnings.
Opt Out of Data Collection: Selenium Manager collects anonymized usage stats by default. Set the SE_AVOID_STATS=true environment variable to disable it.
Explore Cloud Options: For large-scale testing, consider cloud-based grids or Docker for easier node management.

Conclusion

Selenium Grid is a game-changer for automation testing, enabling parallel test execution across multiple machines to save time and improve reliability. This guide has covered:

What Selenium Grid is and why it’s useful.
The hub-and-node architecture and its components.
How to set up a hub and nodes, simplified by Selenium Manager.
Writing and running tests with RemoteWebDriver and TestNG.
Practical tips for real-world testing.

Download the latest Selenium Server JAR from selenium.dev, follow these steps, and experiment with distributing your tests. If you run into issues, check the hub’s status page or the official Selenium documentation for troubleshooting.

Happy testing! 🚀

Cross Browser Testing with Selenium Grid

Table of contents