Selenium Grid Setup for Cross-Browser Testing

This guide walks you through setting up Selenium Grid to run your automated tests across multiple browsers and machines in parallel. You’ll learn how to start a hub, register nodes, and configure your test code to use the grid, cutting down total test time and verifying your app works in Chrome, Firefox, Edge, and Safari.

What You’ll Need

Java 8 or higher – Selenium Grid runs as a Java process. Check with java -version.
Selenium Server (Grid) JAR – Download the latest selenium-server-4.x.x.jar from the official Selenium releases page.
WebDriver binaries – For each browser you want to automate (e.g., chromedriver, geckodriver, msedgedriver). Place them in a directory your PATH can access, or specify their location when starting nodes.
Browsers installed – Chrome, Firefox, Edge, Safari (on macOS) – each node must have the browser it will test.
Test framework – Your existing Selenium tests (Java, Python, C#, etc.) that you want to run through the grid.

Step-by-Step

Download and verify the Selenium Server JAR
Get the latest selenium-server-4.x.x.jar from the official Selenium releases page. Place it in a dedicated folder, e.g., ~/selenium-grid.
Start the Grid Hub
Open a terminal and run:
java -jar selenium-server-4.x.x.jar hub
By default, the hub listens on http://localhost:4444. You should see log output confirming the hub is ready.
Verify the hub is running
Open a browser and go to http://localhost:4444. You’ll see the Selenium Grid console. If you don’t, check the terminal for errors (e.g., port already in use).
Start a node for each browser/machine
On the same machine or a different one, run:
java -jar selenium-server-4.x.x.jar node --hub http://localhost:4444
This registers the node with the hub. By default, it detects installed browsers and their drivers if they are in PATH.
Specify browser drivers if needed
If a driver isn’t in PATH, use the --driver-path option. For example, for Chrome:
java -jar selenium-server-4.x.x.jar node --hub http://localhost:4444 --driver-path chromedriver=/path/to/chromedriver
Repeat for each browser/driver combination you need.
Start multiple nodes for parallel testing
To run tests in parallel, start several nodes (or use one node with multiple max sessions). For a single node, set the max sessions with:
--max-sessions 5
Or start separate node processes for different browsers or machines.

Configure your test code to use the grid
In your Selenium tests, change the WebDriver initialization to point to the hub URL. For example, in Java:

ChromeOptions options = new ChromeOptions();
WebDriver driver = new RemoteWebDriver(new URL("http://localhost:4444"), options);

In Python:

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
driver = webdriver.Remote(command_executor="http://localhost:4444", options=options)

Run your tests
Execute your test suite as usual. The tests will be routed to available nodes and run in the requested browser.

Common Mistakes

Mixing Selenium 3 and 4 syntax – Selenium 4 uses separate hub and node commands; in Selenium 3 you used -role hub and -role node. Stick to one version.
Forgetting to update PATH for drivers – If the node can’t find chromedriver, it won’t register that browser. Always ensure drivers are accessible or explicitly passed.
Firewall blocking ports – Nodes need to communicate with the hub on port 4444 (and sometimes 5555 for older versions). Open these ports if nodes are on different machines.
Using the wrong browser name in options – For example, using FirefoxOptions when you meant Chrome. The node matches the requested capabilities to what it has.
Not cleaning up old sessions – If tests crash, sessions may linger. Restart the node or use timeouts in your grid config.

Tips

Use Docker for easy scaling – The official Selenium Docker images let you start nodes with a single command, e.g., docker run selenium/node-chrome.
Set explicit timeouts – Configure session and node timeouts in the hub config to avoid stuck sessions.
Run tests in parallel with a test framework – Use TestNG, JUnit, or pytest’s parallel features to send multiple tests to the grid simultaneously.
Use a grid config file – For complex setups, create a config.toml file to define hubs, nodes, and capabilities. Start with java -jar selenium-server-4.x.x.jar hub --config config.toml.
Monitor the grid console – The web UI shows active sessions, node status, and browser availability. Use it to spot issues early.

Troubleshooting

Node not registering with hub
Check the node’s log for connection errors. Ensure the hub URL is correct and reachable (try curl http://localhost:4444). If on different machines, check firewalls and use the machine’s IP instead of localhost.
Test fails with “SessionNotCreatedException�
This usually means the browser or driver version mismatch. Update your browser and driver to compatible versions. Also verify the node actually has that browser installed.
Tests run sequentially despite multiple nodes
Your test framework might be configured to run single-threaded. Enable parallel execution in your test runner (e.g., TestNG suite XML with parallel="tests").
Grid console shows no browsers available
That means the node didn’t detect any browsers. Check the node startup log – it lists which drivers it found. Reinstall drivers or pass them explicitly.
Port 4444 already in use
Find the process using it (on Linux/macOS: lsof -i :4444) and kill it, or start the hub on a different port with --port 4445.

Frequently Asked Questions

Do I need a separate node for each browser?

No. A single node can handle multiple browsers if they are all installed on that machine. The node will register each browser as a separate capability.

Can I run Selenium Grid on a single machine without Docker?

Yes, you can run the hub and nodes as separate Java processes on the same machine. Just start the hub first, then start one or more node processes.

How do I run tests in parallel across different browsers?

Configure your test framework to run tests in parallel (e.g., TestNG with thread-count). Each test can specify a different browser via capabilities, and the grid will route them to the appropriate node.

What is the difference between Selenium Grid and Selenium WebDriver?

WebDriver is the API you use to control a browser. Grid is a tool that manages multiple WebDriver instances on different machines/browsers, allowing you to scale tests.

Is Selenium Grid free?

Yes, Selenium Grid is open-source and free to use. You only pay for the infrastructure (machines, VMs, or Docker hosts) you run it on.

How do I update the Selenium Server JAR?

Download the latest JAR from the Selenium releases page and replace the old one. Restart the hub and nodes to use the new version.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →