Documentation

Introduction

Using J2MEUnit is very similar to the original JUnit framework. If you haven't used JUnit before we recommend that you first have a look at the documentation on the JUnit site to get an understanding of what unit testing is and how the framework is used to develop unit tests. This site will mainly explain the differences of J2MEUnit and how unit tests can be written in the limited Java environment of J2ME.

Why Is a New Framework Necessary?

The differences between J2MEUnit and JUnit are mainly caused by the fact that on the micro edition platform of Java there is no reflection API available. That means that all the features of JUnit that use reflection to build and run test suites automatically can't be implemented as easily in the J2ME environment. J2MEUnit tries to alleviate this by providing some new mechanisms or by implementing them differently, as described in the following sections.

Described hereafter is version 1.1 (and higher) of J2MEUnit which is the first version that is available on Sourceforge. Version 1.0 was originally developed by RoleModel Software. Version 1.1 contains a few changes that make the handling of tests in the non-reflection environment of J2ME easier. The version 1.0 test handling mechanism, although not described here, is still available so that tests classes built for version 1.0 will still work.

Building a Test Suite

Test cases are built similar as in JUnit: you create your test methods in a subclass of j2meunit.framework.TestCase and optionally initialize and clean up test data by overloading the methods setUp() and tearDown(). Although there is no reflection API to determine test methods automatically we recommend to follow the JUnit convention to let all test method names start with "test".

Because reflection is not available developers always have to build the test suites that shall be run explicitly (as it is possible in JUnit too). This is done by implementing the method suite() (which is an instance method in J2MEUnit and not static as in JUnit!) and returning a new instance of the class TestSuite that contains all test methods from the test case that a developer wants to include in the test suite.

The best way to add test methods to a suite is with instances of j2meunit.framework.TestMethod. TestMethod is an interface with a single method run(TestCase) which can be implemented most easily with anonymous inner classes. The argument to run() at test execeution time is the test case the TestMethod instance is associated with. So all that needs to be done in the implementation of the run method is to call the corresponding test method in the test case instance after casting it to the correct type. Here is an example from the method suite() in the class j2meunit.examples.TestOne that can be found in the source code distribution of J2MEUnit:

aSuite.addTest(new TestOne("testOne",
    new TestMethod()
    {
         public void run(TestCase tc)
        {
            ((TestOne) tc).testOne();
        }
    }));

Or, the same code but more compact:

aSuite.addTest(new TestOne("testOne", new TestMethod()
{  public void run(TestCase tc) {((TestOne) tc).testOne(); } }));

Running Tests

Tests can be run through a special class, called TestRunner as in JUnit. J2MEUnit comes with two implementations of TestRunner. The first one is j2meunit.textui.TestRunner and is similar to the command line TestRunner from JUnit. This implementation is from the original J2MEUnit version 1.0 and can only be run from J2ME command line environments.

Because today J2ME applications are normally developed and tested in the J2ME environment of Sun's Wireless Toolkit (WTK) J2MEUnit from version 1.1 on comes with an enhanced TestRunner implemented as a MIDlet that can be run in the WTK emulator or on a real J2ME device like a mobile phone. Therefore it is recommended to use the implementation j2meunit.midletui.TestRunner to run tests.

Creating an instance of the test runner MIDlet is simple and straightforward, the only thing that needs to be done is to tell the test runner the tests to execute. This can be done by subclassing j2meunit.midletui.TestRunner, implementing the startApp() method (of the J2ME MIDlet base class), and calling the start() method of TestRunner with the test cases and/or suites as parameters as in the ExampleTestMidlet class that is part of the J2MEUnit source distribution:

protected void startApp()
{
	start(new String[] { "j2meunit.examples.TestAll" });
}

But there's even a simpler method to run tests without the need to subclass TestRunner. The j2meunit.midletui.TestRunner class looks for a MIDlet property called J2MEUnitTestClasses when it is started as a MIDlet (MIDlet properties can be set in the JAD file or the JAR archive's manifest file). That means that you can simply set this property and invoke TestRunner directly. This is used in the test classes of J2MEUnit to invoke the AllTests test suite. If you download the source code distribution you can study the XML build files of J2MEUnit to see how this is used to run the J2MEUnit tests.

By the way, J2MEUnit uses the Antenna toolkit for Ant which provides additional Ant tasks for J2ME projects like preverification and others. The J2MEUnit build files can serve as an example how Antenna can be used to built J2ME projects.

In all other aspects J2MEUnit works like the standard JUnit toolkit. For example, fixtures for tests are managed as usual through the setUp() and tearDown() methods as in JUnit. If you need more information about general unit testing features please have a look at the numerous literature that is available on this topic as books or on the internet. For further questions regarding the J2MEUnit classes you can also have a look at the Javadoc API documentation which is part of the source code distribution or at the source code itself.