EQUIP2 WebApp Unit Testing

Chris Greenhalgh, 2007-02-06

Introduction

It is (apparently) a *good thing* to develop your application together with Unit tests. These allow you to:

• develop the API (writing the tests first)
• know when it is working
• routinely perform regression tests as things change to make sure you haven't broken other things

Spring's dependency injection approach makes it relatively easy to test objects and parts of the system without having to run/test the whole web application.

This tutorial includes basic support for unit tests using JUnit. There are also specific examples of testing code which makes use of EQUIP2.

Defining and running tests

Running tests

The unit testing here is based on JUnit; refer to EQUIP2_WebApp_Configuring_and_Building for which version of Junit to get (4) and where to put it (in lib/junit-4.jar)

• builds the test source from the test/ directory into build/test/
• uses org.junit.runner.JUnitCore to run the tests in the specified classes (configured in the build target) [this should be changed to use the junit ant task! but i think pure JUnit 4 tasks may need Ant 1.7]
  

> ant test

Adding a new test

To create a new test make a new java source file in the test/ directory hierarchy (traditionally the package is the same as the class(es) being tested, and the name is 'meaningful').

You will need to import org.junit.Test and import static org.junit.Assert.*. Each test should be a public method, which you should tag with the (java 1.5) attribute org.junit.Test ('@Test'). The test method should create any required data, run the test, and check for the correct results using the org.junit.Assert.* static methods, e.g. 'assertTrue(boolean)', which requires the argument to be true to mark success.

If the correct outcome is to throw an exception then tag the method with the expected exception class as a parameter of the Test tag, e.g. '@Test(expected= IndexOutOfBoundsException.class)'. See the JUnit documentation (e.g. cookbook and Javadocs) for more details.

Add the name of your new test class to the argument list of the org.junit.runner.JUnitCore java command in the build.xml file.

Now run the test(s) again.

Creating Testing

Testing controllers

See the Spring documentation (e.g. the web MVC tutorial and the reference documentation (e.g. chapter 23)) for more suggestions on unit testing controllers, etc. Spring also has some 'mock' objects whic implement the HttpServletRequest/Response APIs for testing controllers - see the Spring package org.springframework.mock.web.

See also the combined example, below.

The general idea is:

• create a subset of the application class(es),
  
• either directly, using new, etc., or by creating Spring container instance(s) directly (based on the main application .xml configuration files, or versions specifically for testing)
  
• prime them with known (dummy) data,
• run the entry method for the code path to be tested (as if we were the container and/or the spring dispatcher),
• check (using JUnit assertX()) that the results are as expected.

Testing with a dataspace

EQUIP2 has a number of different dataspace implementation. The web application normally uses the persistent version based on Hibernate over a RDBMS. However, for testing, other implementation can be used (avoiding the need to have a real database with suitable test data in it).

The tests directory in this tutorial includes a drop-in replacement for the normal IDAllocator class, equip2.spring.db.IDAllocator. This replacement will work with a transient (testing) dataspace, whereas the normal version depends on Hibernate and an underlying JDBC connection. There is a unit test for this replacement allocator: equip2.webapptutorial.testing.TestIDAllocator.

Some useful utility functions are collected into equip2.webapptutorial.testing.TestingUtils, in particular newTransientDataspace(), which creates a transient dataspace (!) and readXmlDump(IDataspace,File), which reads the objects from an EQUIP2 XML dump into the dataspace.

The test equip2.webapptutorial.testing.TestSimpleDataspaceExample includes an example of setting up a transient dataspace and testing some simple dataspace operations.

Warning

• there is no string length limit in the transient datspace, unlike the SQL string length constraint that will become apparent when strings are persisted to the relational database
• if a class has a primitive-type property (e.g. int) then after storing in the database and retrieving this will have assumed its default value (0 or false), whereas it will not be forced to its default value by a transient dataspace (isSetX will still return false).

Combined testing example

• create an application context using a modified version of the main web application context definition, test/applicationContext.xml - this creates a transient dataspace without logging rather than a persistent dataspace.
• pre-populate the dataspace with data from an EQUIP2 XML dump file (in this case test/equip2/webapptutorial/testing/TestRegisterPlayer.dump.xml)
• create a nested application context using the actual servlet configuration, WEB-INF/publicweb-servlet.xml
• create a mock (fake) HTTP request, and cause (in this case) the player registration controller to handle it
• check the response from the controller

Note that it is often possible to test controllers without a full HTTP mock request, e.g. using a pre-populated command or form-backing object.

If core game functionality is separated into distinct objects then it may not be worthwhile recreating the full application/servlet context, but rather the objects may be created and initialised directly.

Changes

• Document created
• added combined test example and TestUtilities