Tutorial

The QuickStart contains sample code and guidance to get you started with jWebUnit.

Creating a TestCase

jWebUnit uses two approaches for creating test cases: inheritance and delegation.
The simplest is to inherit from WebTestCase rather than
junit.framework.TestCase.

import net.sourceforge.jwebunit.WebTestCase;

public class ExampleWebTestCase extends WebTestCase {

public ExampleWebTestCase(String name) {
super(name);
}
}
An alternative is to include an instance of the WebTester class in your TestCase
and delegate navigation and assertions to it.
This is provided in case you need or prefer delegation.

import junit.framework.TestCase;
import net.sourceforge.jwebunit.WebTester;

public class ExampleWebTestCase extends TestCase {

private WebTester tester;

public ExampleWebTestCase(String name) {

super(name);
tester = new WebTester();
}
}
For the rest of the examples, we will use inheritance.

Navigating Your Web Application

Navigation is a two step process.

First, point the TestCase to your application, then access a particular resource.
Let's say that your app is running on http://myserver:8080/myapp. To
minimize the number of the times we must set this, we set this either in the
constructor or in the setUp() method of the TestCase.

public ExampleWebTestCase(String name) {

super(name);
getTestContext().setBaseUrl("http://myserver:8080/myapp");
}
or
public void setUp() throws Exception {
getTestContext().setBaseUrl("http://myserver:8080/myapp");
}
The TestContext encapsulates the configuration of a TestCase.

Now that the TestCase is pointed at your application, you can navigate to a
particular resource.
For example, if you have a html page, info.html, located under your
application root, then you can access it in a test method with the following
code:
public void testInfoPage() {
beginAt("/info.html");
}

You can also navigate through links either by text contained in the link or by the link's id:

<a id="addLink" href="/addPage">Add Widget</a>

<a id="editlink" href="/editPage">Edit Widget</a>

public void testMainPageLinks() {

beginAt("/mainPage");
assertLinkPresent("addLink");
clickLink("addLink");
assertTitleEquals("Widget Add Page");
beginAt("/mainPage");
assertLinkPresentWithText("Edit Widget");
clickLinkWithText("Edit Widget");
assertTitleEquals("Widget Edit Page");
}

Working With Forms

You can navigate to a page with

o a form
o check for the presence and correct default values of form elements,
o set form element values and
o submit the form.

public void testFormSubmission() {

beginAt("/info.html");
assertFormPresent("expectedFormName");
assertFormElementPresent("field1");
assertFormElementEquals("field2", "field2_defaultValue");
setFormElement("field1", "value1");
setFormElement("fieldn", "valuen");
submit();
}

You can also check for the presence of submit buttons on the form and submit
with a specific button.
 public void testFormSubmission() {
beginAt("/info.html");
assertFormPresent("expectedFormName");
assertSubmitButtonPresent("Add");
assertSubmitButtonPresent("Modify");
setFormElement("field1", "value1");
submit("Modify");
}

For pages with more than one form, jWebUnit will establish which form is being
worked with implicitly from the form elements checked or set.
You can also set the form explicitly by form id or name:

public void testBottomFormSubmission() {

beginAt("/twoForm.html");
setWorkingForm("bottomForm");
submit();
}

You can work with non-submit (type='button') buttons as well:

public void testPopupButton() {

beginAt("/info.html");
assertButtonPresent("popupButtonId"); //clickButton will assert
this also.
clickButton("popupButtonId");
assertWindowPresent("popupWindow");
}

In the above examples, we are working with submit buttons and form elements by their
name. For form elements, it is possible to work with them by label (string followed by
colon before input element). Before using this approach, consider that the display label
may change, but the submission name of the element will probably remain static.

public void testFormSubmission() {

beginAt("/form.html");
assertFormElementPresentWithLabel("Credit Card Number");
setFormElementWithLabel("Credit Card Number", "myNumber");
submit();
}

Working With Frames and Windows

You can assert the presence of and navigate to windows by name.

If clicking on a button on the root page should open a window, you could test for
this and go to the popup window as follows:

