Table of Contents

• Writing Tests
• XML Test Case Definitions
• Ant integration

Writing Tests

Certain patterns should be followed when writing your test cases. First, the test cases must contain a constructor of the form:

  ClassName(String name, UnitTestSpecification spec) {
    super(name, spec);
  }

Second, the test cases must contain a suite() method of the following form.

  public static Test suite() {
    return new TestSuite(ClassName.class);
  }

Finally, we recommend writing your tests in such a manner that they can take advantage of JSpecUnit's framework. Writing your tests so that they take inputs and compare the actual results to expected results can ultimately cut down on the redundant code that you write, and prevents hard-coding magic numbers into your tests themselves.

Here is an example of how tests might be written without the JSpecUnit framework. This example tests the retrieveUser method of the fictitious AccountRetriever class.

  public void testValidUser() throws Exception
  {
    AccountRetriever retriever = new AccountRetriever();
    User user = retriever.getUser("user1");
    assertTrue("User does not exist!", user != null);
  }
  
  public void testInvalidUser() throws Exception
  {
    AccountRetriever retriever = new AccountRetriever();
    User user = retriever.getUser("user2");
    assertTrue("User unexpectedly exists!", user == null);
  }
  
  public void testInvalidArgument() throws Exception
  {
    try
    {
      AccountRetriever retriever = new AccountRetriever();
      User user = retriever.getUser(null);
      fail("User retrieved without throwing an error!");
    }
    catch (Exception e)
    {
      ; // do nothing... we expected to catch an exception
    }
  }

The example involves writing three test cases that were written to test the same underlying method. Using JSpecUnit, this can be reduced to a single test. The parameters and expected behavior of the test for the parameters are pushed entirely into a configuration file.

  public void testGetUser() throws Exception
  {
    try
    {
      String testUser = testData.getInputParamValue("user");
      AccountRetriever retriever = new AccountRetriever();
      User user = retriever.getUser(testUser);
      assertTrue("Exepcted to fail with an exception while retrieving user", 
                   testData.getException() == null);
      boolean userExists = Boolean.getBoolean(testData.getExpectedResult("userExists"));
      assertTrue("User existince was expected to be " + userExists 
                 + " but was " + userExists, (user != null) == userExists);
    }
    catch (Exception e)
    {
      checkException(e);
    }
  }

XML Test Case Definitions

JSpecUnit's strengths come from allowing test inputs and the expected behavior for a set of inputs to be placed into a configuration file. While the exact specification for the XML can be obtained from the download, we realize that many of you don't have the time or inclination to do so in order to satisfy your curiousity about the XML format. So here's a quick example that shows the XML testing file that would be used for the above example.

<?xml version ="1.0" encoding = "UTF-8"?>
<package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="file:///jspecunit/xml/jspecunit.xsd">
  <packagename>com.foo</packagename>
  <classes>
    <class>
      <classname>AccountRetrieverTest</classname>
      <methods>
        <method>
          <methodname>testGetUser</methodname>
          <methodparams>
            <methodparam>
              <name>user</name>
              <type>String</type>
            </methodparam>
          </methodparams>
          <testcases>
            <testcase>
              <testcasename>valid user</testcasename>
              <inputparams>
                <inputparam>
                  <name>user</name>
                  <value>user1</value>
                </inputparam>
              </inputparams>
              <expectedresults>
                <expectedresult>
                  <name>userExists</name>
                  <type>Boolean</type>
                  <value>true</value>
                </expectedresult>
              </expectedresults>
            </testcase>
            <testcase>
              <testcasename>invalid user</testcasename>
              <inputparams>
                <inputparam>
                  <name>user2</name>
                  <value>foo</value>
                </inputparam>
              </inputparams>
              <expectedresults>
                <expectedresult>
                  <name>userExists</name>
                  <type>Boolean</type>
                  <value>false</value>
                </expectedresult>
              </expectedresults>
            </testcase>
            <testcase>
              <testcasename>invalid arguments</testcasename>
              <expectedresults>
                <expectedresult>
                  <name>userExists</name>
                  <type>Boolean</type>
                  <value>false</value>
                </expectedresult>
              </expectedresults>
              <exception>
                <type>com.foo.InvalidArgumentException</type>
                <message></message>
              </exception>
            </testcase>
          </testcases>
        </method>
      </methods>
    </class>
  </classes>
</package>

Ant integration

JSpecUnit contains an ant task that allows it to be executed from within an ant build file. Here is an example for how to do so.

    
 <target name="unittest">   
   <taskdef name="jspecunit" classname="jspecunit.antextension.JSpecUnitTask" 
               classpath="${jspecunit.jar}"/>
   <jspecunit todir="${report.dir}">
     <fileset dir="${unit-test.config.dir}" includes="**/*test-data.xml"/>
     <classpath>
       <pathelement location="${build.unit-test.classes.dir}"/>
     </classpath>
     <formatter type="xml"/>
   </jspecunit>

   <junitreport todir="${report.dir}">
     <fileset dir="${report.dir}"><include name="TEST-*.xml"/></fileset>
     <report todir="${report.dir}" format="frames"/>
   </junitreport>
 </target>