Emma: Quick Reference

Introduction

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!

Chances are, you've come here already knowing what coverage is all about and are, in fact, wondering what EMMA offers and why it is worth checking out. Explore the rest of this site to see why.

EMMA features at a glance

• EMMA can instrument classes for coverage either offline (before they are loaded) or on the fly (using an instrumenting application classloader).
• Supported coverage types: class, method, line, basic block. EMMA can detect when a single source code line is covered only partially.
• Coverage stats are aggregated at method, class, package, and "all classes" levels.
• Output report types: plain text, HTML, XML. All report types support drill-down, to a user-controlled detail depth. The HTML report supports source code linking.
• Output reports can highlight items with coverage levels below user-provided thresholds.
• Coverage data obtained in different instrumentation or test runs can be merged together.
• EMMA does not require access to the source code and degrades gracefully with decreasing amount of debug information available in the input classes.
• EMMA can instrument individial .class files or entire .jars (in place, if desired). Efficient coverage subset filtering is possible, too.
• Makefile and ANT build integration are supported on equal footing.
• EMMA is quite fast: the runtime overhead of added instrumentation is small (5-20%) and the bytecode instrumentor itself is very fast (mostly limited by file I/O speed). Memory overhead is a few hundred bytes per Java class.
• EMMA is 100% pure Java, has no external library dependencies, and works in any Java 2 JVM.

Use EMMA in WebLogic

First of all, there is little chance that you will be able to use the on-the-fly mode (emmarun) with a full-blown J2EE container. The reason lies in the fact that many J2EE features require specialized classloading that will happen outside of EMMA instrumenting classloader. The server might run fine, but you will likely get no coverage data.

Thus, the correct procedure is to instrument your classes prior to deployment (offline mode). Offline instrumentation always follows the same compile/instrument/package/deploy/get coverage/generate reports sequence. Follow these steps:

1. use EMMA's instr tool to instrument the desired classes. This can be done as a post-compilation step, before packaging. However, many users also find it convenient to let EMMA process their jars directly (either in-place, using overwrite mode, or by creating separate instrumented copies of everything, in fullcopy mode);
2. do your J2EE packaging as normal, but do not include emma.jar as a lib at this level, that is, within your .war, .ear, etc;
3. locate whichever JRE is used by the container and copy emma.jar into its <jre dir>/lib/ext directory. If that is impossible, add emma.jar to the server classpath (in a server-specific way);
4. deploy your instrumented classes, .jars, .wars, .ears, etc and exercise/test your J2EE application via your client-side testcases or interactively or whichever way you do it;
5. to get a coverage dump file, you have three options described in What options exist to control when EMMA dumps runtime coverage data?. It is highly recommended that you use coverage.get control command with the ctl tool available in v2.1.

Example, Offline Mode with Weblogic

This example tests the PokerHand class via a simple web app, where an HTML file is used to invoke the PokerHand class via a servlet. The build steps are as follows:

1. The Ant build compiles the Java source and instruments the classes.
2. The instrumented classes and web resources are bundled into a WAR file.
3. Tomcat must have access to the Emma jar. One way is to copy emma.jar to the $JAVA_HOME/jre/lib/ext directory, where JAVA_HOME is the JVM used by Tomcat.
4. The user deploys the WAR file, starts Tomcat, and tests via the HTML page.
5. When Tomcat is shutdown, "coverage.ec" is written to $TOMCAT_HOME/bin.
6. The above file is copied to the example directory so that the report can be generated.

Again, the resulting report is similar, where the coverage level is a direct reflection of the number of tests explored via the browser.
This example exercises PokerHand.java via the PokerHandServlet, using Emma to report on the code-coverage.

It uses the Emma's "offline mode" to instrument the Java classes before building a war file.  After exercising the servlet, Emma is used to generate a report.

Run Build.xml
this will build ./dist/pokerhand.war, and this step may depend on emma_ant.jar.

 

<?xml version="1.0"?>

<project name="PokerHand" default="build" basedir=".">

 <property name="classes.dir" value="${basedir}/classes" />
 <property name="coverage.dir" value="${basedir}/coverage" />
 <property name="dist.dir" value="${basedir}/dist" />
 <property name="instr.dir" value="${basedir}/classes_instr" />
 <property name="lib.dir" value="${basedir}/lib" />
 <property name="src.dir" value="${basedir}/src" />
 <property name="web.dir" value="${basedir}/web" />

 <target name="init">
  <mkdir dir="${classes.dir}" />
  <mkdir dir="${instr.dir}" />
  <mkdir dir="${coverage.dir}" />
  <mkdir dir="${dist.dir}" />
  <path id="run.classpath">
   <pathelement location="${classes.dir}" />
  </path>
 </target>

 <target name="compile" depends="init" description="typical Java compile">
  <javac debug="on" srcdir="${src.dir}" destdir="${classes.dir}" classpath="${lib.dir}/junit.jar;${lib.dir}/servlet-api.jar" />
 </target>

 <target name="clean" description="cleans directories">
  <delete dir="${classes.dir}" />
  <delete dir="${classes_instr.dir}" />
  <delete dir="${coverage.dir}" />
  <delete dir="${instr.dir}" />
  <delete dir="${dist.dir}" />
 </target>

 <!-- path element used by EMMA taskdef below: -->
 <path id="emma.lib">
  <pathelement location="${lib.dir}/emma.jar" />
  <pathelement location="${lib.dir}/emma_ant.jar" />
 </path>

 <!-- this loads <emma> and <emmajava> custom tasks: -->
 <taskdef resource="emma_ant.properties" classpathref="emma.lib" />

 <target name="emma" description="turns on EMMA's instrumentation/reporting">
  <property name="emma.enabled" value="true" />
  <property name="out.instr.dir" value="${basedir}/outinstr" />
  <mkdir dir="${out.instr.dir}" />
  <property name="emma.filter" value="" />
 </target>

 <target name="instrument" depends="init, compile" description="instruments the Java classes">
  <emma enabled="true">
   <instr instrpathref="run.classpath" destdir="${instr.dir}" metadatafile="${coverage.dir}/metadata.emma" merge="true">
   </instr>
  </emma>
 </target>

 <target name="build" depends="instrument" description="builds the war file">
  <zip destfile="${dist.dir}/pokerhand.war">
   <zipfileset dir="${instr.dir}" prefix="WEB-INF/classes" />
   <zipfileset dir="${web.dir}" />
  </zip>
 </target>
</project>

 

Copy emma.jar file to $DOMAIN_HOME/lib, and deploy war file into Weblogic.

Run app.

Copy coverage.ec from $DOMAIN_HOME to this directory.

Run run.bat (Windows) or run.sh (Linux).
java -classpath emma.jar emma report -r html -in coverage.ec,coverage/metadata.emma -sourcepath src

Sample report

Sample code

Password: hzwangbing.spaces.live.com

Emma-Test.zip

Download （Namipan） Download （SkyDrive）