EMMA

This plugin uses the eponym SourceForge project to provide Java code coverage.

Declaration

Here is the recommended configuration for EMMA plugin:

  <plugin name="emma">
    <attribute name="emma.set.list" value="application"/>
    <attribute name="emma.mode" value="offline"/>
    <attribute name="emma.switch" value="emma"/>
  </plugin>

Usage

EMMA is a Java code coverage tool that is designed to work with instrumented classes. This instrumentation step can be done on-the-fly by a dedicated ClassLoader with non instrumented classes (online mode), or in any JVM runtime context with instrumented classes (offline mode).

Application must be executed after EMMA instrumentation to collect code coverage data, then the report generation provides you a comfortable way to analyze the code that has not been executed. You can run as many execution targets as possible or even the same target many times, code coverage data are merged with any previous execution data.

Offline mode

The offline mode should be preferred to collect code coverage information in any context: simple application, test cases or J2EE application deployed as a EAR or a WAR.

With the recommended configuration provided below, you have to use compile target to instrument classes before executing your application with the emma property set on the command line:

  ant compile junit.startdev.all startdev.module.eu.mymodule.myeu -Demma=t

Code coverage information are collected, ready to be used in report generation.

Online mode

The online mode (on-the-fly) should be reserved to simple application and test cases execution.

Its advantage is to skip the classes instrumentation step needed for the offline mode.

  <plugin name="emma">
    <attribute name="emma.set.list" value="application"/>
    <attribute name="emma.mode" value="online"/>
    <attribute name="emma.switch" value="emma"/>
  </plugin>

As instrumentation step is not needed, if your classes are already compiled, you can execute your runtime targets directly with emma set.

  ant junit.startdev.all startdev.module.eu.mymodule.myeu -Demma=t

Report generation

The target emma.report generates a code coverage report per module set with currently available code coverage data, generated by EMMA-enabled execution targets. A module can be registered in one or many sets thank to the set attribute. Please read details about module sets.

For more details about EMMA usage, link report interpretation, please read the tool documentation.

When used with the website plugin, EMMA are generated in the reports.directory and a report entry is added to the project reports overview.

Advanced manual configuration

This section describes how to enable EMMA support with a more fine grain, it is reserved for expert users. In that case, the global plugin emma.mode and emma.switch must not be set.

The hook registrations described here are exactly the same that the plugin configuration does automatically on runnable module execution units marked with the emma.mode attribute.

Advanced offline mode

Classes instrumentation is done by registering the following hook in your project description:

  <!-- add emma.instrumentation target in the compile hook -->
  <hook name="post.javac.[module]" target="emma.instrumentation.module"/>

If the hook is at the project level, it applies to all available modules. If the hook is declared at the module level, it only applies to the concerned module.

Classes instrumentation is not enough. EMMA jar must be available in your Java command ClassPath. To do so, the runtime.hook.emma.offline target must be registered in the runtime.[module].[eu] hook chain, at least for runnable module execution units.

  <hook name="runtime.[module].[eu]" target="runtime.hook.emma.offline"/>

If the hook is at the project level (faster but not advised), all runnable execution unit modules are concerned. If declared at the module level, all execution units of the module are concerned. If declared at the execution unit level, only that execution unit is concerned.

As a result, code coverage data are collected for modules that are both instrumented (emma.instrumentation.module hook) and executed by a runtime target with the runtime.hook.emma.offline target registered in the runtime hook chain.

Advanced on-the-fly mode

The instrumentation hook must be removed (emma.instrumentation.module) and the runtime hook must be renamed: use runtime.hook.emma.online instead of runtime.hook.emma.offline at the same place you have defined your module and execution unit hooks.

  <hook 
    name="runtime.[module].[eu]"
    target="runtime.hook.emma.online"
    if="emma"/>

  ant startdev.module.eu.mymodule.myeu -Demma=

Targets

• emma.report generates reports for all module sets (emma.set.list).
• emma.report.set generates the report for a specific set.
• runtime.hook.emma.offline is the runtime hook to enable offline code coverage in a Java command with instrumented classes.
• runtime.hook.emma.online is the runtime hook to enable online code coverage in a Java command with non instrumented classes.
• emma.instrument invokes emma.instrument.module on all modules.
• emma.instrument.module invokes EMMA incremental (only modified classes) instrumentation on a module classes directory. This target is designed to be registered in the post.javac.[module] hook chain.

Attributes

Global

• emma.mode is the default code coverage mode used for all runnable modules. If set to offline, all module classes are instrumented.
• emma.switch is the name of a property to enable instrumentation and code coverage support. If not defined, support is permanent. If defined, compilation must be done with this property set to enable instrumentation, and runtime targets must be executed also with this property set.
• emma.set.list is the module set list for which the emma.report target generates reports by default. Default value is the list of known module sets.

Per module

• emma.mode is the module code coverage mode. If set to offline and global mode is not offline, then the module classes are instrumented.

Per execution unit

• emma.mode is the execution unit code coverage mode. If set to offline and global mode is not offline, then the module classes are instrumented.

Known issue

• EMMA on-the-fly code coverage analysis is not able to work with already instrumented classes. As a result, you have to clean and compile again your instrumented modules to switch from the offline usage to the online mode.
• Current version outputs a text report in dist/runtime when running a command in on-the-fly mode.