EMMA: Quick Start |
This page shows how easy it is to use EMMA by doing a few command-line runs (if you'd rather work with specially prepared examples or start converting an existing ANT build to EMMA, you should read the user guide instead). I am going to use command line for a couple of reasons: to avoid spending time with an ANT setup right now and because EMMA command line tools can be used on top of an existing ANT build without changing it (e.g., you can instrument your build's output with a single command). The only requirement here is to have emma.jar, which you can get from either the complete or the smaller emma-<release>-lib.zip download.
(All EMMA tools are implemented as bean-like objects. The command line utilities and ANT tasks are mere frontend drivers for those, so everything you can do on a command line you can do in ANT and vice versa.)
On-the-fly instrumentation | ||
This means taking an existing application and running it using EMMA instrumenting application runner. You can try the SwingSet2 demo shipped with the JDK:
>java -cp emma.jar emmarun -jar .../jdk1.4.2/demo/jfc/SwingSet2/SwingSet2.jar
(As you can see, running the demo through EMMA is basically inserting emmarun between the JVM and the application: it just doesn't get any easier!) Play with the Swing demo a bit and then close it. You will see EMMA writing a plain text coverage report (coverage.txt) to the current directory. The plain text report is meant mostly for quick informal testing. It defaults to showing just the overall and package-level stats and most of it is self-explanatory:
OVERALL COVERAGE SUMMARY: [class, %] [method, %] [block, %] [line, %] [name] 98% (121/123)! 64% (312/489)! 81% (15500/19172) 77% (2633.6/3441)! all classes OVERALL STATS SUMMARY: total packages: 1 total classes: 123 total methods: 489 total executable files: 31 total executable lines: 3441 COVERAGE BREAKDOWN BY PACKAGE: [class, %] [method, %] [block, %] [line, %] [name] 98% (121/123)! 64% (312/489)! 81% (15500/19172) 77% (2633.6/3441)! default package
For every type of coverage the overall coverage percentage is shown, as well the actual percentage ratio: the latter is important for knowing which areas need more testing work (a half-covered package with 500 classes needs more attention than a half-covered package with 10 classes).
The odd-looking exclamation marks in some columns denote items that fail default coverage criteria (e.g., 80% for line coverage and 70% for method coverage).
HTML report | ||
Well, there is only so far you can get trying to display hierarchical and columnar data in a plain text file. Next, try the HTML report (dumped starting with coverage/index.html):
>java -cp emma.jar emmarun -r html -jar .../jdk1.4.2/demo/jfc/SwingSet2/SwingSet2.jar
Now, this kind of report is much easier to browse (go here for some samples). And if you link to the demo sources by adding -sp .../jdk1.4.2/demo/jfc/SwingSet2/src option, you will actually see individual line coverage marked up in the source code embedded within the HTML.
Also, it isn't necessary to generate reports at application exit time: you can dump coverage data into a binary file to be used for later report generation. There are lots of other options we could give to emmarun, but right now let's try something entirely different.
Offline instrumentation | ||
Instrumenting an application on-the-fly as we've done above isn't always possible. For example, a J2EE container could do its own fancy class loading, which is not easy to hook into. Well, in such case EMMA's offline instrumentor is the solution.
To try it, make a local copy of SwingSet2.jar and instruct EMMA to instrument it in-place:
>cp .../jdk1.4.2/demo/jfc/SwingSet2/SwingSet2.jar . >java -cp emma.jar emma instr -m overwrite -cp SwingSet2.jar
EMMA will drop certain metadata information into coverage.em and the jar will now contain classes instrumented for coverage. (Note that instead of the Swing demo you could have done the same with your own classes and jars in an existing build.) Because they now depend on certain EMMA runtime classes, we need to add emma.jar to the application execution classpath:
>java -cp SwingSet2.jar:emma.jar SwingSet2
Again, play with the Swing demo a bit and close it. You will see EMMA writing some runtime coverage data into coverage.ec (both types of data could also go in the same file, but that's not the default behavior). Now, to produce a coverage report simply combine metadata with runtime coverage data in the report generator tool:
>java -cp emma.jar emma report -r html -in coverage.em,coverage.ec
Forward the spears | ||
This short exercise ends here. If you're curious enough you can read the command line tool usage (emma -h, or the reference manual) and experiment with other options, but I think you ought to test drive EMMA inside an ANT build and with a real product next. The user guide is a good document to read next.
