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-report: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 run automatically as part of the build to catch these errors.

<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:

<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:

@Uri("timer:foo?period=5000")

is changed to include a typo error in the period option

@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.

For example to turn on 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 -Dcamel.includeTest=true

Validate Apache Camel routes in transitive dependencies

If your routes use direct or seda endpoints that are not present in the current project, but the routes are declared into a dependency of your project, you can edit the plugin configuration accordingly so that these routes can be taken into account by the Camel validate plugin. In particular, in order to use the validate plugin with transitive dependencies, sources jars are needed, for example:

• Given the following Camel route from("direct:in").to("direct:out") defined in the current project
• The route from("direct:out") is declared into a dependency of your project, for example my.company:routes-dependency:1.0
• If routes-dependency sources are released into a maven repository, the following plugin configuration can be used:

<plugin>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-report-maven-plugin</artifactId>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>validate</goal>
      </goals>
      <configuration>
        <sourcesArtifacts>
          <sourcesArtifact>my.company:routes-dependency:jar:sources:1.0</sourcesArtifact>
        </sourcesArtifacts>
        <extraMavenRepositories>
          <extraMavenRepository>http://internal.repo:8080/maven</extraMavenRepository>
        </extraMavenRepositories>
      </configuration>
    </execution>
  </executions>
</plugin>

camel-report: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 have been used or not.

Camel uses JMX to capture metrics during tests which are used for calculating route coverage. You must have camel-management JAR on the classpath (can be test scoped) such as by declaring the following Maven dependency in your pom.xml file:

<!-- JMX is needed for route coverage testing -->
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-management</artifactId>
    <scope>test</scope>
</dependency>

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-junit5 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:

<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-junit5:

@CamelSpringBootTest
@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:

Java-only: enabling route coverage in CamelTestSupport

@Override
public boolean isDumpRouteCoverage() {
    return true;
}

You do this using routeId:

• Java
• XML
• YAML

from("jms:queue:cheese").routeId("cheesy")
  .to("log:foo")
  ...

<route id="cheesy">
  <from uri="jms:queue:cheese"/>
  <to uri="log:foo"/>
  ...
</route>

- route:
    id: cheesy
    from:
      uri: jms:queue:cheese
      steps:
        - to:
            uri: log:foo

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.