Built by Maven

HtmlUnit Development Guide

Prerequisites

Before starting, ensure you have the following installed:

  • Java Development Kit (JDK 17)
  • Eclipse IDE
  • Maven 3
  • Git (use your favorite Git client)
  • Web Browser (Chrome / Firefox / Edge to check compatibility)

Repository Setup and Initial Build

Clone the HtmlUnit repository from GitHub:

git clone https://github.com/HtmlUnit/htmlunit.git
cd htmlunit

Compile the project to ensure everything is working correctly:

mvn clean compile

Run selective unit tests:

Do not run the whole test suite as it takes a significant amount of time.

mvn test -Dtest=org.htmlunit.javascript.host.dom.*Test

Eclipse IDE Setup

Generate Eclipse project files:

Use the Maven Eclipse Plugin to generate project files with source downloads:

mvn eclipse:eclipse -DdownloadSources=true

Then import the project into Eclipse:

File → Import → Existing Projects into Workspace

Running Tests from Eclipse:

Usually you would run only select tests from Eclipse. Refer to the section on real browser testing below for details.

IntelliJ IDEA Project Setup

IntelliJ IDEA has built-in Maven support and can directly import the HtmlUnit project.

Import Steps:

  1. Open IntelliJ IDEA
  2. Select File → Open
  3. Navigate to the cloned HtmlUnit directory
  4. Select the pom.xml file and click Open
  5. Choose Open as Project when prompted
  6. IntelliJ will automatically detect the Maven project and import it

Running Tests via Maven

Running the full test suite requires significant time and resources. Several profiles are defined to run distinct test sets:

Run Core Test Suite:

Fast core test suite (~25 min; excludes library and heavy tests):

mvn test -P without-library-and-huge-tests -Dgpg.skip -Djava.awt.headless=true

Run Library Test Suite:

Runs test suites from various JavaScript libraries (jQuery, Prototype, etc.):

mvn test -P only-library-tests -Dgpg.skip -Djava.awt.headless=true

Test Port Configuration:

Tests assume port 12345 is available. If you encounter java.net.BindException: Address already in use, override the test port: 

mvn test ... -Dhtmlunit.test.port=10101

Running Tests with Real Browsers

The primary goal of HtmlUnit is providing accurate browser simulation. Almost all tests can be executed against real browsers using Selenium WebDriver.

This is managed via org.htmlunit.WebDriverTestCase. To configure real browser runs, create a test.properties file in the HtmlUnit root directory: 

browsers=hu
#browsers=hu-ff
#browsers=hu-ff, hu-chrome
#browsers=ff, chrome, edge

# Unix/Linux paths
ff.bin=/usr/bin/firefox
ff-esr.bin=/usr/bin/firefox-esr
geckodriver.bin=/usr/bin/driver/geckodriver
chrome.bin=/path/to/chromedriver
edge.bin=/path/to/chromedriver

# Windows paths
geckodriver.bin=C:\\path\\to\\geckodriver.exe
ff.bin=C:\\path\\to\\Mozilla Firefox\\firefox.exe
ff-esr.bin=C:\\path\\to\\Mozilla Firefox ESR\\firefox.exe
chrome.bin=C:\\path\\to\\chromedriver.exe
edge.bin=C:\\path\\to\\msedgedriver.exe

# optional
autofix=false

Test Properties Reference:

browsers: Comma-separated combination of target environments:

  • hu (HtmlUnit all browser versions)
  • hu-ff, hu-ff-esr, hu-chrome, hu-edge
  • ff, ff-esr, chrome, edge (Real browsers via WebDriver)

Browser Driver & Binary Paths:

  • chrome.bin: Path to ChromeDriver executable
  • geckodriver.bin: Path to GeckoDriver executable
  • ff.bin / ff-esr.bin: Optional Firefox binaries
  • edge.bin: Path to Edge WebDriver binary

Additional Options:

  • autofix: Automatically update expectations or @NotYetImplemented annotations.