Maven EMMA plugin

The Maven EMMA allows EMMA to be integrated into Maven projects. EMMA is an open-source toolkit for measuring and reporting Java code coverage. EMMA distinguishes itself from other tools by going after a unique feature combination: support for large-scale enterprise software development while keeping individual developer's work fast and iterative. Every developer on your team can now get code coverage for free and they can get it fast!

Installing the Maven EMMA Plugin

  • Automatic install: To automatically install the plugin, type the following on a single line: 

              maven plugin:download 
            -DgroupId=emma
            -DartifactId=maven-emma-plugin
            -Dversion={version}

    where {version} is the release number you want to install. Maven will automatically download the plugin and install it, uninstalling any other version you may already have.

  • Manual install: Download the Maven EMMA Plugin jar and copy it in {MAVEN_HOME}/plugins where {MAVEN_HOME} is the location where you have installed Maven. Make sure you also remove any previous EMMA plugin from {MAVEN_HOME}/plugins and delete your {USER_HOME}/.maven/plugins directory.

Using the EMMA plugin

There are 3 possible ways of running the plugin (Note that if you're in a multiproject setup, running the plugin for multiprojects is not yet supported):

  • All in one: You'll either call the emma goal or add the maven-emma-plugin report to the reports section in your POM. This will instrument your source code, run your project's tests on the instrumented code and generate EMMA reports.
  • In 2 steps: You'll call emma:test which will instrument your source code and run your project's tests on the instrumented code. You'll then need to call emma:report to generate the reports to .../target/docs/coverage.
  • In 3 steps: You'll call emma:on followed by whatever other goal you wish (for example maven emma:on war.) This will instrument your source code. Then you'll run any goal that tests your artifacts. For example in the case of a WAR you can use HttpUnit/HtmlUnit to run functional tests. The test of your artifact will fill the EMMA database with data. Finally you'll run emma:report to generate the reports to .../target/docs/coverage..

If you have detailed questions about how EMMA operates, or problems, please review the main EMMA FAQ and documentation at http://emma.sourceforge.net/. The maven EMMA plugin simply wraps the EMMA Ant tasks, so it behaves in a very similar way. Specifically, if you have questions about getting EMMA coverage from tests run in an application server, search the main EMMA FAQ for 'application server'.

Alternate EMMA-hosted Maven Repository

All EMMA jars and plugins will be uploaded to the central Maven repository at http://www.ibiblio.org/maven/emma/. However, if they are not availalbe on ibiblio for some reason, there is also an alternate repository hosted at http://emma.sourceforge.net/maven/

If you want to use this repository, simply add it to your comma-delimited maven.repo.remote property. For example: 

        maven.repo.remote=http://www.ibiblio.org/maven/, http://emma.sourceforge.net/maven/

Important Notes

  • A primary goal of the maven EMMA plugin is to avoid the possibility of shipping EMMA-instrumented classes as part of a production artifact. To accomplish this, there is a "redirect" option controlled by the maven.emma.redirect property, which defaults to 'true'. When this property is true, and the the EMMA plugin is enabled (by running an EMMA goal or calling emma:on), all instrumented classes are compiled to an alternate location. This is accomplished by overriding the "maven.build.dest" and "maven.test.dest" (if tests are instrumented) directory properties. A side effect of this approach is that some existing custom maven scripts may not work correctly if the paths to these directories are hard-coded, rather than using the standard properties defined by maven. To avoid this situation, ensure that you use the following properties in any custom scripts:
    • ${maven.build.dir} INSTEAD OF ${basedir}/target
    • ${maven.build.dest} INSTEAD OF ${basedir}/target/classes
    • ${maven.test.dest} INSTEAD OF ${basedir}/target/test-classes
  • The EMMA Maven plugin uses the maven.junit.sysproperties to define the EMMA emma.coverage.out.file. If you want to redefine maven.junit.sysproperties programatically at build-time (after emma initializes, but before tests are run), then you must preserve the existing value. If you just define the maven.junit.sysproperties value in a property file, then you don't have to worry (the plugin will preserve it).
  • If you are performing your own offline instrumentation (for container tests, for example), ensure that:
    1. All data files generated by emma are named according to emma conventions. Metadata should end in *.em, runtime coverage data should end in *.ec.
    2. All data files generated by EMMA are stored in the ${maven.emma.data.dir} dir, which is .../target/emma/data by default.
  • Not all EMMA properties are exposed as maven plugin properties. EMMA has a very flexible approach to property specification, allowing you many different options for specifying properties. The maven plugin simply invokes the EMMA Ant tasks, so all of the EMMA documentation about specifying properties applies to the plugin also. See the EMMA Users Guide and Reference Manual for more information, specifically the "EMMA Property Reference" section.