Selenium Grid 4: Setup, Hub and Node, and Running Tests (Java)

Selenium Grid lets you run Selenium tests on other machines, browsers and operating systems — and many of them in parallel. Your test talks to one address (the Grid), and the Grid sends each test to a machine (a node) that has the browser it needs. It's how teams run a large regression suite in minutes instead of hours.

How Selenium Grid Works

Your test sends a request such as "I need Chrome". The Grid finds a node with a free Chrome slot, opens the browser there and passes every command through. When the test calls quit(), the slot is free for the next test.

Setting Up Selenium Grid 4

You need Java 11 or newer and the Selenium Server jar from the Selenium downloads page. Every command below was run with selenium-server-4.25.0.jar.

Option 1: Standalone (one machine)

java -jar selenium-server-4.25.0.jar standalone

Standalone finds the browsers installed on the machine (Selenium Manager downloads matching drivers) and is ready at http://localhost:4444.

Option 2: Hub and nodes (several machines)

Start the hub on one machine:

java -jar selenium-server-4.25.0.jar hub

Then start a node on each test machine, pointing at the hub:

java -jar selenium-server-4.25.0.jar node --hub http://<hub-ip>:4444

To control exactly which browsers a node offers, use a config file:

[node]
detect-drivers = false
max-sessions = 2

[[node.driver-configuration]]
display-name = "chrome"
stereotype = '{"browserName": "chrome"}'
max-sessions = 2

java -jar selenium-server-4.25.0.jar node --config node.toml --hub http://<hub-ip>:4444

Check That the Grid Is Ready

Open http://localhost:4444/status (or the Grid UI at http://localhost:4444/ui). With only the hub running, the Grid reports it isn't ready yet:

{
    "value": {
        "ready": false,
        "message": "Selenium Grid not ready.",
        "nodes": []
    }
}

After a node registers, the same request returns "ready": true and lists the node with its browser slots:

Output

ready: True | Selenium Grid ready.
node http://192.0.2.2:5555 availability UP | slots ['chrome']

These are real results from a hub and node started with the commands above (the second output is a summary of the JSON).

Running Tests on Selenium Grid (Java)

The only change from a local test is the driver: instead of new ChromeDriver(), create a RemoteWebDriver with the Grid URL and the browser options. This compiles with Selenium 4.25:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.firefox.FirefoxOptions;
import org.openqa.selenium.remote.RemoteWebDriver;

import java.net.URI;
import java.net.URL;

public class GridTest {
    public static void main(String[] args) throws Exception {
        URL gridUrl = URI.create("http://localhost:4444").toURL(); // the hub (or standalone) address

        ChromeOptions chrome = new ChromeOptions();
        chrome.addArguments("--headless=new");                 // no window: ideal for CI
        WebDriver driver = new RemoteWebDriver(gridUrl, chrome);
        try {
            driver.get("https://www.selenium.dev");
            System.out.println("Chrome on the Grid: " + driver.getTitle());
        } finally {
            driver.quit();                                     // frees the slot on the node
        }

        WebDriver firefox = new RemoteWebDriver(gridUrl, new FirefoxOptions()); // needs a Firefox node
        try {
            firefox.get("https://www.selenium.dev");
            System.out.println("Firefox on the Grid: " + firefox.getTitle());
        } finally {
            firefox.quit();
        }
    }
}

How it works: the options object tells the Grid which browser you need; the Grid picks a node with a matching free slot. Calling quit() in finally is essential — a session that's never quit keeps its slot busy until it times out.

Run Grid with Docker

The Selenium project publishes ready-made Docker images, so you don't need to install browsers on the machine:

docker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-chrome:latest

For several browsers, use the hub and node images (selenium/hub, selenium/node-chrome, selenium/node-firefox) with Docker Compose.

Common Mistakes

1. SessionNotCreatedException: Could not start a new session — no node has the browser you asked for. Check /status and the slots each node offers.
2. Tests wait, then time out — every slot is busy. Usually sessions weren't quit: always call driver.quit() in finally or @AfterMethod.
3. Node can't reach the hub — use the hub machine's real IP (not localhost) and open ports 4444 and the node port in the firewall.
4. Sharing one driver between parallel tests — each test thread needs its own driver (use ThreadLocal<WebDriver>).
5. Chrome crashing in Docker — give the container more shared memory (--shm-size="2g").

Practice Exercises

1. Start Grid in standalone mode and open /status and /ui.
2. Change one of your local tests to use RemoteWebDriver and run it on the Grid.
3. Run three TestNG test classes in parallel on the Grid and watch the slots fill up in the UI.

Key Takeaways

• Grid runs tests on remote machines and in parallel; tests connect to one URL.
• Start with standalone; move to hub and nodes when you need more machines.
• Use RemoteWebDriver with browser options, and always quit the driver.

📚 Official documentation: Selenium Grid documentation · Docker images for Selenium Grid

Frequently Asked Questions

What is Selenium Grid used for?

To run Selenium tests on remote machines and different browsers, and to run many tests in parallel to cut execution time.

What is the difference between standalone and hub-and-node?

Standalone runs the hub and a node in one process on one machine. Hub-and-node splits them so several machines (nodes) can join one hub.

Which port does Selenium Grid use?

The hub or standalone server listens on port 4444 by default. Nodes use their own port, often 5555.

How do I check if Selenium Grid is running?

Open http://localhost:4444/status. It returns "ready": true when at least one node is available. The Grid UI is at /ui.

Do I need Selenium Grid for parallel testing?

No — TestNG can run tests in parallel on one machine. Grid is useful when you need more browsers, operating systems or machines than one computer offers.