How to use Apache JMeter’s WebDriver Sampler to Load Test the UI of an Application

Key takeaways

• The WebDriver Sampler comes from the Selenium/WebDriver Support plugin (jpgc-webdriver, version 4.13.0.2, built on Selenium 4.13.0). Install it with the Plugins Manager.
• It drives a real browser, so it sees JavaScript, rendering and client-side calls that HTTP samplers never execute.
• A real browser per thread is expensive. Run a few browser threads beside an HTTP-level load and use them to measure what a user sees, not to generate volume.

To load test the UI of an application with JMeter, install the Selenium/WebDriver Support plugin, add a browser config such as Chrome Driver Config to a thread group, point it at a browser driver, and script the user’s steps in a WebDriver Sampler. Each JMeter thread then drives its own real browser and records how long the scripted steps took, while ordinary HTTP samplers produce the bulk of the load.

What does the JMeter WebDriver Sampler measure?

It measures the time a real browser needs to complete the steps in your script: loading a page, running its JavaScript, clicking a link, waiting for content to appear. JMeter on its own works at protocol level. Its documentation says it “does not execute the Javascript found in HTML pages” and does not render HTML the way a browser does. The WebDriver Sampler fills that gap by controlling Chrome, Edge, Firefox or another browser through Selenium WebDriver.

What do you need before you start?

• JMeter 5.6.3, the current release, which requires Java 8 or later. The JMeter load testing tutorial covers installing it and building a basic HTTP test plan.
• The Plugins Manager, then the plugin Selenium/WebDriver Support (id jpgc-webdriver). The jmeter-plugins.org catalog lists 4.13.0.2 as the latest version; its 4.13.0.0 release note says Selenium 4.13.0 is “the last version of WebDriver with Java 8 support”. Our guide to installing plugins with the JMeter Plugins Manager walks through the dialog.
• A browser and a matching driver. The plugin adds config elements for Chrome, Edge, Firefox, Internet Explorer (which starts Edge in IE mode), HtmlUnit (no window, no driver needed) and a Remote Driver Config for a Selenium Grid. Its documentation asks you to download the driver yourself and enter its location in the Path to Driver field.

Where to get the drivers today: ChromeDriver for Chrome 115 and later comes from the Chrome for Testing availability dashboard (linked from developer.chrome.com/docs/chromedriver/downloads), geckodriver from github.com/mozilla/geckodriver/releases, and msedgedriver from Microsoft’s Edge WebDriver page. The old sites.google.com/a/chromium.org/chromedriver address that earlier versions of this article linked to no longer serves the downloads. Browsers update themselves and drivers do not, so check that the two versions still match when a test that used to work fails to start the browser.

How do you set up a WebDriver test in JMeter?

Step 1: Add a thread group for the browser users

Right-click the Test Plan and add a thread group. The screenshot uses the jp@gc - Stepping Thread Group from the Custom Thread Groups plugin (jpgc-casutg); a standard Thread Group works just as well, and the jmeter-plugins.org page for the Stepping Thread Group itself points to the Concurrency Thread Group as the better alternative today. Keep the thread count small, for the reasons in the resource section below.

Step 2: Add a Chrome Driver Config

Right-click the thread group and choose Add > Config Element > jp@gc - Chrome Driver Config. One config per thread group is enough: every thread in that group gets its own browser from it.

Enter the location of the chromedriver file you downloaded, for example /Users/user/Downloads/chromedriver on a Mac.

The screenshots come from an older plugin version, where the browser options sat on an Experimental tab. In version 4.13 the Driver tab holds Path to Driver together with these options:

• Create a new Browser at the start of each iteration. Off by default. When it is off, a thread keeps the same browser across iterations, so cached files and cookies carry over, much like a returning visitor. Turn it on to start each iteration with a fresh browser, at the cost of a browser start-up every time.
• Headless, which runs Chrome, Edge or Firefox without a visible window, useful on a server.
• Maximize browser window (on by default), Accept Insecure Certs for test environments with self-signed certificates, and Development Mode, which keeps the browser open after an error so you can see what went wrong.

