Before You Begin

First, check you have all the prerequisits:

Apache Ant (http://ant.apache.org)
Sun's Wireless Toolkit (http://java.sun.com/javame)
Cobertura for J2ME, available here.

Once unzipped the archive you have 2 different ways of using Cobertura for J2ME:

Use directly the ant tasks. You can find the specification of these tasks here. Also, the sample application provides a complete example of how to use these tasks.
Use the included build script. This script also uses the ant tasks but simplify their use. Please refer to the FAQ section for more information on how to use the included script.

Preparing for intrumentation

Instrumenting your application code requires to compile with debug information. Therefore make sure that you invoke the compiler with the correct options e.g.

javac -g ...

Instrumenting your code

The next step is to instrument the code you want the coverage metrics for. This is done in 2 easy steps:

In the Cobertura for J2ME directory (installation directory), open a command prompt and type the following command line
ant cobertura4j2me-instrument -Dpattern [PATTERNS]
where PATTERNS is the list of patterns of files to instrument.

For example, the following command will instrument the code in the package com.mycomp.mypackage:
ant cobertura4j2me-instrument -Dpattern "com/mycomp/mypackage/*.class"

Note: The file cobertura-instr.ser containing the intrumentation data is generated in the Cobertura for J2ME directory. This file should not be deleted!!
Now use your packager tool (e.g. antenna) to generate your application. The instrumented code will have been generated in the path.instrumented directory (defined in cobertura4j2me.properties) along with the coverage runtime library.

Don't forget that CLDC1.1 and the JSR75 FileConnection API are required to run the coverage data runtime library.

Alternatively, it is possible to automatically instrument your application as part of your antenna buils script. Please refer to the FAQ section for more information.

Running the tests

Simply run your tests as usual:

Install your test midlet to your device/emulator
and launch it

Note: Given that the midlet successfully completes - i.e. destroyApp() is invoked - the file cobertura.ser would have been generated in the directory set in path.device.data
Copy the generated file to the Cobertura for J2ME directory

tip If you run your test suite on Sun's Wireless Toolkit you should run it in the Trusted security domain (see FAQ for more information on security domain) so you won't get prompted every time the coverage data file is being accessed (through the FileConnection API).

Merging runtime and instrumentation data

Well done!! You have all the data you need to generate the report. However, we first need to merge the runtime and intrumentation data:

Simply type the following command line in the Cobertura for J2ME directory:

ant cobertura4j2me-merge

This will read cobertura-instr.ser and update cobertura.ser with all data.

This tool searches for all the *.ser files in the directory and merges all the data in cobertura.ser. Therefore, if you want to generate a report from different runs you just need to copy all the data files - after renaming them of course - and merge them.

Generating HTML report

Almost done. All you have to do is simply open a command prompt in Cobertura for J2ME and type:

ant cobertura4j2me-report -Dsource "pathtosourcedirectory"

Alternatively, it is possible the generate the report with no source code included:

ant cobertura4j2me-report-nosource

This means that the report will not contain any source code nor source metrics (CCN, NCSS, JVDC)

Note: If you have instrumented many classes, this might take some time, so be patient!

Then you should see a directory named report under the Cobertura for J2ME directory. It will contain the generated html report.