Avi is a senior developer with a passion for Java technologies… http://www.aviyehuda.com/ Avi is a DZone MVB and is not an employee of DZone and has posted 25 posts at DZone. You can read more from them at their website. View Full User Profile

HtmlUnit: A Quick Introduction

  • submit to reddit
HtmlUnit is an open source java library for creating HTTP calls which imitate the browser functionality. HtmlUnit is mostly used for integration testing on top of unit test frameworks such as JUnit or TestNG. This is done by requesting web pages and asserting the results.

Simple Example

public void testGoogle(){
WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");
assertEquals("Google", currentPage.getTitleText());


  • As you can see in the example, the WebClient is the starting point. It is the browser simulator.
  • WebClient.getPage() is just like typing an address in the browser. It returns an HtmlPage object.


  • HtmlPage represents a single web page along with all of it's client's data (HTML, JavaScript, CSS ...).
  • The HtmlPage lets you access to many of a web page content:

Page source

  • You can receive the page source as text or as XML.
HtmlPage currentPage = 
String textSource = currentPage.asText();
String xmlSource = currentPage.asXml();

HTML Elements

  • HtmlPage lets you ability to access any of the page HTML elements and all of their attributes and sub elements. This includes tables, images, input fields, divs or any other Html element you may imagine.
  • Use the function getHtmlElementById() to get any of the page elements.
WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");
HtmlImage imgElement = (HtmlImage)currentPage.getHtmlElementById("logo");


  • Anchor is the representation of the Html tag <a href="..." >link</a>.
  • Use the functions getAnchorByName(), getAnchorByHref() and getAnchorByText() to easily access any of the anchors in the page.
WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");
HtmlAnchor advancedSearchAn =
currentPage.getAnchorByText("Advanced Search");
currentPage = advancedSearchAn.click();
assertEquals("Google Advanced Search",currentPage.getTitleText());

Dom elements by XPath

  • You can access any of the page elements by using XPath.
WebClient webClient = new WebClient();
HtmlPage currentPage =

//Using XPath to get the first result in Google query
HtmlElement element = (HtmlElement)currentPage.getByXPath("//h3").get(0);
DomNode result = element.getChildNodes().get(0);

Form control

  • A large part of controlling your HTML page is to control the form elements:
    • HtmlForm
    • HtmlTextInput
    • HtmlSubmitInput
    • HtmlCheckBoxInput
    • HtmlHiddenInput
    • HtmlPasswordInput
    • HtmlRadioButtonInput
    • HtmlFileInput
WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");

//Get the query input text
HtmlInput queryInput = currentPage.getElementByName("q");

//Submit the form by pressing the submit button
HtmlSubmitInput submitBtn = currentPage.getElementByName("btnG");
currentPage = submitBtn.click();


currentPage = webClient.getPage("http://www.google.com/search?q=htmlunit");
final HtmlTable table = currentPage.getHtmlElementById("nav");
for (final HtmlTableRow row : table.getRows()) {
System.out.println("Found row");
for (final HtmlTableCell cell : row.getCells()) {
System.out.println(" Found cell: " + cell.asText());

JavaScript support

  • HtmlUnit uses the Mozilla Rhino JavaScript engine.
  • This lets you the ability to run pages with JavaScript or even run JavaScript code by command.
ScriptResult result = currentPage.executeJavaScript(JavaScriptCode);
  • By default JavaScript exceptions will crash your tests. If you wish to ignore JavaScript exceptions use this:
  • If you would like to turn off the JavaScript all together, use this:

HTTP elements


WebClient webClient = new WebClient();
HtmlPage currentPage =
URL url = currentPage.getWebResponse().getRequestSettings().getUrl()

Response status

WebClient webClient = new WebClient();
HtmlPage currentPage = webClient.getPage("http://www.google.com/");


Set cookies = webClient.getCookieManager().getCookies();
for (Cookie cookie : cookies) {
System.out.println(cookie.getName() + " = " + cookie.getValue());

Response headers

WebClient webClient = new WebClient();
HtmlPage currentPage =

List headers =
for (NameValuePair header : headers) {
System.out.println(header.getName() + " = " + header.getValue());

Request parameters

List parameters = 
for (NameValuePair parameter : parameters) {
System.out.println(parameter.getName() + " = " + parameter.getValue());

Making assertions

  • HtmlUnit comes with a set of assetions:
   assertTitleEquals(HtmlPage, String)
assertTitleContains(HtmlPage, String)
assertTitleMatches(HtmlPage, String)
assertElementPresent(HtmlPage, String)
assertElementPresentByXPath(HtmlPage, String)
assertElementNotPresent(HtmlPage, String)
assertElementNotPresentByXPath(HtmlPage, String)
assertTextPresent(HtmlPage, String)
assertTextPresentInElement(HtmlPage, String, String)
assertTextNotPresent(HtmlPage, String)
assertTextNotPresentInElement(HtmlPage, String, String)
assertLinkPresent(HtmlPage, String)
assertLinkNotPresent(HtmlPage, String)
assertLinkPresentWithText(HtmlPage, String)
assertLinkNotPresentWithText(HtmlPage, String)
assertFormPresent(HtmlPage, String)
assertFormNotPresent(HtmlPage, String)
assertInputPresent(HtmlPage, String)
assertInputNotPresent(HtmlPage, String)
assertInputContainsValue(HtmlPage, String, String)
assertInputDoesNotContainValue(HtmlPage, String, String)

  • You can still of course use the framework's assertions. For example, if you are using JUnit, you can still use assertTrue() and so on.
  • Here are a few examples:
WebClient webClient = new WebClient();
HtmlPage currentPage =

WebAssert.assertTextPresent(currentPage, "htmlunit");
WebAssert.assertTitleContains(currentPage, "htmlunit");
WebAssert.assertLinkPresentWithText(currentPage, "Advanced search");
assertTrue(currentPage.getByXPath("//h3").size()>0); //result number

See also

 Download example


from http://www.aviyehuda.com/

Published at DZone with permission of Avi Yehuda, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)



Thomas Eichberger replied on Sat, 2010/05/22 - 6:36pm

Nice introduction.

Senthil Balakrishnan replied on Tue, 2010/05/25 - 12:01pm

It's one of the oldest & simple intergration test automation. I personally liked it always!!!

Raghu Semburakk... replied on Tue, 2010/06/08 - 4:06pm in response to: Senthil Balakrishnan

I know senthil :-)

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.