2.2. emmarun: instrumenting Java classes on-the-fly

2.2. emmarun: instrumenting Java classes on-the-fly
	2. Getting Started (command line)

Assuming you are in the examples directory of EMMA distribution, start by compiling the example source code:

>mkdir out 
>javac -d out -g src/*.java src/search/*.java

You can now run the main demo driver:

>java -cp out Main
main(): running doSearch()...
main(): done

To run the same program with coverage data collection, just insert emmarun in front of your program's main class name:

>java emmarun -cp out Main
main(): running doSearch()...
main(): done
EMMA: writing [txt] report to [...coverage.txt] ...

The default text coverage report is generated in the current directory:

[EMMA v2.0.3611 report, generated Sun Jan 11 14:18:08 CST 2004]
-------------------------------------------------------------------------------
OVERALL COVERAGE SUMMARY:
[class, %]      [method, %]     [block, %]      [line, %]       [name]
100% (3/3)      100% (7/7)      95%  (116/122)  100% (29/29)    all classes

OVERALL STATS SUMMARY:

total packages: 2
total classes:  3
total methods:  7
total executable files: 3
total executable lines: 29

COVERAGE BREAKDOWN BY PACKAGE:

[class, %]      [method, %]     [block, %]      [line, %]       [name]
100% (2/2)      100% (4/4)      91%  (64/70)    100% (18/18)    search
100% (1/1)      100% (3/3)      100% (52/52)    100% (11/11)    default package
-------------------------------------------------------------------------------

Code coverage has never been easier! This on-the-fly instrumentation mode is handy for light-weight testing of main() test methods, individual classes, and small- to- mid-size programs. emmarun also works well with Swing applications.

Other report types

By default, emmarun generates a plain-text report only. The default report's depth is all which means to show the overall coverage summary followed by breakdown by package. You can increase the default depth to include package and source file summaries. This and many other aspects of EMMA report generation can be configured using command line (-D<report property>=<value>) or an EMMA configuration file. See Chapter3, EMMA Property Reference in the reference manual for full details on EMMA configuration. Also, all EMMA command line tools provide usage information in response to -h option.

emmarun application runner uses an instrumenting classloader to add bytecode instrumentation to Java classes as they are being loaded by the JVM. For efficiency reasons, emmarun does not scan your entire classpath before it starts running. This has the side effect of only reporting on the classes that got loaded by the application. If your intent is to base coverage metrics on the full set of classes in the classpath, you can use the -f option.

Although it was not the case with this tutorial's sample code, chances are your application has third-party library dependencies and you are not interested in their coverage metrics. There are two ways to handle this:

List third-party libraries in the JVM's classpath, not emmarun's -cp option:
```
>java -cp ...somelib.jar emmarun -cp out Main
```
Use a coverage filter to make sure that only the classes of interest are instrumented:
```
>java emmarun -cp out;...somelib.jar -ix +Main,+search.*  Main
```

If these techniques are not sufficient (e.g., you need to exclude testcases from coverage and they are in the same Java packages as the application code and do not follow a sensible naming pattern), you can always switch to offline instrumentation as described next.

Further reading. This has been a quick intro to EMMA's on-the-fly command line instrumentation mode. For further details see Section2, <emmajava>/emmarun in the reference manual.


2. Getting Started (command line)		2.3. Offline mode: separating instrumentation and execution