Step 3: Add a WebDriver Sampler and write the script

Add Sampler > jp@gc - WebDriver Sampler to the same thread group. The script gets an object named WDS: WDS.browser is the Selenium WebDriver instance, WDS.vars holds the thread’s JMeter variables, WDS.sampleResult is the result JMeter records and WDS.log writes to jmeter.log.

Two things changed since the screenshot below was taken:

• The default script language is Groovy. The plugin’s source notes that the JavaScript engine was removed from the JDK, and JMeter’s own release notes say Nashorn is gone from Java 15. If you choose javascript on a newer Java, add a JavaScript engine such as Mozilla Rhino to lib/ext first, as the JMeter release notes describe.
• The sampler now does the timing. In the current version (4.13.0.2) it starts the timer before your script runs and stops it after. The old pattern of wrapping the step in WDS.sampleResult.sampleStart() and sampleEnd() no longer works as intended: your sampleStart() is ignored because the timer started before the script ran, while your sampleEnd() still stops it early, and both log “called twice” errors. Remove both calls. To time one step on its own, put the preparation steps in one WebDriver Sampler and the step you care about in the next; the browser stays open between samplers in the same thread.

This Groovy script opens a page with a token in the query string and marks the sample as failed when the wrong page loads. Replace the URL and the expected title with your own:

def token = WDS.vars.get('token')
WDS.browser.get('https://www.example.com/?uid=' + token)

if (!WDS.browser.getTitle().contains('Example Domain')) {
    WDS.sampleResult.setSuccessful(false)
    WDS.sampleResult.setResponseMessage('Unexpected title: ' + WDS.browser.getTitle())
}

The sampler assumes success unless you say otherwise, so always check something on the page. For pages that fill in content with JavaScript after the load, wait for a specific element with Selenium’s WebDriverWait before the check; the difference between waiting styles is covered in explicit and implicit waits in Selenium WebDriver.

Step 4: Get the token with an HTTP request first

In this example the page needs a token, so an HTTP Request sampler (generate_token in the tree) logs in first and a post-processor extracts the token into the token variable. The screenshot shows the old jp@gc - JSON Path Extractor, a plugin that jmeter-plugins.org now marks as deprecated in favour of JMeter’s built-in JSON Extractor. The full login and extraction flow, with credentials read from a CSV file, is in logging in from a CSV file and extracting the token.

Keep in mind that the HTTP sampler and the browser do not share cookies. A token passed in the URL or a header reaches the browser; a session cookie set on the HTTP sampler does not. If the application relies on a session cookie, log in through the browser in a first WebDriver Sampler instead.

Step 5: Add listeners

Add an Aggregate Report for the sample count, response times, error rate and throughput of each sampler.

The over-time graphs in the screenshot are plugins too: Response Times Over Time and Active Threads Over Time come with 3 Basic Graphs (jpgc-graphs-basic), and Hits per Second with 5 Additional Graphs (jpgc-graphs-additional). They are handy while you build the test. For the measured run, JMeter’s best practices say to use non-GUI mode, write results with -l and leave listeners such as View Results Tree for debugging only.

How many browser threads can one machine run?

Far fewer than HTTP threads. Each thread starts its own driver process and its own browser. The plugin’s documentation says that, in general, a WebDriver test needs about one CPU core per virtual user, and its tutorial suggests a ceiling of one browser fewer than the number of cores (three browsers on a four-core machine). Treat those as starting points from the plugin authors, not measured limits for your machine: run one thread to get a baseline, then add browsers while you watch CPU and memory on the load generator. If the generator itself is saturated, the browser timings measure your laptop, not the application. For the HTTP side, the limits are different; see how many concurrent users JMeter can run from one machine.

We measured the cost with Selenium and headless Chrome outside JMeter: about 620 to 680 MiB of memory per browser, and fewer page views a second with 20 browsers than with 5 on a 10-core machine. The numbers are in what one Selenium browser user costs.

