------
 Maven 2 Clover Plugin: using
 ------
 Vincent Massol
 <vmassol@apache.org>
 ------
 April 1st, 2006

Generating a Clover report when generating the site

  Add the Clover report in your <<<pom.xml>>> under the <<<reporting>>> section:

+--------
<project>
  [...]
  <reporting>
    <plugins>
      [...]
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          [...]
        </configuration>
      </plugin>
    </plugins>
  </reporting>
[...]
+---------

  The <<<maven-clover-plugin>>> report will only generate a report out of an existing Clover database
  so if you don't have a Clover database available you'll need to configure your build to generate one.
  This is achieved by binding the <<<clover:instrument>>> goal to the <<<pre-site>>> phase so that it
  executes before the report executes. For example:

+--------
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          [...]
        </configuration>
        <executions>
          <execution>
            <phase>pre-site</phase>
            <goals>
              <goal>instrument</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
[...]
+---------

  Then, to generate the report as part of the site simply type <<<mvn site:site>>>.
  
Generating a Clover report without modifying your POM

  If you simply want to generate a Clover report on the fly without modifying your POM, simply
  type <<<mvn clover:instrument clover:clover>>>. Alternatively if you want to aggregate children
  module reports into a master Clover report, run <<<mvn clover:instrument clover:aggregate clover:clover>>>
  instead.

Generating HTML, XML and PDF reports

  By default the Clover plugin will generate a HTML report. If you want to generate a PDF or XML report, or
  if you simply do not want to generate the HTML report use the <<<generateHtml>>>, <<<generatePdf>>> and
  <<<generateXml>>> configuration elements. By default the <<<generateHtml>>> element is set to true.
  For example if you wish to generate the PDF and XML reports you would use:

+--------
[...]
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-clover-plugin</artifactId>
    <configuration>
      <generatePdf>true</generatePdf>
      <generateXml>true</generateXml>
    </configuration>
  </plugin>
[...]
+---------

  Note that only the HTML report gets a link in the "Project Reports" section in generated menu on the site. If
  you want to link the PDF or XML reports you'll need to do that by modifying your <<<site.xml>>>. For example:

+--------
[...]
  <menu name="Other Reports">
    <item name="Clover PDF" href="clover/clover.pdf"/>
    <item name="Clover XML" href="clover/clover.xml"/>
  </menu>
[...]
+---------

  If you do not want to generate the HTML report then you should not configure the Clover plugin in the
  <<<reporting>>> section as this section is for plugins which generate HTML reports. In that case, simply
  bind the <<<clover:clover>>> goal to the <<<site>>> phase in the <<<build>>> section. For example:

+--------
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          <generateHtml>false</generateHtml>
          <generatePdf>true</generatePdf>
          <generateXml>true</generateXml>
        </configuration>
        <executions>
          <execution>
            <phase>site</phase>
            <goals>
              <goal>instrument</goal>
              <goal>clover</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
[...]
+---------

