Headless Code Coverage for Equinox

This extension to Equinox integrates the EMMA code coverage library into OSGi/Equinox applications. Please also consider our new code coverage library JaCoCo which greatly simplifies the integration as it provides on-the-fly coverage data recording for any Java application (including OSGi frameworks).

EclEmma is a user interface centric tool implemented for and on top of the Eclipse IDE. EclEmma also provides support for code coverage analysis of Eclipse applications itself, e.g. for JUnit plug-in tests. While a code coverage tool within the IDE supports the individual developer with his/her daily work, so called headless tools are required for testing in automated environments like (continuous) build systems. Based on the techniques described in this paper the EclEmma Equinox Runtime easily adds code coverage to any Java application running on OSGi/Equinox.

Features

The EclEmma Equinox Runtime is a single plug-in that can be added to any Eclipse application and provides code coverage information for the executed Java code. It has several configuration options e.g. for selecting the plug-ins to analyze.

How does it work?

The EclEmma Equinox Runtime is a so called OSGi framework extension that uses specific hooks of the Equinox OSGi implementation to dynamically instrument plug-in classes using the EMMA code coverage library.

Usage

System Requirements

The EclEmma Code Coverage for Equinox runtime requires Eclipse 3.2 or higher and Java 1.4 or higher. As Eclipse/Equinox changed some internal APIs with 3.5, you need to select from different extension versions:

• Eclipse 3.2, 3.3, 3.4 → org.eclemma.runtime.equinox 1.0.0
• Eclipse 3.5 and later → org.eclemma.runtime.equinox 1.1.0

Headless Mode

This will be the typical scenario when you run you plug-in tests in your automated build.

• Download the latest version of the compiled bundle org.eclemma.runtime.equinox from the SF download page.
• Unzip the file in your Eclipse installation root. The expanded bundle org.eclemma.runtime.equinox has to be located in the plugins folder. This must be the same directory where the org.eclipse.osgi bundle is located. Using e.g. an extension site will not work! The org.eclemma.runtime.equinox must not be jared, as it contains another JAR which can not be loaded from a packaged bundles in case of framework extensions.
• Insert the following line into the ./configuration/config.ini file of your target Eclipse:

  osgi.framework.extensions=org.eclemma.runtime.equinox

  or add the same value as a Java system property using the -D parameter.

PDE Mode

If you want to study or modify the extension bundle you may directly import it to your PDE workspace and launch a Eclipse application in development mode. The extension works for any OSGi/Equinox based launch type, i.e. Eclipse application OSGi framework and JUnit plug-in test.

• Import the latest version of the extension bundle from the SVN repository at https://eclemma.svn.sourceforge.net/svnroot/eclemma/eclemma/trunk/org.eclemma.runtime.equinox.
• Due to the fact that Equinox needs any framework extension co-located with the OSGi framework bundle you need to also import org.eclipse.osgi into your workspace (from the Plug-Ins view's context menu select Import As → Source Project).
• Take a existing launch configuration or create a new one. Make sure that the org.eclemma.runtime.equinox and the org.eclipse.osgi bundle are enabled.
• On the Arguments tab insert the following definition in the VM arguments field:

  -Dosgi.framework.extensions=org.eclemma.runtime.equinox

Configuration Options

All configuration options are given by system properties. They can be passed into the JVM with the -D parameter. For example

  -Demma.session.out.file=testcoverage.es

will set the property emma.session.out.file to the value testcoverage.es. Note that the EclEmma Equinox Runtime will produce default results without any configuration options.

• eclemma.help
  Setting any value to this property prints help information to the console.
• eclemma.instrument.bundles
  Comma separated list of bundle ids that should be considered for code coverage analysis. Default: All bundles.
• emma.session.out.file
  Location of the EMMA session file where the coverage information will be written to. Default: coverage.es in the working directory.
• emma.session.out.merge
  If set to true the result will be merged with an existing coverage session file. Default: Merge with existing file.
• emma.filter
  Comma separated list of filters for class names that should be considered for code coverage analysis. The usual wildcards * and ? are possible, a optional + or - prefix indicates inclusion or exclusion. See Emma documentation for details. Default: All classes in the selected bundles.

Analyzing the Coverage Result

The code coverage runtime create a single EMMA coverage session file containing Meta data about all the classes of the bundles under test and the actual coverage information. This file can be imported into EclEmma and analyzed within Eclipse. Alternatively a HTML report can be created using EMMA's Ant task.

In both cases several coverage session files from different launches can be merged into a single report.

Acknowledgment

The EclEmma Equinox Runtime has been contributed and is maintained by Mikkel T Andersen. Any questions and comments about the project are welcome in our forums.