Using JaCoCo merge goal to report coverage in multi-module projects

This Example github project shows how jacoco:merge goal can be used to merge all the exec files

In this example we two projects.  project1 and project2

  • project1 has 2 classes : Example1 and Example2. It also has 1 unit test to fully cover Example1
  • project2 has only unit test. The unit test fully covers Example2 from project1

As project1 is not covering Example2, jacoco will report 0% coverage for Example2

Firstly, to show that JaCoCo will show 0% coverage for Example2 class in project1 run these commands:


mvn clean verify

then run


mvn jacoco:report

if you go into folder

project1/target/site/jacoco/project1 you’ll the reports produced by jacoco

The report shows class Example1 has 100% coverage whilst Example2 (which is covered by project2) has 0% coverage

Using merge goal to get JaCoCo to report on coverage provided by other projects

For the above example, we want to show Example2 is fully covered (as coverage was provided by project2)

To get jacoco to report coverage provided by other projects. We need to merge all the jacoco.exec files we have

  • project1 jacoco exec is under project1/target/jacoco.exec
  • project2 jacoco exec is under project2/target/jacoco.exec

Merge the jacoco.exec from project 1 and project 2 to make a merged jacoco.exec The merged jacoco.exec file will show we have 100% coverage for Example2 class. We will then configure the reporting goal to use this merged exec file.

Step 1

We want to copy all the jacoco.exec file into the top level folder target folder (we may also need to create the target folder)

we need to copy all jacoco.exec we have into the top-level target folder, but so that they don’t overwrite each other, we need to give them unique names, for this we will use merge goal (or you can use copy script for this step)

Note: jacoco:merge goal requires fileSets config to be present see : merge goal documentation

We will add this to our the jacoco plugin configuration (so that we can use the merge goal)

<fileSets>
  <fileSet>
    <directory>${project.build.directory}</directory>
    <includes>
      <include>*.exec</include>
    </includes>
  </fileSet>
</fileSets>

as mentioned, the file(s) when written to the top level, we don’t want them to overwrite to each other, so we give them file name :  

${project.artifactId}.exec

E.g. on Windows if the project level folder was : c:/temp/jacoco-merge

You would run this (making sure that c:/temp/jacoco-merge/target) exists first


mvn jacoco:merge -Djacoco.destFile=c:/temp/jacoco-merge/target/${project.artifactId}.exec

End result should look like this (strictly speaking, you could use copy commands to achieve this instead)

Step 2

Now that we have all the exec files (project1.exec and project2.exec) in one folder, we need to merge these 2 files to produce merged jacoco.exec file

For this, we run this command. NOTE: Since all the files are all in the top level folder, we only need to execute merge goal at the top level folder only so we use flag -N to not recurse this merge goal in the child projects.


mvn -N jacoco:merge

Result of above

Step 3

Now that we have the merged exec file produced in above step. What we want to do is run the report goal (to generate the html reports) but instead the of using default jacoco.dataFile value (${project.build.directory}/jacoco.exec) we will configure jacoco.dataFile to instead use the merged jacoco exe file


mvn jacoco:report -Djacoco.dataFile=C:\temp\jacoco-merge\target\jacoco.exec

Now if we look again in project1/target/site/jacoco/project1 we can see it shows both Example1 and Example2 have 100% coverage

Enforcing Minimum Code Coverage

If you want to enforce minimum code coverage check, JaCoCo worked really in the projects that I’ve worked on so far.

JaCoCo works as agent (there is another option where it can do offline instrumentation). The prepare-agent goal sets up the “jacocoProperty” property to setup JaCoCo as agent on the the surefire argLine (so it will only work if sure-fire is configured to run your unit tests in forked process)

Here is basic maven project that demonstrates how to check minimum line and branch coverage of 80% is met.

Prepare Agent Goal

