How to Use HtmlUnit with Selenium Grid
Run HtmlUnit sessions through Selenium 4 Grid with HtmlUnit Remote: configure the extension and node, connect with RemoteWebDriver, and troubleshoot common setup issues.
Direct answer: To run HtmlUnit through Selenium 4 Grid, install the HtmlUnit Remote Grid extension on the Selenium Server, register an HtmlUnit node slot with the matching slot matcher, then create a Java RemoteWebDriver session using browserName=htmlunit. The ordinary HtmlUnitDriver dependency is for local sessions; the Grid integration comes from HtmlUnit Remote.
HtmlUnit is a Java GUI-less browser. It can be useful for headless tests, but do not assume its behavior matches Chrome, Firefox, or another real browser your application supports. Run compatibility-sensitive checks in the real browsers you support, too.
1. Choose the setup and verify versions
Use local HtmlUnitDriver when the test process itself should own the browser. Use HtmlUnit Remote when sessions need to be created and managed through Selenium Grid. The Grid path requires both the remote extension and a Grid node configured to advertise the htmlunit browser.
The HtmlUnit driver project lists org.seleniumhq.selenium:htmlunit3-driver:4.48.0. Its README points to compatibility tables for driver and HtmlUnit versions. The Selenium Grid article provides the extension setup shape, but the current HtmlUnit Remote artifact version and a complete compatible version range are not established here. Check the project release metadata and compatibility table before pinning versions. Do not assume that the driver and Grid extension use identical version numbers.
2. Install and configure the HtmlUnit Grid extension
Selenium Server does not bundle HtmlUnit driver artifacts. Add the HtmlUnit Remote Grid extension JAR with Selenium Server’s --ext option. The following configuration follows the documented example; save it as htmlunit.toml and adjust it only after checking the extension version you install.
[node]
detect-drivers = false
[[node.driver-configuration]]
display-name = "HtmlUnit"
stereotype = "{\"browserName\": \"htmlunit\"}"
[distributor]
slot-matcher = "org.openqa.selenium.htmlunit.remote.HtmlUnitSlotMatcher"The node configuration disables automatic driver detection, declares a slot whose browser name is htmlunit, and tells the distributor to use HtmlUnit’s slot matcher. The advertised browser name must match the capability sent by the client.
3. Start Selenium Server with the extension
Download the Selenium Server JAR and the HtmlUnit Remote Grid extension JAR for versions you have verified. Replace the placeholders below with the actual filenames. This example starts a standalone Grid process:
java -jar selenium-server-<version>.jar \
--ext htmlunit-remote-<version>-grid-extension.jar \
standalone --config htmlunit.tomlKeep the extension available to the process that loads the configured node. If you deploy a distributed Grid, apply the extension and node configuration to the appropriate node process, and ensure the distributor uses the HtmlUnit slot matcher. The example above is a launch pattern, not a claim that a particular placeholder version is current.
4. Create a remote HtmlUnit session in Java
Point RemoteWebDriver at the Grid URL and request the browser name the node advertises. The following is the client-side shape for Selenium 4; provide the actual reachable Grid URL for your deployment.
import java.net.URL;
import org.openqa.selenium.Capabilities;
import org.openqa.selenium.MutableCapabilities;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.RemoteWebDriver;
public class HtmlUnitGridExample {
public static void main(String[] args) throws Exception {
URL gridUrl = new URL("http://localhost:4444");
Capabilities options = new MutableCapabilities();
((MutableCapabilities) options).setCapability("browserName", "htmlunit");
WebDriver driver = new RemoteWebDriver(gridUrl, options);
try {
driver.get("https://example.com");
System.out.println(driver.getTitle());
} finally {
driver.quit();
}
}
}The Grid URL is deployment-specific. The example requests only the browser name; add capabilities supported by the HtmlUnit driver and your installed versions only when needed. Always call quit() in a finally block so the remote session is released even if navigation or an assertion fails.
5. Local HtmlUnitDriver versus Grid
| Mode | Where the session runs | Choose it when |
|---|---|---|
| Local HtmlUnitDriver | In the Java test process | You want the simplest setup and do not need Grid-managed remote sessions. |
| HtmlUnit Remote through Grid | On a Grid node loaded with the HtmlUnit extension | You need sessions to use Grid’s remote session model and node configuration. |
The local driver project documents constructors for default or specified browser versions and optional JavaScript support. The Grid configuration adds deployment and extension management. Whether HtmlUnit is suitable for a given test depends on what behavior the test needs to verify; compare results against the actual supported browsers for rendering or browser compatibility requirements.
Configuration checklist
- Verify Selenium Server, HtmlUnit Remote, HtmlUnit, and driver compatibility in the projects’ current release information.
- Make the HtmlUnit Remote Grid extension JAR available to Selenium Server through
--ext. - Register the node driver configuration with
browserNameset tohtmlunit. - Configure
org.openqa.selenium.htmlunit.remote.HtmlUnitSlotMatcherfor the distributor. - Connect the test to the correct Grid URL and request the same browser name.
- Close every session with
driver.quit(). - Keep tests that require actual browser rendering or compatibility coverage in the real browsers your application supports.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Grid cannot create an HtmlUnit session | The extension is missing, not loaded, or incompatible with the Selenium Server version. | Confirm the extension JAR path passed to --ext, inspect server startup output, and verify release compatibility. |
| No matching node or slot is available | The node does not advertise the requested capability, or the distributor is not using HtmlUnit’s matcher. | Check the TOML stereotype for browserName equal to htmlunit, the driver configuration, and the slot matcher class name. |
| Session creation reports an unsupported browser | The client capability and node stereotype differ, often due to a spelling or configuration mismatch. | Use the exact value htmlunit on both sides and confirm the node registered successfully. |
| The server rejects the configuration or fails at startup | Malformed TOML, an incorrect class name, or an extension that is not on the server classpath. | Validate the TOML structure, preserve the fully qualified matcher class name, and check startup logs for extension loading errors. |
| Remote connection fails before session creation | The Grid URL is wrong, unreachable from the test process, or the server is not listening. | Use the URL reachable from the client environment, check host and port routing, and confirm Selenium Server is running. |
| Tests pass in HtmlUnit but fail in a real browser, or the reverse | The test depends on behavior that differs between a GUI-less browser and a real browser. | Run the relevant test in the supported real browsers and treat HtmlUnit as a separate test target, not a substitute for compatibility coverage. |
| Sessions accumulate on the Grid | The test exits without closing the remote session. | Put driver.quit() in a finally block, including around assertions and navigation. |
Performance, reliability, and cost considerations
Grid adds a remote session request and a separately configured server or node to the test path. Keep the Selenium Server and extension versions pinned and compatible, and check node registration and server logs when sessions cannot be allocated. The research sources do not provide a performance benchmark or resource comparison for HtmlUnit and other browsers, so measure your own suite before making capacity assumptions.
HtmlUnit’s GUI-less nature can make it useful as a headless test target, but it does not establish equivalence with a full browser. Reliability also depends on the extension being loaded, the node advertising the expected slot, network reachability, and tests releasing sessions. No Grid hosting or infrastructure cost is specified here; account for the servers and operational setup your deployment requires.
Or skip the browser setup
If the goal is to capture a website image rather than run WebDriver tests, ScreenshotNeo provides a website screenshot API and MCP server. It uses one GET request to return PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpimport 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}`);ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.
FAQ
Does Selenium Server include HtmlUnit support by default?
No. The Selenium Server setup needs the HtmlUnit Remote Grid extension loaded with --ext.
Can I use HtmlUnitDriver locally without Grid?
Yes. Local HtmlUnitDriver is a separate mode that runs in the test process; use HtmlUnit Remote when you need Selenium 4 Grid-managed sessions.
Should HtmlUnit replace browser testing?
No. Use it as a headless test target where it fits, and test in the real browsers relevant to your application’s support requirements.
Which HtmlUnit Remote version should I install?
Check the current HtmlUnit Remote release metadata and compatibility information for your Selenium Server and driver versions. The setup example uses placeholder artifact filenames because the current extension version is not established here.
