Added docs for route-coverage maven plugin
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/6e4e721d Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/6e4e721d Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/6e4e721d Branch: refs/heads/master Commit: 6e4e721df28da5dbfcd29c2610ded45e4ecd5fd0 Parents: f015f7b Author: Claus Ibsen <davscl...@apache.org> Authored: Thu Oct 12 19:49:51 2017 +0200 Committer: Claus Ibsen <davscl...@apache.org> Committed: Thu Oct 12 19:49:51 2017 +0200 ---------------------------------------------------------------------- .../src/main/docs/camel-maven-plugin.adoc | 257 +++++++++++++------ 1 file changed, 178 insertions(+), 79 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/6e4e721d/tooling/maven/camel-maven-plugin/src/main/docs/camel-maven-plugin.adoc ---------------------------------------------------------------------- diff --git a/tooling/maven/camel-maven-plugin/src/main/docs/camel-maven-plugin.adoc b/tooling/maven/camel-maven-plugin/src/main/docs/camel-maven-plugin.adoc index 8da3da6..c384b49 100644 --- a/tooling/maven/camel-maven-plugin/src/main/docs/camel-maven-plugin.adoc +++ b/tooling/maven/camel-maven-plugin/src/main/docs/camel-maven-plugin.adoc @@ -4,14 +4,17 @@ The Camel Maven Plugin supports the following goals - camel:run - To run your Camel application - camel:validate - To validate your source code for invalid Camel endpoint uris + - camel:route-coverage - To report the coverage of your Camel routes after unit testing == camel:run The `camel:run` goal of the Camel Maven Plugin is used to run your Camel Spring configurations in a forked JVM from Maven. A good example application to get you started is the Spring Example. - cd examples/camel-example-spring - mvn camel:run +---- +cd examples/camel-example-spring +mvn camel:run +---- This makes it very easy to spin up and test your routing rules without having to write a main(...) method; it also lets you create multiple jars to host different sets of routing rules and easily test them independently. @@ -28,13 +31,16 @@ The `camel:run` plugin also supports running a Blueprint application, and by def You would need to configure the camel:run plugin to use blueprint, by setting useBlueprint to true as shown below - <plugin> - <groupId>org.apache.camel</groupId> - <artifactId>camel-maven-plugin</artifactId> - <configuration> - <useBlueprint>true</useBlueprint> - </configuration> - </plugin> +[source,xml] +---- +<plugin> + <groupId>org.apache.camel</groupId> + <artifactId>camel-maven-plugin</artifactId> + <configuration> + <useBlueprint>true</useBlueprint> + </configuration> +</plugin> +---- This allows you to boot up any Blueprint services you wish - whether they are Camel-related, or any other Blueprint. @@ -47,17 +53,20 @@ We use the Felix Connector project as the blueprint container. This project is n For that you can use Apache Karaf or Apache ServiceMix. You can use the applicationContextUri configuration to specify an explicit blueprint XML file, such as: - <plugin> - <groupId>org.apache.camel</groupId> - <artifactId>camel-maven-plugin</artifactId> - <configuration> - <useBlueprint>true</useBlueprint> - <applicationContextUri>myBlueprint.xml</applicationContextUri> - <!-- ConfigAdmin options which have been added since Camel 2.12.0 --> - <configAdminPid>test</configAdminPid> - <configAdminFileName>/user/test/etc/test.cfg</configAdminFileName> - </configuration> - </plugin> +[source,xml] +---- +<plugin> + <groupId>org.apache.camel</groupId> + <artifactId>camel-maven-plugin</artifactId> + <configuration> + <useBlueprint>true</useBlueprint> + <applicationContextUri>myBlueprint.xml</applicationContextUri> + <!-- ConfigAdmin options which have been added since Camel 2.12.0 --> + <configAdminPid>test</configAdminPid> + <configAdminFileName>/user/test/etc/test.cfg</configAdminFileName> + </configuration> +</plugin> +---- The `applicationContextUri` will currently load the file from the classpath, so in the example above the `myBlueprint.xml` file must be in the root of the classpath. @@ -76,33 +85,41 @@ You should add the CDI container of your choice (e.g. Weld or OpenWebBeans) to t From the source of Camel you can run a CDI example via - cd examples/camel-example-cdi - mvn compile camel:run +---- +cd examples/camel-example-cdi +mvn compile camel:run +---- === Logging the classpath You can configure whether the classpath should be logged when `camel:run` executes. You can enable this in the configuration using: - <plugin> - <groupId>org.apache.camel</groupId> - <artifactId>camel-maven-plugin</artifactId> - <configuration> - <logClasspath>true</logClasspath> - </configuration> - </plugin> +[source,xml] +---- +<plugin> + <groupId>org.apache.camel</groupId> + <artifactId>camel-maven-plugin</artifactId> + <configuration> + <logClasspath>true</logClasspath> + </configuration> +</plugin> +---- === Using live reload of XML files You can configure the plugin to scan for XML file changes and trigger a reload of the Camel routes which are contained in those XML files. - <plugin> - <groupId>org.apache.camel</groupId> - <artifactId>camel-maven-plugin</artifactId> - <configuration> - <fileWatcherDirectory>src/main/resources/META-INF/spring</fileWatcherDirectory> - </configuration> - </plugin> +[source,xml] +---- +<plugin> + <groupId>org.apache.camel</groupId> + <artifactId>camel-maven-plugin</artifactId> + <configuration> + <fileWatcherDirectory>src/main/resources/META-INF/spring</fileWatcherDirectory> + </configuration> +</plugin> +---- Then the plugin watches this directory. This allows you to edit the source code from your editor and save the file, and have the running Camel application pickup those changes. @@ -120,23 +137,27 @@ For validating the source code for mis configured Camel: Then you can run the validate goal from the command line or from within your Java editor such as IDEA or Eclipse. - mvn camel:validate +---- +mvn camel:validate +---- You can also enable the plugin to automatic run as part of the build to catch these errors. - <plugin> - <groupId>org.apache.camel</groupId> - <artifactId>camel-maven-plugin</artifactId> - <version>2.19.0</version> - <executions> - <execution> - <phase>process-classes</phase> - <goals> - <goal>validate</goal> - </goals> - </execution> - </executions> - </plugin> +[source,xml] +---- +<plugin> + <groupId>org.apache.camel</groupId> + <artifactId>camel-maven-plugin</artifactId> + <executions> + <execution> + <phase>process-classes</phase> + <goals> + <goal>validate</goal> + </goals> + </execution> + </executions> +</plugin> +---- The phase determines when the plugin runs. In the sample above the phase is `process-classes` which runs after the compilation of the main source code. @@ -144,23 +165,24 @@ the compilation of the main source code. The maven plugin can also be configured to validate the test source code , which means that the phase should be changed accordingly to `process-test-classes` as shown below: - <plugin> - <groupId>org.apache.camel</groupId> - <artifactId>camel-maven-plugin</artifactId> - <version>2.19.0</version> - <executions> - <execution> - <configuration> - <includeTest>true</includeTest> - </configuration> - <phase>process-test-classes</phase> - <goals> - <goal>validate</goal> - </goals> - </execution> - </executions> - </plugin> - +[source,xml] +---- +<plugin> + <groupId>org.apache.camel</groupId> + <artifactId>camel-maven-plugin</artifactId> + <executions> + <execution> + <configuration> + <includeTest>true</includeTest> + </configuration> + <phase>process-test-classes</phase> + <goals> + <goal>validate</goal> + </goals> + </execution> + </executions> +</plugin> +---- === Running the goal on any Maven project @@ -168,12 +190,14 @@ You can also run the validate goal on any Maven project without having to add th Doing so requires to specify the plugin using its fully qualified name. For example to run the goal on the `camel-example-cdi` from Apache Camel you can run - $cd camel-example-cdi - $mvn org.apache.camel:camel-maven-plugin:2.19.0:validate +---- +$cd camel-example-cdi +$mvn org.apache.camel:camel-maven-plugin:2.19.0:validate +---- which then runs and outputs the following: -``` +---- [INFO] ------------------------------------------------------------------------ [INFO] Building Camel :: Example :: CDI 2.19.0 [INFO] ------------------------------------------------------------------------ @@ -184,19 +208,26 @@ which then runs and outputs the following: [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ -``` +---- The validation passed, and 4 endpoints was validated. Now suppose we made a typo in one of the Camel endpoint uris in the source code, such as: - @Uri("timer:foo?period=5000") +[source,java] +---- +@Uri("timer:foo?period=5000") +---- + is changed to include a typo error in the `period` option - @Uri("timer:foo?perid=5000") +[source,java] +---- +@Uri("timer:foo?perid=5000") +---- And when running the validate goal again reports the following: -``` +---- [INFO] ------------------------------------------------------------------------ [INFO] Building Camel :: Example :: CDI 2.19.0 [INFO] ------------------------------------------------------------------------ @@ -214,14 +245,14 @@ And when running the validate goal again reports the following: [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ -``` +---- === Options The maven plugin supports the following options which can be configured from the command line (use `-D` syntax), or defined in the `pom.xml` file in the `<configuration>` tag. -|======================================== +|=== | Parameter | Default Value | Description | downloadVersion | true | Whether to allow downloading Camel catalog version from the internet. This is needed if the project uses a different Camel version than this plugin is using by default. | failOnError | false | Whether to fail if invalid Camel endpoints was found. By default the plugin logs the errors at WARN level. @@ -236,7 +267,7 @@ The maven plugin supports the following options which can be configured from the | ignoreLenientProperties | true | Whether to ignore components that uses lenient properties. When this is true, then the uri validation is stricter but would fail on properties that are not part of the component but in the uri because of using lenient properties. For example using the HTTP components to provide query parameters in the endpoint uri. | duplicateRouteId | true | *Camel 2.20* Whether to validate for duplicate route ids. Route ids should be unique and if there are duplicates then Camel will fail to startup. | showAll | false | Whether to show all endpoints and simple expressions (both invalid and valid). -|======================================== +|=== === Validating include test @@ -244,6 +275,74 @@ The maven plugin supports the following options which can be configured from the If you have a Maven project then you can run the plugin to validate the endpoints in the unit test source code as well. You can pass in the options using `-D` style as shown: - $cd myproject - $mvn org.apache.camel:camel-maven-plugin:2.19.0:validate -DincludeTest=true +---- +$cd myproject +$mvn org.apache.camel:camel-maven-plugin:2.19.0:validate -DincludeTest=true +---- + + +== camel:route-coverage + +For generating a report of the coverage of your Camel routes from unit testing. +In the same manner you can generate Java code coverage reports, then this is the same but for Camel routes. +You can therefore use this to know which parts of your Camel routes has been used or not. + +=== Enabling route coverage + +You need to enable route coverage in the unit tests classes. You can do this by adding the `@EnableRouteCoverage` +annotation to the test class if you are testing using `camel-test-spring`: + +[source,java] +---- +@RunWith(CamelSpringBootRunner.class) +@SpringBootTest(classes = SampleCamelApplication.class) +@EnableRouteCoverage +public class FooApplicationTest { +---- + +However if you are using `camel-test` and your unit tests are extending `CamelTestSupport` then you can +turn on route coverage as shown: + +[source,java] +---- +@Override +public boolean isDumpRouteCoverage() { + return true; +} +---- + +=== Generating route coverage report + +After unit testing with: + +---- +mvn test +---- + +You can then run the goal to report the route coverage + +---- +mvn camel:route-coverage +---- + +Which then reports which routes has missing route coverage with precise source code line reporting: + +---- + TODO: sample +---- + +=== Options + + +The maven plugin supports the following options which can be configured from the command line (use `-D` syntax), or defined in the `pom.xml` file in the `<configuration>` tag. + +|=== +| Parameter | Default Value | Description +| failOnError | false | Whether to fail if any of the routes has not 100% coverage. +| includeTest | false | Whether to include test source code. +| includes | | To filter the names of java and xml files to only include files matching any of the given list of patterns (wildcard and regular expression). Multiple values can be separated by comma. +| excludes | | To filter the names of java and xml files to exclude files matching any of the given list of patterns (wildcard and regular expression). Multiple values can be separated by comma. +|=== + +