Generating historical reports

  This is done in the same manner as you generate a standard Clover report but in addition you need to set the
  <<<generateHistorical>>> configuration property to true (it's false by default). For example:

+--------
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          <generateHistorical>true</generateHistorical>
          [...]
        </configuration>
[...]
      </plugin>
    </plugins>
  </build>
[...]
+---------

  Now this will generate a historical report only if you have saved Clover historical savepoints. In order to save a
  Clover savepoint, run the <<<clover:save-history>>> goal. It's up to you to decide when you want to call this goal.
  For example you could call it every time a build is executing on your CI server, or you could call it at every
  project release, etc. The location of the history directory for saving the savepoints is controlled by the
  <<<historyDir>>> configuration property, which points to <<<${project.build.directory}/clover/history>>> by default.
  It is recommended to use another location that will not get erased by a <<<mvn clean>>>. For example:

+--------
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          <generateHistorical>true</generateHistorical>
          <historyDir>${myHistoryDir}</historyDir>
          [...]
        </configuration>
[...]
      </plugin>
    </plugins>
  </build>
[...]
+---------

  Where <<<myHistoryDir>>> could be a Maven property that you define in a profile.

Checking test coverage

  In order to check for a test coverage percentage and fail the build in case of non-compliance,
  you'll need to configure the Clover plugin to tell it what test coverage threshold you wish to use:
  
+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          <targetPercentage>50%</targetPercentage>
        </configuration>
        <executions>
          <execution>
            <phase>verify</phase>
            <goals>
              <goal>instrument</goal>
              <goal>check</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
+---------

  In this example you've told Maven to run <<<clover:instrument>>> and <<<clover:check>>> whenever the <<<verify>>>
  phase is reached (this will be the case if you run <<<mvn install>>> for example). You need to call
  <<<clover:instrument>>> before the check because <<<clover:check>>> requires an existing Clover datababase to
  perform the verification.

  If you don't specify a target percentage the default value used is 70%.

  You can also invoke <<<mvn clover:check>>> directly on the command line.

  Note: The <<<clover:check>>> goal will also check the test percentage coverage for merged databases if any is found.

Using Clover with JDK 1.4 and JDK 1.5 keywords

  If your code is using JDK 1.4 or JDK 1.5 specific keywords, you'll need to configure the Clover
  plugin. For example for JDK 1.4:
  
+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          <jdk>1.4</jdk>
[...]
+---------

Specifying a Clover flush policy

  If you want to specify the Clover 
  {{{http://cenqua.com/clover/doc/adv/flushpolicies.html}flush policy}} that the plugin should use,
  then specify it in the plugin's configuration. Valid policies are <<<threaded>>>, <<<directed>>>
  and <<<interval>>>.
  
  For example to use a <<<threaded>>> policy with a flush interval of <<<5000>>> ms you would write:
  
+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          <flushPolicy>threaded</flushPolicy>
          <flushInterval>5000</flushInterval>
[...]
+---------

Specifying a custom license file

  The Clover plugin provides a default evaulation license. However if your project is a commercial project
  you need to purchase your own license to use Clover. To use your license specify it using a
  <<<licenseLocation>>> configuration element. For example if you wanted to automatically execute the
  <<<check>>> goal when you type <<<mvn install>>> and if you wanted to use your license located in
  <<<${basedir}/src/test/clover/myclover.license>>> you would use:

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <configuration>
          <licenseLocation>${basedir}/src/test/clover/myclover.license</licenseLocation>
        </configuration>
        <executions>
          <execution>
            <configuration>
              <targetPercentage>50%</targetPercentage>
            </configuration>
            <phase>verify</phase>
            <goals>
              <goal>instrument</goal>
              <goal>check</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
+---------

  Important note: The <<<licenseLocation>>> element needs to be defined in the global <<<configuration>>> element
  and not in the <<<configuration>>> element under the <<<execution>>> tag.

  Instead of specifying a file, you can also specify either a <<URL>> or a <<relative path inside a JAR>> (to learn
  how to use this last feature, refer to the
  {{{http://maven.apache.org/plugins/maven-checkstyle-plugin/tips.html}Checkstlye plugin documentation}}.

Aggregating Clover reports

  <<Note: There's currently a {{{http://jira.codehaus.org/browse/MCLOVER-34}bug in Maven2}} which results in the clover
  aggregation not working properly. More specifically the aggregate goal requires an existing Clover database and
  thus the first time your run "mvn site" the aggregated report won't be generated. It'll work the second time
  though. Just ensure that you run the aggregate goal after you've generated the children Clover databases.>>

  You can aggregate children modules Clover reports into a single master report by running the <<<clover:aggregate>>>
  goal. For example if you have the following project layout:

+--------
myproject/
  |_ project1/
    |_ pom.xml
  |_ project2/
    |_ pom.xml
  |_ pom.xml
+---------

  Then, ensure that your <<<myproject/pom.xml>>> contains the following:

+--------
<project>
  [...]
  <reporting>
    <plugins>
      [...]
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
      </plugin>
    </plugins>
  </reporting>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-clover-plugin</artifactId>
        <executions>
          <execution>
            <phase>pre-site</phase>
            <goals>
              <goal>instrument</goal>
              <goal>aggregate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
[...]
+---------

  When you run <<<mvn site>>> in <<<myproject/>>>, the plugin will instrument your sources, run your tests,
  aggregate the different Clover databases generated for each build module (i.e. <<<project1>>> and <<<project2>>>)
  and generate a master Clover report in the site for the <<<myproject>>> project.

  Note that you can control the location of the master Clover database by using the <<<cloverMergeDatabase>>>
  configuration property.

Controlling files to instrument

  By default all Java files are included during the instrumentation. To specify inclusion and exclusion use the
  <<<includes>>> and <<<excludes>>> configuration elements as shown in this example:

+--------
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-clover-plugin</artifactId>
    <configuration>
      <includes>
        <include>**/api/**/*.java</include>
        <include>some/path/MyFile.java</include>
        [...]
      </includes>
      <excludes>
        <exclude>**/*Test/java</exclude>
        [...]
      </excludes>
[...]
+---------