From 605aa115fda67f2867b3eba5345532c7b6302fed Mon Sep 17 00:00:00 2001 From: Vincent Massol <vmassol@apache.org> Date: Fri, 6 Oct 2006 14:46:59 +0000 Subject: [PATCH] [maven-scm] copy for tag maven-clover-plugin-2.3 git-svn-id: https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3@453619 13f79535-47bb-0310-9956-ffa450edef68 --- pom.xml | 12 +- src/it/contexts/goals.txt | 2 +- src/it/contexts/pom.xml | 23 +- .../clover/samples/contexts/Simple.java | 14 +- .../src/test/verifier/verifications.xml | 9 + src/it/multiproject/goals.txt | 1 + src/it/simple/goals.txt | 1 + src/site/apt/examples/contexts.apt | 35 + src/site/apt/examples/multiproject.apt | 41 ++ src/site/apt/examples/simple.apt | 35 + src/site/apt/index.apt | 55 +- src/site/apt/usage.apt | 613 ++++++++++++------ src/site/fml/faq.fml | 38 ++ src/site/site.xml | 6 + 14 files changed, 660 insertions(+), 225 deletions(-) create mode 100644 src/it/contexts/src/test/verifier/verifications.xml create mode 100644 src/it/multiproject/goals.txt create mode 100644 src/it/simple/goals.txt create mode 100644 src/site/apt/examples/contexts.apt create mode 100644 src/site/apt/examples/multiproject.apt create mode 100644 src/site/apt/examples/simple.apt create mode 100644 src/site/fml/faq.fml diff --git a/pom.xml b/pom.xml index d377d36cc7..c8f42379a3 100644 --- a/pom.xml +++ b/pom.xml @@ -2,7 +2,7 @@ <parent> <artifactId>maven-plugins</artifactId> <groupId>org.apache.maven.plugins</groupId> - <version>2-SNAPSHOT</version> + <version>3</version> </parent> <prerequisites> <maven>2.0.1</maven> @@ -11,7 +11,7 @@ <artifactId>maven-clover-plugin</artifactId> <packaging>maven-plugin</packaging> <name>Maven Clover Plugin</name> - <version>2.3-SNAPSHOT</version> + <version>2.3</version> <description>Maven plugin for Clover</description> <issueManagement> <system>jira</system> @@ -173,6 +173,8 @@ <projectsDirectory>src/it</projectsDirectory> <pomIncludes> <pomInclude>**/contexts/pom.xml</pomInclude> + <pomInclude>**/simple/pom.xml</pomInclude> + <pomInclude>**/multiproject/pom.xml</pomInclude> </pomIncludes> <postBuildHookScript>verify.bsh</postBuildHookScript> </configuration> @@ -190,4 +192,10 @@ </build> </profile> </profiles> + + <scm> + <connection>scm:svn:https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3</connection> + <developerConnection>scm:svn:https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3</developerConnection> + <url>https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3</url> + </scm> </project> diff --git a/src/it/contexts/goals.txt b/src/it/contexts/goals.txt index 9cb8855c79..8e5f26baf0 100644 --- a/src/it/contexts/goals.txt +++ b/src/it/contexts/goals.txt @@ -1 +1 @@ -clean install +clean install site verifier:verify diff --git a/src/it/contexts/pom.xml b/src/it/contexts/pom.xml index 8b3c9a276f..6ae84b5cd1 100644 --- a/src/it/contexts/pom.xml +++ b/src/it/contexts/pom.xml @@ -14,18 +14,28 @@ <scope>test</scope> </dependency> </dependencies> - <build> + <reporting> + <excludeDefaults>true</excludeDefaults> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> - <!-- Verify that context filters work --> - <contextFilters>static</contextFilters> - - <targetPercentage>80%</targetPercentage> - + <contextFilters>try</contextFilters> + </configuration> + </plugin> + </plugins> + </reporting> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-clover-plugin</artifactId> + <configuration> + <!-- Without the block filter the TPC is 50% and with it it's 57,1%. Thus we check for a TPC above of + 55% to verify the filter has been applied correctly --> + <targetPercentage>55%</targetPercentage> </configuration> <executions> <execution> @@ -34,7 +44,6 @@ <goals> <goal>instrument</goal> <goal>check</goal> - <goal>log</goal> </goals> </execution> </executions> diff --git a/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java b/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java index e7db72e822..19a15bec32 100644 --- a/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java +++ b/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java @@ -17,18 +17,20 @@ package org.apache.maven.plugin.clover.samples.contexts; public class Simple { - static - { - System.getProperties(); - } - public void someMethod1() { } public void someMethodToReduceStatementCoverage() { - System.getProperties(); + try + { + System.getProperties(); + } + finally + { + // We use a try/finally so that we can use a block context of + } } public void someMethod2(int i) diff --git a/src/it/contexts/src/test/verifier/verifications.xml b/src/it/contexts/src/test/verifier/verifications.xml new file mode 100644 index 0000000000..5e642cd503 --- /dev/null +++ b/src/it/contexts/src/test/verifier/verifications.xml @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<verifications> + <files> + <file> + <location>target/site/clover/pkgs-summary.html</location> + <contains>57.1%</contains> + </file> + </files> +</verifications> diff --git a/src/it/multiproject/goals.txt b/src/it/multiproject/goals.txt new file mode 100644 index 0000000000..d32445c40a --- /dev/null +++ b/src/it/multiproject/goals.txt @@ -0,0 +1 @@ +clean install site diff --git a/src/it/simple/goals.txt b/src/it/simple/goals.txt new file mode 100644 index 0000000000..d32445c40a --- /dev/null +++ b/src/it/simple/goals.txt @@ -0,0 +1 @@ +clean install site diff --git a/src/site/apt/examples/contexts.apt b/src/site/apt/examples/contexts.apt new file mode 100644 index 0000000000..a6bbc7fb60 --- /dev/null +++ b/src/site/apt/examples/contexts.apt @@ -0,0 +1,35 @@ + ------ + Contexts Example + ------ + Vincent Massol + <vmassol@apache.org> + ------ + October 6th, 2006 + + ~~ Copyright 2006 The Apache Software Foundation. + ~~ + ~~ Licensed under the Apache License, Version 2.0 (the "License"); + ~~ you may not use this file except in compliance with the License. + ~~ You may obtain a copy of the License at + ~~ + ~~ http://www.apache.org/licenses/LICENSE-2.0 + ~~ + ~~ Unless required by applicable law or agreed to in writing, software + ~~ distributed under the License is distributed on an "AS IS" BASIS, + ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~~ See the License for the specific language governing permissions and + ~~ limitations under the License. + + ~~ NOTE: For help with the syntax of this file, see: + ~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +{Contexts Example} + + This example demonstrates how to configure {{{http://cenqua.com/clover/doc/adv/contexts.html}Clover filter contexts}} + using the Clover plugin. + +* {Sources} + + Sources are available {{{http://svn.apache.org/viewvc/maven/plugins/trunk/maven-clover-plugin/src/it/contexts/}here}}. + + To execute the project run either <<<mvn install>>> to verify the TPC or <<<mvn site>>> to generate the Clover report. diff --git a/src/site/apt/examples/multiproject.apt b/src/site/apt/examples/multiproject.apt new file mode 100644 index 0000000000..b244cca292 --- /dev/null +++ b/src/site/apt/examples/multiproject.apt @@ -0,0 +1,41 @@ + ------ + Multiproject Example + ------ + Vincent Massol + <vmassol@apache.org> + ------ + October 6th, 2006 + + ~~ Copyright 2006 The Apache Software Foundation. + ~~ + ~~ Licensed under the Apache License, Version 2.0 (the "License"); + ~~ you may not use this file except in compliance with the License. + ~~ You may obtain a copy of the License at + ~~ + ~~ http://www.apache.org/licenses/LICENSE-2.0 + ~~ + ~~ Unless required by applicable law or agreed to in writing, software + ~~ distributed under the License is distributed on an "AS IS" BASIS, + ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~~ See the License for the specific language governing permissions and + ~~ limitations under the License. + + ~~ NOTE: For help with the syntax of this file, see: + ~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +{Multiproject Example} + + This example demonstrates how to use the Clover plugin in a multiproject scenario (i.e. a master Maven project with + several children modules. It also demonstrates how to perform Clover report aggregation and how functional tests + can be accounted for in the Clove report. + +* {Sources} + + Sources are available {{{http://svn.apache.org/viewvc/maven/plugins/trunk/maven-clover-plugin/src/it/multiproject/}here}}. + + To execute the project run <<<mvn install>>> to generate the Clover report. + + Note: Because of a {{{http://jira.codehaus.org/browse/MCLOVER-34}bug in Maven2}} you'll need to run + <<<mvn install>>> twice at the top level if you want to generate an aggregated report. This is because it currently + works only if the Clover databases int he children exist prior to the top level project running the Clover report + generation. diff --git a/src/site/apt/examples/simple.apt b/src/site/apt/examples/simple.apt new file mode 100644 index 0000000000..1d339c81eb --- /dev/null +++ b/src/site/apt/examples/simple.apt @@ -0,0 +1,35 @@ + ------ + Simple Example + ------ + Vincent Massol + <vmassol@apache.org> + ------ + October 6th, 2006 + + ~~ Copyright 2006 The Apache Software Foundation. + ~~ + ~~ Licensed under the Apache License, Version 2.0 (the "License"); + ~~ you may not use this file except in compliance with the License. + ~~ You may obtain a copy of the License at + ~~ + ~~ http://www.apache.org/licenses/LICENSE-2.0 + ~~ + ~~ Unless required by applicable law or agreed to in writing, software + ~~ distributed under the License is distributed on an "AS IS" BASIS, + ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~~ See the License for the specific language governing permissions and + ~~ limitations under the License. + + ~~ NOTE: For help with the syntax of this file, see: + ~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +{Simple Example} + + This example demonstrates how to use the Clover plugin both for report generation and for Test Percentage + Clover (TPC) verification, on a single Maven project. + +* {Sources} + + Sources are available {{{http://svn.apache.org/viewvc/maven/plugins/trunk/maven-clover-plugin/src/it/simple/}here}}. + + To execute the project run either <<<mvn install>>> to verify the TPC or <<<mvn site>>> to generate the Clover report. diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 9de793fe54..ac171988ed 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -4,8 +4,8 @@ Vincent Massol <vmassol@apache.org> ------ - April 8th, 2006 - + October 6th, 2006 + ~~ Copyright 2006 The Apache Software Foundation. ~~ ~~ Licensed under the Apache License, Version 2.0 (the "License"); @@ -23,7 +23,7 @@ ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/guides/mini/guide-apt-format.html -Introduction +Maven Clover Plugin The Clover plugin is the place where build actions related to {{{http://www.cenqua.com/clover/}Clover}} are found in Maven. @@ -32,9 +32,7 @@ Introduction If your project is a commercial project you will need to get a license for the Clover jar before using this plugin. Please note that a 30 days license is included in this plugin. - The full description of goals is available {{{index.html}here}}. - -Features +* Features The Clover plugin currently supports the following features: @@ -59,9 +57,48 @@ Features test compiled tests classes. It creates a parallel directory in <<<target/clover>>> in order not to tamper with your main files. - See the {{{howto.html}Howto}} section to learn how to use these features. - -Examples +* Usage + + Instructions on how to use Maven Clover Plugin can be found {{{usage.html}here}}. + +* Goals Overview + + The <<<maven-clover-plugin>>> has seven goals, but only six are called directly by the user. The full description + of goals, generated automatically from the source code, is available {{{plugin-info.html}here}}. + + * {{{aggregate-mojo.html}clover:aggregate}} - Aggregate children module Clover databases if there are any. This mojo + should not exist. It's only there because the site plugin doesn't handle @aggregators properly at the moment... + + * {{{check-mojo.html}clover:check}} - Verify Test Percentage Coverage (TPC) from an existing Clover database and fail + the build if it is below the defined threshold. The check is done on main Clover databases and also on merged Clover + databases when they exist. + + * {{{instrumentInternal-mojo.html}clover:instrumentInternal}} - Instrument source roots. + + <<Note: Do not call this MOJO directly. It is meant to be called in a custom forked lifecycle by the other Clover + plugin MOJOs.>> + + * {{{instrument-mojo.html}clover:instrument}} - Instrument all sources using Clover and forks a custom lifecycle to + execute project's tests on the instrumented code so that a Clover database is created. + + Note: We're forking a lifecycle because we don't want the Clover instrumentation to affect the main lifecycle build. + This will prevent instrumented sources to be put in production by error. Thus running mvn install on a project where + this instrument goal has been specified will run the build twice: once for building the project as usual and another + time for instrumenting the sources with Clover and generating the Clover database. + + * {{{log-mojo.html}clover:log}} - Provides information on the current Clover database. + + * {{{clover-mojo.html}clover:clover}} - Generate a Clover report from existing Clover databases. The generated report is + an external report generated by Clover itself. If the project generating the report is a top level project and if + the aggregate configuration element is set to true then an aggregated report will also be created. + + Note: This report mojo should be an @aggregator and the clover:aggregate mojo shouldn't exist. This is a limitation + of the site plugin which doesn't support @aggregator reports... + + * {{{save-history-mojo.html}clover:save-history}} - Save a + {{{http://cenqua.com/clover/doc/tutorial/part2.html}Clover history point}}. + +* Examples Check the {{{http://svn.apache.org/viewcvs.cgi/maven/plugins/trunk/maven-clover-plugin/src/it/}plugin test suite}} for example of how to use this plugin. diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt index bf10316fda..5628010ee1 100644 --- a/src/site/apt/usage.apt +++ b/src/site/apt/usage.apt @@ -1,104 +1,220 @@ ------ - Maven 2 Clover Plugin: using + Usage ------ Vincent Massol <vmassol@apache.org> + Franz Allan Valencia see + <franz.see@gmail.com> + ------ + October 11th, 2006 ------ - September 9th, 2006 -User Guide + ~~ Copyright 2006 The Apache Software Foundation. + ~~ + ~~ Licensed under the Apache License, Version 2.0 (the "License"); + ~~ you may not use this file except in compliance with the License. + ~~ You may obtain a copy of the License at + ~~ + ~~ http://www.apache.org/licenses/LICENSE-2.0 + ~~ + ~~ Unless required by applicable law or agreed to in writing, software + ~~ distributed under the License is distributed on an "AS IS" BASIS, + ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~~ See the License for the specific language governing permissions and + ~~ limitations under the License. - * {{{usage.html#Generating a Clover report when generating the site}Generating a Clover report when generating the site}} + ~~ NOTE: For help with the syntax of this file, see: + ~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +{Usage} - * {{{usage.html#Generating a Clover report without modifying your POM}Generating a Clover report without modifying your POM}} +* Table Of Contents - * {{{usage.html#Generating HTML, XML and PDF reports}Generating HTML, XML and PDF reports}} + * {{{usage.html#Getting Started}Getting Started}} - * {{{usage.html#Generating historical reports}Generating historical reports}} + * {{{usage.html#Controlling files to instrument}Controlling files to instrument}} * {{{usage.html#Checking test coverage}Checking test coverage}} - * {{{usage.html#Using Clover with JDK 1.4 and JDK 1.5 keywords}Using Clover with JDK 1.4 and JDK 1.5 keywords}} + * {{{usage.html#Using block contexts}Using block contexts}} + + * {{{usage.html#Using Clover with different JDK versions}Using Clover with different JDK versions}} - * {{{usage.html#Specifying a Clover flush policy}Specifying a Clover flush policy}} + * {{{usage.html#Specifying a Clover flush policy}Specifying a Clover flush policy}} - * {{{usage.html#Specifying a custom license file}Specifying a custom license file}} + * {{{usage.html#Generating a Clover report}Generating a Clover report}} + + * {{{usage.html#Specifying report formats}Specifying report formats}} - * {{{usage.html#Aggregating Clover reports}Aggregating Clover reports}} + * {{{usage.html#Generating historical reports}Generating historical reports}} - * {{{usage.html#Controlling files to instrument}Controlling files to instrument}} + * {{{usage.html#Aggregating Clover Reports}Aggregating Clover Reports}} * {{{usage.html#Getting information on an existing Clover database}Getting information on an existing Clover database}} + * {{{usage.html#Specifying a custom license file}Specifying a custom license file}} + [] + +* {Getting Started} -* {Generating a Clover report when generating the site} + The first thing to do is to create a {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}. To do + this, you must either do: - Add the Clover report in your <<<pom.xml>>> under the <<<reporting>>> section: ++------+ + mvn clover:instrument ++------+ -+-------- -<project> - [...] - <reporting> + or + ++------+ + <build> <plugins> - [...] <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> [...] </configuration> + <executions> + <execution> + [...] + <goals> + <goal>instrument</goal> + </goals> + [...] + </execution> + </executions> </plugin> </plugins> - </reporting> + </build> ++------+ + + This instruments all sources using Clover so that a + {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} is created (or if it already exists, the plugin + will simply use it and add data on top of the existing one). When you execute your tests + the instrumented code will start generating logs into the Clover database. These logs can then be used for + Test Coverage Percentage checks, for report generation or for logging. + + Note that the Clover plugin takes great care not to mix the instrumented code nor any artifact generated from it + with main production sources and artifacts. This is the reason why you may see your tests executed twice: once + for the production sources and once for the Clover-instrumented sources. + + <Back to {{{usage.html}top}}.> + +** {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> [...] +--------- - 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: + <Back to {{{usage.html}top}}.> + +* {Checking test coverage} -+-------- -<project> - [...] + 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: + ++------+ + mvn clover:check -DtargetPercentage=50% ++------+ + + or + ++------+ <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> - [...] + <targetPercentage>50%</targetPercentage> </configuration> <executions> <execution> - <phase>pre-site</phase> + <phase>verify</phase> <goals> - <goal>instrument</goal> + <goal>check</goal> </goals> </execution> </executions> </plugin> </plugins> </build> -[...] -+--------- ++------+ - Then, to generate the report as part of the site simply type <<<mvn site:site>>>. + In this example you've told Maven to run <<<clover:check>>> whenever the + <<<verify>>> phase is reached (this will be the case if you run + <<<mvn install>>> for example). -* {Generating a Clover report without modifying your POM} + Furthermore, you specified that the <<<targetPercentage>>> is <<<50%>>>, + meaning the test must result to at least <<<50%>>> test coverage percentage to + pass. If the <<<targetPercentage>>> was not specified, the default value of + <<<70%>>> will be used. + + However, as previously mentioned, Clover needs an existing + {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}. Thus, a call + to <<<clover:instrument>>> may be neccessary: + ++------+ + mvn clover:instrument clover:check -DtargetPercentage=50% ++------+ - 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. + or + ++------+ + <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> ++------+ -* {Generating HTML, XML and PDF reports} + Note: The <<<clover:check>>> goal will also check the test percentage coverage + for merged Clover databases if any is found (see the + {{{usage.html#Aggregating Clover Reports}Aggregating Clover Reports}} section for more on that). + + <Back to {{{usage.html}top}}.> + +** {Using block contexts} - 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: + Clover allows specifying {{{http://cenqua.com/clover/doc/adv/contexts.html}block contexts}} + (i.e. elements to be excluded from the Test Percentage Coverage). To configure a block context use + the <<<contextFilters>>> element. For example to exclude <<<try>>> and <<<static>>> block contexts, you would + write: +-------- [...] @@ -106,244 +222,300 @@ User Guide <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> - <generatePdf>true</generatePdf> - <generateXml>true</generateXml> + <contextFilters>try,static</contextFilters> </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> -[...] -+--------- + <Back to {{{usage.html}top}}.> - 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: +** {Using Clover with different JDK versions} + 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: + +-------- -<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> + <jdk>1.4</jdk> [...] +--------- -* {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: + <Back to {{{usage.html}top}}.> + +** {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: + +-------- -<project> - [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> - <generateHistorical>true</generateHistorical> - [...] - </configuration> -[...] - </plugin> - </plugins> - </build> + <flushPolicy>threaded</flushPolicy> + <flushInterval>5000</flushInterval> [...] +--------- - 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: + <Back to {{{usage.html}top}}.> + +* {Generating a Clover report} + + To generate a Clover report, simply execute the following command: + ++------+ +mvn clover:clover ++------+ + Also, you may want to generate a Clover Report everytime you generate site for + your maven project (i.e. <<<mvn site>>>): + +-------- <project> - [...] - <build> + [...] + <reporting> <plugins> + [...] <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> - <generateHistorical>true</generateHistorical> - <historyDir>${myHistoryDir}</historyDir> [...] </configuration> -[...] </plugin> </plugins> - </build> + </reporting> [...] +--------- + + But just like the <<<clover:check>>> goal, the <<<clover:clover>>> goal + also needs an existing + {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}. Thus, if + if it still does not exist, a call to <<<clover:instrument>>> must first be + made: + ++------+ +mvn clover:instrument clover:clover ++------+ - 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: + or +-------- +<project> + [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> - <targetPercentage>50%</targetPercentage> + [...] </configuration> <executions> <execution> - <phase>verify</phase> + <phase>pre-site</phase> <goals> <goal>instrument</goal> - <goal>check</goal> </goals> </execution> </executions> </plugin> </plugins> </build> + [...] + <reporting> + <plugins> + [...] + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-clover-plugin</artifactId> + <configuration> + [...] + </configuration> + </plugin> + </plugins> + </reporting> +[...] +--------- + + Note that in the above example that <<<clover:instrument>>> was bound to the + <<<pre-site>>> phase. This is done to ensure that a + {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} is + generated before the report executes. - 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. + <Back to {{{usage.html}top}}.> + +** {Specifying report formats} + + 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: - If you don't specify a target percentage the default value used is 70%. ++-------- +[...] + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-clover-plugin</artifactId> + <configuration> + <generatePdf>true</generatePdf> + <generateXml>true</generateXml> + </configuration> + </plugin> +[...] ++--------- - You can also invoke <<<mvn clover:check>>> directly on the command line. + 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: - Note: The <<<clover:check>>> goal will also check the test percentage coverage for merged databases if any is found. ++-------- +[...] + <menu name="Other Reports"> + <item name="Clover PDF" href="clover/clover.pdf"/> + <item name="Clover XML" href="clover/clover.xml"/> + </menu> +[...] ++--------- -* {Using Clover with JDK 1.4 and JDK 1.5 keywords} + 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: - 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: - +-------- +<project> + [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-clover-plugin</artifactId> <configuration> - <jdk>1.4</jdk> + <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> [...] +--------- -* {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: + <Back to {{{usage.html}top}}.> +** {Generating historical reports} + + Generating historical reports 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> - <flushPolicy>threaded</flushPolicy> - <flushInterval>5000</flushInterval> + <generateHistorical>true</generateHistorical> + [...] + </configuration> + [...] + </plugin> + </plugins> + </build> [...] +--------- -* {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: + Now this will generate a + {{{http://cenqua.com/clover/doc/tutorial/part2.html}Clover 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> - <licenseLocation>${basedir}/src/test/clover/myclover.license</licenseLocation> + <generateHistorical>true</generateHistorical> + <historyDir>${myHistoryDir}</historyDir> + [...] </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}}. + Where <<<myHistoryDir>>> could be a Maven property that you define in a + profile. -* {Aggregating Clover reports} + <Back to {{{usage.html}top}}.> + +** {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.>> + <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 the first + time your run> <<<mvn site>>> <it won't find the generated children databases as they'll be produced after it + executes. 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: + You can aggregate children modules Clover databases into a single merged database + by running the <<<clover:aggregate>>> goal. This For example if you have the + following project layout: +-------- -myproject/ - |_ project1/ - |_ pom.xml - |_ project2/ - |_ pom.xml - |_ pom.xml +myproject + |-- project1 + | `-- pom.xml + |-- project2 + | `-- pom.xml + `-- pom.xml +--------- Then, ensure that your <<<myproject/pom.xml>>> contains the following: @@ -381,35 +553,31 @@ myproject/ [...] +--------- - 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: + When you run <<<mvn site>>> in <<<myproject/>>>, the plugin will instrument + your sources, run your tests, aggregate the different + {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} generated + for each build module (i.e. <<<project1>>> and <<<project2>>>) and generate an + aggregated Clover report in the site for the <<<myproject>>> project. + + Alternatively, you can execute + ++------+ +mvn clover:aggregate clover:clover ++------+ -+-------- - <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> -[...] -+--------- + or if there is no existing + {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}: + ++------+ +mvn clover:instrument clover:aggregate clover:clover ++------+ + Note that you can control the location of the merged + {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} by using + the <<<cloverMergeDatabase>>> configuration property. + + <Back to {{{usage.html}top}}.> + * {Getting information on an existing Clover database} You can dump information about your project's Clover database (after it has been populated) by running @@ -429,3 +597,48 @@ Coverage Overview - Conditionals: 1/2 (50%) TOTAL: 62,5% +--------- + + <Back to {{{usage.html}top}}.> + +* {Specifying a custom license file} + + The Clover plugin provides a default evaulation license. However if you continue to use Clover you'll need your + own license (they are free for open source/non-commercial project but you'll need to contact Cenqua to get a + license). 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 feature, refer to the + {{{http://maven.apache.org/plugins/maven-checkstyle-plugin/tips.html}Checkstlye plugin documentation}}. + + <Back to {{{usage.html}top}}.> diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml new file mode 100644 index 0000000000..7413e5fe39 --- /dev/null +++ b/src/site/fml/faq.fml @@ -0,0 +1,38 @@ +<?xml version="1.0"?> + +<!-- + ~ Copyright 2006 The Apache Software Foundation. + ~ + ~ Licensed under the Apache License, Version 2.0 (the "License"); + ~ you may not use this file except in compliance with the License. + ~ You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. + --> + +<faqs id="FAQ" title="Frequently Asked Questions"> + <part id="General"> + <faq id="Does Clover work on the Source code or the bytecode?"> + <question>Does Clover work on the Source code or the bytecode?</question> + <answer> + <p>Clover works on the source code. It is not possible for Clover to work + on bytecodes.</p> + </answer> + </faq> + <faq id="Why are my tests executed twice?"> + <question>Why are my tests executed twice?</question> + <answer> + <p>The Clover plugin takes great care not to mix the instrumented code nor any artifact generated from it + with main production sources and artifacts. This is the reason why you may see your tests executed twice: once + for the production sources and once for the Clover-instrumented sources. + </p> + </answer> + </faq> + </part> +</faqs> diff --git a/src/site/site.xml b/src/site/site.xml index c507e9b909..e0234071c2 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -37,6 +37,12 @@ <item name="Usage" href="usage.html"/> <item name="FAQ" href="faq.html"/> </menu> + + <menu name="Examples"> + <item name="Simple" href="/examples/simple.html"/> + <item name="Filter Contexts" href="/examples/contexts.html"/> + <item name="Multiproject" href="/examples/multiproject.html"/> + </menu> <!-- To be uncommented once it's up to date again --> <!--menu name="Architecture"> -- GitLab