How to Use WebDriverManager with Selenium

To use WebDriverManager with Selenium in Java, add the io.github.bonigarcia:webdrivermanager test dependency, call WebDriverManager.chromedriver().setup(), and then create a ChromeDriver. WebDriverManager resolves and downloads a compatible browser driver, puts its path where Selenium can find it, and caches resolved drivers for reuse. You can also use create() to set up the driver and construct the WebDriver in one call. The project README and official documentation describe these patterns.

1. Add WebDriverManager to your Java project

Maven

Use test scope if WebDriverManager is only used in automated tests. The official docs show version 6.4.0; check the project’s current release metadata and your Java/Selenium constraints before pinning a version.

<dependency>
  <groupId>io.github.bonigarcia</groupId>
  <artifactId>webdrivermanager</artifactId>
  <version>6.4.0</version>
  <scope>test</scope>
</dependency>

Gradle

dependencies {
    testImplementation("io.github.bonigarcia:webdrivermanager:6.4.0")
}

If your project uses a different Selenium version or Java baseline, verify compatibility before copying that version. The docs show versioned examples, but no single version should be assumed to fit every project.

2. Set up ChromeDriver and run a Selenium test

This JUnit 5 example resolves ChromeDriver once for the class, opens a browser for the test, checks the page title, and always closes the browser. Ensure Chrome is installed in the environment where the test runs.

import static org.junit.jupiter.api.Assertions.assertTrue;

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

import io.github.bonigarcia.wdm.WebDriverManager;

class ChromeTest {
    private WebDriver driver;

    @BeforeAll
    static void resolveChromeDriver() {
        WebDriverManager.chromedriver().setup();
    }

    @BeforeEach
    void openBrowser() {
        driver = new ChromeDriver();
    }

    @Test
    void readsPageTitle() {
        driver.get("https://bonigarcia.dev/selenium-webdriver-java/");
        assertTrue(driver.getTitle().contains("Selenium WebDriver"));
    }

    @AfterEach
    void closeBrowser() {
        if (driver != null) {
            driver.quit();
        }
    }
}

For a minimal non-JUnit program, the essential order is the same:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import io.github.bonigarcia.wdm.WebDriverManager;

public class Main {
    public static void main(String[] args) {
        WebDriverManager.chromedriver().setup();
        WebDriver driver = new ChromeDriver();
        try {
            driver.get("https://example.com");
            System.out.println(driver.getTitle());
        } finally {
            driver.quit();
        }
    }
}

3. Use create() when you want a one-line setup

create() combines manager setup and WebDriver construction. It is convenient when you do not need to configure the driver between resolving it and creating the browser.

WebDriver driver = WebDriverManager.chromedriver().create();
try {
    driver.get("https://example.com");
    System.out.println(driver.getTitle());
} finally {
    driver.quit();
}

Use setup() followed by new ChromeDriver(options) when you need to supply Selenium browser options, such as headless mode, before starting the session:

import org.openqa.selenium.chrome.ChromeOptions;

WebDriverManager.chromedriver().setup();
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
WebDriver driver = new ChromeDriver(options);
try {
    driver.get("https://example.com");
} finally {
    driver.quit();
}

Browser arguments and their support can depend on the installed browser version and environment. In containers or CI, configure the browser and container resources as required by that environment; driver setup alone does not install Chrome.

4. Select a driver for another browser

Choose the manager that matches the browser you intend Selenium to control. The documented managers include Chrome, Firefox, Edge, Opera, Chromium, Internet Explorer, and Safari. Safari’s driver is built into the browser; the WebDriverManager Safari manager is especially relevant to its builder and Docker capabilities.

Browser	Manager setup	Selenium driver class
Chrome	`WebDriverManager.chromedriver().setup()`	`ChromeDriver`
Firefox	`WebDriverManager.firefoxdriver().setup()`	`FirefoxDriver`
Edge	`WebDriverManager.edgedriver().setup()`	`EdgeDriver`
Chromium	`WebDriverManager.chromiumdriver().setup()`	Use the Selenium driver appropriate to the Chromium installation

WebDriverManager.firefoxdriver().setup();
WebDriver driver = new FirefoxDriver();

The browser itself must be installed and available to the process unless you use a separate managed-browser approach. A driver binary is the communication bridge; it is not the browser.

5. What happens during driver resolution

At a high level, WebDriverManager discovers the browser version, resolves a matching driver, downloads it into a local cache, and exports the driver path through Selenium’s system property. Its documentation lists ~/.cache/selenium as the default driver cache location. A later call can reuse cached resolution data and the driver binary.

The documentation describes browser-version resolution data as cached for one hour by default and driver resolution for one day. These values and other behavior can be configured. The cache means repeated local test runs often avoid the full external lookup and download path, but a fresh machine still needs network access to obtain required metadata and binaries unless they are already available.

6. Configuration choices that matter

The fluent API supports configuration beyond the basic manager selection. Use the official configuration reference for the exact method and property names for the WebDriverManager version you pin.