<plugin>
        <groupId>org.jacoco</groupId>
        <artifactId>jacoco-maven-plugin</artifactId>
        <version>0.8.2</version>
       
         <executions>

           <!--  (1)  Prepare agent runs in the init phase, it setups the jacocoProperty,  so we can insert this to the maven sure fire argLine and get to run jacoco as agent -->
          <execution>
            <id>prepare-agent</id>
            <goals>
              <goal>prepare-agent</goal>
            </goals>
            <configuration>
              <propertyName>jacocoArgLine</propertyName>
              <includes>
                <include>com.choudhury.codecoverage.*</include>
              </includes>
            </configuration>
          </execution>

SureFire Plugin Argline

We run sure fire and we add the “jacocoProperty” as part of the argLine

 <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.22.1</version>
        <configuration>
            <!-- (2)  setup the argLine and run the unit tests.   **NOTE the "jacocArgeLine" property was configured the "prepare-agent" goal of Jacoco  (see below) -->
            <argLine>${jacocoArgLine} -Xmx256m</argLine>
        </configuration>
      </plugin>

After the forked sure fire process is has completed it write the jacoco.exec file in the target file. This file is required for both the “check” and “report” JaCoCo goals.

jacoco_coverage_file

Check Goal
In verify phase, we execute the check goal of JaCoCo

          <!--  (3) the check goal by default runs in the verify phase, we want to fail the build if mimimum code coverage checks aren't met -->
          <execution>
            <id>check</id>
            <goals>
              <goal>check</goal>
            </goals>
            <configuration>
              <rules>
                <!-- All classes must have 80% line and branch coverage . Note we use 2 d.p so that we get can any check failure messages reported to 2 d.p  -->
                <rule >
                  <element>CLASS</element>
                  <limits>
                    <limit >
                      <counter>LINE</counter>
                      <value>COVEREDRATIO</value>
                      <minimum>0.80</minimum>
                    </limit>
                    <limit >
                      <counter>BRANCH</counter>
                      <value>COVEREDRATIO</value>
                      <minimum>0.80</minimum>
                    </limit>
                  </limits>
                  <excludes>
                    <exclude>com.choudhury.codecoverage.Bye</exclude>
                  </excludes>
                </rule>
              </rules>
            </configuration>
          </execution>
        </executions>

Example Project

Example maven project can be found here

With the example project, when we run “mvn clean install” we expect to fail on code coverage checks.

To confirm that Jacoco agent is correctly being appended to the Java argLine for maven SureFire plugin, temporarily put a long enough pause in the Unit Test (and whilst the Unit Test are running) launch jvisualvm to check that jacoco is correctly setup as an agent.

jacoco_run_as_agent

min_check_failed

If we update the HelloTest to test the missed branch and re-run “mvn clean install” we should see the lines “All Coverage checks have been met” to appear and the the build should pass 🙂

min_check_passed

JaCoCo Code Coverage Reports

Another nice feature of JaCoCo maven plugin is the report goal allowing you to see which lines have been covered by your tests.

Execute the report goal of the JaCoCo maven plugin

mvn jacoco:report

(Note : this reads the jacoco.exec file in your target folder, do make sure it’s present when you run this goal, otherwise you will get no reports produced).

The report goal should produce the html files under target/site/jacoco folder.

  • Green shows the covered lines
  • Yellow shows partially covered branches (you can hover over the diamond icon to get tooltip of how many branches covered)
  • Red is the missed lines.

Automated Swing Testing

For testing Swing UI, Jemmy is a really great tool. Some info about this can be found at

http://wiki.netbeans.org/Jemmy

and

http://jemmy.java.net/

and this is really useful powerpoint presentation I googled across:
Here

Another great tool is Fest-Swing , this uses Robot to generate Input Simulation.

I prefer Jemmy as it provides the option of using either Event Dispatching (events are programmatically created and dispatched onto the Event Queue) or Robot (using the Robot class to control the mouse and keyboard, generating native OS events like a real user using the UI) method for input simulation.

When you run the Tests on the Continuous build system, using Event Dispatch (the default mechanism for Jemmy) , it means you don’t need to have the process running inside a logged in windows desktop (it will still work even when it’s run as windows service account). The other advantage of Event Disptaching mechanism is that you when run the automated tests on your own machine you do not have to worry about your mouse and keyboard being taken control by the automated tests.