You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2020/02/18 14:23:53 UTC
[camel] branch master updated: Added camel-report-maven-plugin
documentation
This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new 50ceb42 Added camel-report-maven-plugin documentation
50ceb42 is described below
commit 50ceb429ff3c8eea6b14e8750a3c9645afaf2812
Author: Andrea Cosentino <an...@gmail.com>
AuthorDate: Tue Feb 18 15:19:09 2020 +0100
Added camel-report-maven-plugin documentation
---
.../ROOT/pages/camel-report-maven-plugin.adoc | 316 +++++++++++++++++++++
docs/user-manual/modules/ROOT/pages/index.adoc | 1 +
2 files changed, 317 insertions(+)
diff --git a/docs/user-manual/modules/ROOT/pages/camel-report-maven-plugin.adoc b/docs/user-manual/modules/ROOT/pages/camel-report-maven-plugin.adoc
new file mode 100644
index 0000000..8f01ef9
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-report-maven-plugin.adoc
@@ -0,0 +1,316 @@
+= Camel Report Maven Plugin
+
+The Camel Report Maven Plugin supports the following goals
+
+ - camel-report:validate - To validate your source code for invalid Camel endpoint uris
+ - camel-report:route-coverage - To report the coverage of your Camel routes after unit testing
+
+== camel:validate
+
+For validating the source code for mis configured Camel:
+
+- endpoint uris
+- simple expressions or predicates
+- duplicate route ids
+- seda/direct endpoint pairs
+- configuration in properties files
+
+Then you can run the validate goal from the command line or from within your Java editor such as IDEA or Eclipse.
+
+----
+mvn camel-report:validate
+----
+
+You can also enable the plugin to automatic run as part of the build to catch these errors.
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-report-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.
+
+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:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-report-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
+
+You can also run the validate goal on any Maven project without having to add the plugin to the `pom.xml` file.
+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-report-maven-plugin:2.20.0:validate
+----
+
+which then runs and outputs the following:
+
+----
+[INFO] ------------------------------------------------------------------------
+[INFO] Building Camel :: Example :: CDI 3.0.0
+[INFO] ------------------------------------------------------------------------
+[INFO]
+[INFO] --- camel-report-maven-plugin:3.0.0:validate (default-cli) @ camel-example-cdi ---
+[INFO] Endpoint validation success: (4 = passed, 0 = invalid, 0 = incapable, 0 = unknown components)
+[INFO] Simple validation success: (0 = passed, 0 = invalid)
+[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:
+
+[source,java]
+----
+@Uri("timer:foo?period=5000")
+----
+
+
+is changed to include a typo error in the `period` option
+
+[source,java]
+----
+@Uri("timer:foo?perid=5000")
+----
+
+And when running the validate goal again reports the following:
+
+----
+[INFO] ------------------------------------------------------------------------
+[INFO] Building Camel :: Example :: CDI 3.0.0
+[INFO] ------------------------------------------------------------------------
+[INFO]
+[INFO] --- camel-report-maven-plugin:3.0.0:validate (default-cli) @ camel-example-cdi ---
+[WARNING] Endpoint validation error at: org.apache.camel.example.cdi.MyRoutes(MyRoutes.java:32)
+
+ timer:foo?perid=5000
+
+ perid Unknown option. Did you mean: [period]
+
+
+[WARNING] Endpoint validation error: (3 = passed, 1 = invalid, 0 = incapable, 0 = unknown components)
+[INFO] Simple validation success: (0 = passed, 0 = invalid)
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+----
+
+=== Options
+
+The maven plugin *validate* goal 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.
+| logUnparseable | false | Whether to log endpoint URIs which was un-parsable and therefore not possible to validate.
+| includeJava | true | Whether to include Java files to be validated for invalid Camel endpoints.
+| includeXml | true | Whether to include XML files to be validated for invalid Camel endpoints.
+| 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.
+| ignoreUnknownComponent | true | Whether to ignore unknown components.
+| ignoreIncapable | true | Whether to ignore incapable of parsing the endpoint uri or simple expression.
+| 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.
+| ignoreDeprecated | true |Whether to ignore deprecated options being used in the endpoint uri.
+| duplicateRouteId | true |Whether to validate for duplicate route ids. Route ids should be unique and if there are duplicates then Camel will fail to startup.
+| directOrSedaPairCheck | true |Whether to validate direct/seda endpoints sending to non existing consumers.
+| configurationFiles | application.properties | Location of configuration files to validate. The default is application.properties. Multiple values can be separated by comma and use wildcard pattern matching.
+| showAll | false | Whether to show all endpoints and simple expressions (both invalid and valid).
+|===
+
+For example to turn off ignoring usage of deprecated options from the command line, you can run:
+
+----
+$mvn camel-report:validate -Dcamel.ignoreDeprecated=true
+----
+
+Notice that you must prefix the `-D` command argument with `camel.`, eg `camel.ignoreDeprecated` as the option name.
+
+=== Validating include test
+
+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-report-maven-plugin:3.0.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 can enable route coverage while running unit tests either by
+
+- setting global JVM system property enabling for all test classes
+- using `@EnableRouteCoverage` annotation per test class if using `camel-test-spring` module
+- overriding `isDumpRouteCoverage` method per test class if using `camel-test` module
+
+==== Enabling via JVM system property
+
+You can turn on the JVM system property `CamelTestRouteCoverage` to enable route coverage for all tests cases.
+This can be done either in the configuration of the `maven-surefire-plugin`:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <systemPropertyVariables>
+ <CamelTestRouteCoverage>true</CamelTestRouteCoverage>
+ </systemPropertyVariables>
+ </configuration>
+</plugin>
+----
+
+Or from the command line when running tests:
+
+----
+mvn clean test -DCamelTestRouteCoverage=true
+----
+
+==== Enabling via @EnableRouteCoverage annotation
+
+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 {
+----
+
+==== Enabling via isDumpRouteCoverage method
+
+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;
+}
+----
+
+Routes that can be route coveraged must have an unique id assigned, in other words you cannot use anonymous routes.
+
+You do this using `routeId` in Java DSL:
+
+[source,java]
+----
+from("jms:queue:cheese").routeId("cheesy")
+ .to("log:foo")
+ ...
+----
+
+And in XML DSL you just assign the route id via the id attribute
+
+[source,xml]
+----
+<route id="cheesy">
+ <from uri="jms:queue:cheese"/>
+ <to uri="log:foo"/>
+ ...
+</route>
+----
+
+=== Generating route coverage report
+
+After unit testing with:
+
+----
+mvn test
+----
+
+You can then run the goal to report the route coverage
+
+----
+mvn camel-report:route-coverage
+----
+
+Which then reports which routes has missing route coverage with precise source code line reporting:
+
+----
+[INFO] --- camel-camel-report-plugin:3.0.0:route-coverage (default-cli) @ camel-example-spring-boot-xml ---
+[INFO] Discovered 1 routes
+[INFO] Route coverage summary:
+
+File: src/main/resources/my-camel.xml
+RouteId: hello
+
+ Line # Count Route
+ ------ ----- -----
+ 28 1 from
+ 29 1 transform
+ 32 1 filter
+ 34 0 to
+ 36 1 to
+
+Coverage: 4 out of 5 (80.0%)
+----
+
+Here we can see that the 2nd last line with `to` has `0` in the count column, and therefore is not covered.
+We can also see that this is one line 34 in the source code file, which is in the `my-camel.xml` XML file.
+
+=== Options
+
+The maven plugin *coverage* goal 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.
+| anonymousRoutes | false | Whether to allow anonymous routes (routes without any route id assigned).
+ By using route id's then its safer to match the route cover data with the route source code.
+ Anonymous routes are less safe to use for route coverage as its harder to know exactly which route
+ that was tested corresponds to which of the routes from the source code.
+| generateJacocoXmlReport | false | Whether to generate a coverage-report in Jacoco XML format, when enabled it will generate a file: `target/site/jacoco/xmlJacoco.xml`
+|===
+
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc b/docs/user-manual/modules/ROOT/pages/index.adoc
index 37d8392..aeccd85 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -47,6 +47,7 @@
* [Using CamelProxy] for how to use proxies for clients to easily invoke
camel routes without them knowing
* xref:camel-maven-plugin.adoc[Camel Maven Plugin] for running Camel from a Maven goal
+* xref:camel-report-maven-plugin.adoc[Camel Maven Report Plugin] to validate your source code and report the code coverage of your camel routes
* xref:camel-maven-archetypes.adoc[Camel Maven Archetypes]
* xref:creating-a-new-spring-based-camel-route.adoc[Creating a new Spring based Camel Route]
* xref:components::jmx-component.adoc[Camel JMX]