Browser selection: use a named manager such as chromedriver(), or a generic manager when browser choice is dynamic.
Browser binary: if browser discovery cannot find the executable, the docs describe browserBinary() for specifying its path.
Resolution and cache: WebDriverManager caches browser and driver resolution. Review cache and TTL settings when your CI image changes browsers frequently or when you need repeatable pinned versions.
Custom driver versions and paths: the project exposes advanced configuration for controlling driver resolution and storage. Confirm current option names and supported values in the official docs rather than relying on snippets for a different release.
Logging: logging the resolution process helps identify whether failure occurs during browser discovery, metadata lookup, download, or Selenium startup.
WebDriver construction: the builder API can create WebDriver instances and supports options beyond basic setup; use it when you need its documented conveniences.

For a stable CI run, keep the Java, Selenium, browser, and WebDriverManager versions deliberate. If the browser updates independently, driver compatibility can change; a cache is a performance aid, not a guarantee that an uncontrolled browser version remains compatible indefinitely.

7. Do I still need WebDriverManager with Selenium 4?

Not always. Selenium Manager is shipped with Selenium and can handle automatic driver management for the basic use case. If resolving a driver is your only reason to add WebDriverManager, first try Selenium Manager with your existing Selenium setup. Keep WebDriverManager when you depend on its additional capabilities, such as browsers in Docker, browser discovery, WebDriver construction helpers, or monitoring. Compare your Java and Selenium compatibility needs against the current official documentation before changing a working build.

Requirement	Reasonable starting point
Resolve a local browser driver automatically	Selenium Manager may be sufficient
Use WebDriverManager-specific Docker or monitoring features	Keep WebDriverManager and configure the feature explicitly
Need a project-specific Java/Selenium combination	Check supported versions in current release documentation

WebDriverManager is an open-source Java project maintained by Boni García and licensed under Apache 2.0, according to its repository.

8. Troubleshooting

Symptom	Likely cause	What to do
`SessionNotCreatedException` says the driver supports a different browser version	The selected driver and installed browser do not match, or the browser changed after resolution.	Check the installed browser version, clear stale resolution data if appropriate, rerun resolution with network access, and pin compatible versions in CI if reproducibility is required.
Browser executable cannot be found	Only the driver was resolved; the browser is missing or installed outside the discovery path.	Install the browser in the test environment or configure its binary path using the documented API.
Driver download or metadata lookup fails	CI has no outbound access, a proxy/firewall blocks the request, or the remote metadata service is unavailable.	Check network and proxy settings, inspect WebDriverManager logs, and prepare/cache the required binaries in the build environment if policy requires offline execution.
403 response while resolving a driver	The metadata or download endpoint rejected the request.	Follow the official docs’ HTTP 403 guidance, verify endpoint access and proxy behavior, and use a current WebDriverManager release.
Works locally but fails in CI	Different OS/architecture, browser installation, permissions, network access, or cache state.	Compare environment details; ensure the executable and cache are writable; make browser installation and version explicit in the CI image.
Docker browser starts but cannot reach a local app	`localhost` from inside the browser container refers to that container, not the host running the test.	Use a host-reachable address or the correct container network route for your environment.
Browser starts but tests hang or leave processes behind	The WebDriver session is not closed on exceptions or teardown is skipped.	Put `driver.quit()` in a `finally` block or reliable test teardown; use WebDriverManager’s Docker lifecycle methods when creating Docker browsers.
Java compilation fails after dependency changes	Dependency version or Java baseline conflicts with the project’s Selenium setup.	Inspect the resolved Maven/Gradle dependency tree and check the current compatibility notes for the selected versions.

9. Performance, reliability, and cost

WebDriverManager removes repetitive manual driver downloads and path configuration. The first resolution may need browser inspection, metadata requests, and a binary download; cached runs can reuse local data. For CI reliability, keep browser installation, network access, cache permissions, and version policy explicit. Use logs when resolving failures and always close sessions to avoid resource leaks.

The library is open source under Apache 2.0. Your operational costs come from running browsers, test machines or containers, CI time, and any infrastructure you operate; the supplied project sources do not establish a fixed price for those resources.

10. Or skip the browser setup

If the job is simply to capture a web page as an image or PDF, you do not need to install Selenium and a browser driver yourself. ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers say the page verdict and billing status.
An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Every feature is on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

FAQ

Does WebDriverManager install Chrome?

No. It manages browser-driver resolution. Install the browser separately, or use a documented browser-in-Docker workflow.

Can I call setup() before every test?

You can, but resolving once for a test class or suite avoids unnecessary repeated setup work. Cached data also speeds later resolutions.

Should WebDriverManager be a production dependency?

Usually it belongs in test scope when only automated tests use it. Declare it at runtime scope only if your application itself genuinely uses it.

Can I use WebDriverManager with Firefox or Edge?

Yes. Select the corresponding manager, such as firefoxdriver() or edgedriver(), then construct the matching Selenium driver.