How do you combine browser timing with an HTTP load?

Use two thread groups in the same test plan. The first holds HTTP Request samplers and creates the traffic: hundreds or thousands of threads, depending on your target. The second holds one to a few WebDriver threads that repeat the user journey while that traffic runs. The plugin’s tutorial describes exactly this split: the HTTP samplers make the load production-like from the server’s point of view, while the browser threads show what a real user experiences at the same time. Compare the browser timings at zero load with the timings under load; the difference is what the load costs your users.

Can you run a WebDriver test in the cloud?

Cloud runs of the HTTP part are the easy half. LoadFocus JMeter load testing runs an uploaded .jmx from 25 cloud regions, and the page says CSV data files, thread groups, timers, assertions, JSR223 samplers and plugins come along with the plan. It does not mention the WebDriver Sampler or real browsers, so confirm with LoadFocus before you plan a browser-based run there. If what you want is front-end timing of a page over time rather than during a load test, page speed monitoring runs Lighthouse-based checks of your pages from several cloud locations.

Frequently Asked Questions

What does the WebDriver Sampler add?

Real browser rendering. HTTP samplers measure the server response and never execute JavaScript, so anything that happens in the browser after the response, such as client-side rendering, API calls made by scripts and third-party tags, is invisible to them. The WebDriver Sampler drives a real browser and records how long the scripted steps took.

Can I generate load with it?

Not much. Each thread runs a full browser, and the plugin’s documentation suggests about one CPU core per browser user. Run a small number of browser threads alongside a larger HTTP-based load rather than trying to produce volume this way.

What is it best used for?

Measuring front-end timing under load: what the page actually does for a user while the system is busy, rather than how quickly the server replied. It is also a quick way to check that a critical journey still completes while the servers are under pressure.

Which script language should I use in the WebDriver Sampler?

Groovy, the plugin’s default in the current 4.13 releases. JavaScript only works if your Java version still has a JavaScript engine or you add one, because Nashorn was removed in Java 15. Scripts from older tutorials usually run in Groovy with small changes, since the WDS calls are the same.

Do I still need to download ChromeDriver?

Yes, for the plugin. Its Chrome, Edge and Firefox configs ask for the path to a driver you downloaded, and the driver has to match the installed browser version. HtmlUnit needs no driver, but it is not a real browser and its JavaScript support is more limited.

Can the WebDriver Sampler run headless?

Yes. The Chrome, Edge and Firefox driver configs have a Headless option, which runs the browser without a window. That suits a server or a CI machine without a display.

Sources

• JMeter Plugins catalog entry jpgc-webdriver (versions, Selenium 4.13.0, release notes), jmeter-plugins.org/repo (October 2026)
• WebDriver plugin documentation: Web Driver Sampler, Web Driver Tutorial and Direct Driver Config pages, github.com/undera/jmeter-plugins-webdriver (October 2026)
• WebDriver plugin source, WebDriverSampler.java (default Groovy engine, sampler timing) and WebDriverConfigGui.java (Driver tab options), github.com/undera/jmeter-plugins-webdriver (October 2026)
• Apache JMeter, “JMeter is not a browser”, jmeter.apache.org (October 2026)
• Apache JMeter download page (5.6.3, Java 8+) and release notes (Nashorn removed in Java 15), jmeter.apache.org (October 2026)
• Apache JMeter SampleResult.sampleStart() source, release 5.6.3, github.com/apache/jmeter (October 2026)
• Apache JMeter best practices, jmeter.apache.org/usermanual/best-practices.html (October 2026)
• ChromeDriver downloads, developer.chrome.com/docs/chromedriver/downloads (October 2026)
• Selenium documentation, driver location, selenium.dev (October 2026)
• LoadFocus JMeter load testing page, loadfocus.com/jmeter-load-testing (October 2026)

Related reading

• Load Test OAuth 2.0 APIs with JMeter: Token Flow Step by Step
• JMeter for Beginners: What to Learn, in Order
• JMeter User Defined Variables: Setup, Scope and Examples