RemoteWebDriver

Connecting to the Grid

Instead of new ChromeDriver(), create a RemoteWebDriver with the Grid URL and the browser options. Everything else in your tests stays the same.

public static WebDriver remote(String browser) throws MalformedURLException {
    URL grid = URI.create(ConfigReader.get("gridUrl")).toURL();   // http://grid.qa.local:4444
    Capabilities options = switch (browser) {
        case "firefox" -> new FirefoxOptions();
        case "edge" -> new EdgeOptions();
        default -> new ChromeOptions().addArguments("--window-size=1920,1080");
    };
    RemoteWebDriver driver = new RemoteWebDriver(grid, options);
    driver.setFileDetector(new LocalFileDetector());    // lets sendKeys upload local files to the node
    return driver;
}

Local or Remote From Config

public static void initDriver(String browser, boolean headless) throws MalformedURLException {
    WebDriver driver = "remote".equals(ConfigReader.get("runMode"))
            ? remote(browser)
            : local(browser, headless);
    DRIVER.set(driver);
}

Example

mvn test -DrunMode=remote -DgridUrl=http://localhost:4444 -Dbrowser=firefox

Example output

INFO [LocalDistributor.newSession] - Session request received by the Distributor:
 [Capabilities {browserName: firefox}]
INFO [LocalNode.newSession] - Session created by the Node. Id: 6c1b9a2f-0d7e-4c3a-9f1e-2b8a7d4e5c11, Caps: Capabilities {browserName: firefox, browserVersion: 131.0, ...}
INFO [LocalSessionMap.lambda$new$0] - Deleted session from local Session Map, Id: 6c1b9a2f-0d7e-4c3a-9f1e-2b8a7d4e5c11
[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Common Errors

ErrorCause
SessionNotCreatedException: Could not start a new session... No nodes support the capabilitiesno node has that browser/version/platform
UnreachableBrowserException / connection refusedwrong Grid URL or the Grid is down
Session timed out in the queueall slots busy; increase nodes or reduce thread-count