Chapter 2. EMMA Tool Reference

1. Overview

EMMA functionality is implemented by a set of components responsible for class instrumentation, metadata and coverage data processing, and coverage report generation. Each component has adapters that expose its functionality as an ANT task and a command line tool. To reflect this design, each of the following reference subsections starts by detailing the overall functionality of a given component, followed by its concrete ANT and command line usage.

The following table summarizes EMMA ANT tasks and their equivalent command line tools:

Table 2.1. EMMA ANT tasks and command line tools

ANT task	Command line tool	Functionality	Output
on-the-fly processing mode
<emmajava>	emmarun	Executes a standalone Java application in EMMA instrumenting classloader without a separate instrumentation phase.	One or several coverage reports and (optionally) a coverage session raw data file.
offline processing mode
<instr> subtask	instr command	Instruments a set of classes in a given list of directories and/or archives and output.	Instrumented classes and archives and a coverage metadata file.
<report> subtask	report command	Combines class metadata and coverage runtime data to produce coverage reports.	One or several coverage reports (plain text, HTML, XML).
<merge> subtask	merge command	Merges and compacts several metadata, coverage, or session data files.	A single merged coverage session data file.

Subtasks and commands. For reasons that include modularity and consistency of common option behavior EMMA offline coverage tools are used as subtasks of the "umbrella" <emma> ANT task:


    <emma ...>
      <merge ...>
        ...
      </merge>
      <report ...>
        ...
      </report>
    </emma>

or as subcommands of the "umbrella" emma command line command:

>java emma instr -ip out/classes/ ...
>java emma report -in coverage.em,coverage.ec ...

Note that in the ANT case, <emma> can contain an arbitrary sequence of subtasks (including mutliple subtasks of the same kind, which are executed in the exact sequence as they are specified). In addition to the already mentioned advantages, this allows entire blocks of EMMA tool invocations to be enabled/disabled and configured using attributes of the parent <emma> ANT task.

EMMA properties cascade. Some aspects of EMMA tool/task behavior can be modified using properties which can be set in a variety of ways: via JVM system properties, via an external file, via ANT (sub)task attributes or command line tool options. The task-subtask organization helps with this EMMA configuration as well. The general rule of thumb here is that properties within a more specific context (an ANT subtask vs <emma> parent task, a tool setting vs a global JVM property, etc) inherit their values from the surrounding contexts, but can also override them. For complete details see EMMA property lookup order.

In the remainder of this manual, the same tool will be frequently referred to as <ANT_tool_name>/command_line_tool_name.

Overall EMMA processing sequence. The general sequence of steps when using EMMA depends on your chosen coverage mode:

When using EMMA's on-the-fly coverage mode, there is little to do in addition to how you would normally run your application or testsuite: you use <emmajava>/emmarun as the new startup class and optionally tell it where to place the coverage report(s)^[2].
When using EMMA's offline coverage mode, the general sequence of tool/task invocations is:
1. In one or several passes, use <instr>/instr to instrument class directories and archive files.
2. Execute your application or test suite using the instrumented classes (one or several runs).
3. Optionally, merge and compact all metadata and runtime coverage files using <merge>/merge.
4. In one or several passes, use <report>/report to combine class metadata with the desired runtime coverage data profile(s) and generate the desired coverage report(s).

EMMA data files are untyped. EMMA tools use binary data files for storing instrumentation and runtime coverage results. EMMA files are not typed: they do not require a particular name or extension. Furthermore, each data file is a mini-database that acts as an envelope for an arbitrary sequence of metadata and/or runtime coverage data dumps. It is up to the user how to structure their work with EMMA: either accumulate everything in a single file or use a dedicated file for every tool. The only restriction is that EMMA files can only grow (once new data is merged in, it cannot be removed).

^[2]Usually, <emmajava> (emmarun) runs correspond to completely independent application/testsuite runs. However, its -raw option could be used to retain coverage session data files across different runs, to be processed later by tools like <report>/report and <merge>/merge.


Chapter 1. Installation and System Requirements		2. <emmajava>/emmarun