public void testPopupWindow() {

beginAt("/rootPage.html");
clickLink("popupLink");
assertWindowPresent("popupWindow): //optional - gotoWindow
//will
 //perform this assertion.
gotoWindow("popupWindow");
...
gotoRootWindow(); //Use this method to return to root window.
}

You can work with frames in a similar manner:

public void testFrame() {

beginAt("/info.html");
assertFramePresent("contentFrame"); //optional as window above.
gotoFrame("contentFrame");
...
}

Validating Page Content

Once you have navigated to the page you wish to test, you can call the assertions
provided by jWebUnit to verify it's correctness.

public void testCorrectness() {

beginAt("/mainPage");
assertTitleEquals("Main Page");
assertLinkPresentWithText("Add Widget");
clickLinkWithText("Add Widget");
setFormElement("widgetName", "My Widget");
submit();
assertTextPresent("Widget successfully added."):
}

Validating Table Content

A number of assertions are provided by jWebUnit to validate the contents of

tables on a page.
You can simply check for the presence of text within a table, or check layout of
all or a portion of the table.
HttpUnit is used to purge empty rows and columns from the actual table before
comparison, so you may leave spacer cells and rows out of your check.

The below test validates against this html table (the table id attribute is "ageTable"):

Name Age
Jim 30ish
Wilkes 20ish

public void testAgeTable() {

beginAt("/agePage");
//check that table is present
assertTablePresent("ageTable");
//check that a single string is present somewhere in table
 assertTextInTable("ageTable", "Jim");
//check that a set of strings are present somewhere in table
assertTextInTable("ageTable",
new String[] {"Jim", "Wilkes"});
//check composition of table rows/columns
assertTableEquals("ageTable",
new String[][] {{"Name", "Age"},
{"Jim", "30ish"},
{"Wilkes", "20ish"}});
}

If you need to validate non-blank table cells that span more than a single column,
a set of classes are provided which represent expected tables, rows, and cells.

Age Table
Name Age
Subhajit 25
Hari 23
public void testAgeTable() {
beginAt("/agePage");
ExpectedTable ageTable = new ExpectedTable(new Object[][] {
{new ExpectedCell("Age Table", 2},
{"Name", "Age"},
{"Subhajit", "25"},
{"Hari", "23"}
});
assertTableEquals("ageTable", expectedAgeTable);
}

Using Element IDs to Validate Content

jWebUnit allows you to check for the presence of any html element by its id, or
for text in an element.
This can be a useful trick to check for the presence of some logical part of the
page.
In the case of free floating text, a span element can be used to surround the text
and give it a logical id:

<span id="welcomeMessage">Welcome, Joe User!</span>;

public void testWelcomeMessage() {

beginAt("/mainPage");
//check for presence of welcome message by text
assertTextPresent("Welcome, Joe User!");
//check for presence of welcome message by element id
assertElementPresent("welcomeMessage");
 //check for text within an element
assertTextInElement("welcomeMessage", "Joe User");
}

Using Property Files to Validate Content

One useful testing trick is to use property files for your expected values rather
than hard-coded strings.
This is especially useful if your application uses property files as a source for
static text and messages.
The same files can be used to provide the expected values for the tests.
For convenience, most of the jWebUnit assertions that take strings for the
expected have an equivalent assertion that will take a property file key.
TestContext is used to set the bundle to be used as well as the Locale (default is
Locale.getDefault()).

public void setUp() throws Exception {

getTestContext().setbaseUrl("http://myserver:8080/myapp");
getTestContext().setResourceBundleName("ApplicationResources");
}

public void testMainPage() {

beginAt("/mainPage");
assertTitleEqualsKey("title.mainPage");
assertKeyPresent("message.welcome");
assertKeyInTable("mainPageTable", "header.mainPageTable");
}

getMessage() method on WebTester and WebTestCase that can be used to access

resource bundle messages directly in your tests.

Whether to check for a given logical chunk of text by hard-coded string, property file
lookup, or by use of an element id is up to you.