# 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
    

Java routes are read with the Java DSL parser of camel-java-io, and XML routes with camel-route-parser, without compiling or running them. In a Java route, a value only known at runtime, such as a port held in a field, is validated as a property placeholder (`http://localhost:{{port}}/orders`); an endpoint injected into a field with `@EndpointInject`, and a field with a string initializer, are read as well.

Then you can run the `validate` goal from the command line or from within your Java editor such as IDEA or Eclipse.

```bash
mvn camel-report:validate
```

You can also enable the plugin to run automatically as part of the build to catch these errors.

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

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

```bash
cd camel-example-cdi
mvn org.apache.camel:camel-report-maven-plugin:2.20.0:validate
```

which then runs and outputs the following:

```text
[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:

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

is changed to include a typo error in the `period` option

```java
@Uri("timer:foo?perid=5000")
```

And when running the `validate` goal again reports the following:

```text
[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.

<table class="tableblock frame-all grid-all stretch"><colgroup><col> <col> <col></colgroup><tbody><tr><td class="tableblock halign-left valign-top">Parameter</td><td class="tableblock halign-left valign-top">Default Value</td><td class="tableblock halign-left valign-top">Description</td></tr><tr><td class="tableblock halign-left valign-top">downloadVersion</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">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.</td></tr><tr><td class="tableblock halign-left valign-top">failOnError</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to fail if invalid Camel endpoints was found. By default the plugin logs the errors at WARN level.</td></tr><tr><td class="tableblock halign-left valign-top">coverageThreshold</td><td class="tableblock halign-left valign-top">100</td><td class="tableblock halign-left valign-top">The minimum route coverage in percent when using failOnError.</td></tr><tr><td class="tableblock halign-left valign-top">overallCoverageThreshold</td><td class="tableblock halign-left valign-top">0</td><td class="tableblock halign-left valign-top">The minimum coverage across all routes in percent when using failOnError.</td></tr><tr><td class="tableblock halign-left valign-top">logUnparseable</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to log endpoint URIs which was un-parsable and therefore not possible to validate.</td></tr><tr><td class="tableblock halign-left valign-top">includeJava</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">Whether to include Java files to be validated for invalid Camel endpoints.</td></tr><tr><td class="tableblock halign-left valign-top">includeXml</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">Whether to include XML files to be validated for invalid Camel endpoints.</td></tr><tr><td class="tableblock halign-left valign-top">includeTest</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to include test source code.</td></tr><tr><td class="tableblock halign-left valign-top">includes</td><td class="tableblock halign-left valign-top"></td><td class="tableblock halign-left valign-top">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.</td></tr><tr><td class="tableblock halign-left valign-top">excludes</td><td class="tableblock halign-left valign-top"></td><td class="tableblock halign-left valign-top">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.</td></tr><tr><td class="tableblock halign-left valign-top">ignoreUnknownComponent</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">Whether to ignore unknown components.</td></tr><tr><td class="tableblock halign-left valign-top">ignoreIncapable</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">Whether to ignore incapable of parsing the endpoint uri or simple expression.</td></tr><tr><td class="tableblock halign-left valign-top">ignoreLenientProperties</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">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.</td></tr><tr><td class="tableblock halign-left valign-top">ignoreDeprecated</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">Whether to ignore deprecated options being used in the endpoint uri.</td></tr><tr><td class="tableblock halign-left valign-top">duplicateRouteId</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">Whether to validate for duplicate route ids. Route ids should be unique and if there are duplicates then Camel will fail to startup.</td></tr><tr><td class="tableblock halign-left valign-top">directOrSedaPairCheck</td><td class="tableblock halign-left valign-top">true</td><td class="tableblock halign-left valign-top">Whether to validate direct/seda endpoints sending to non existing consumers.</td></tr><tr><td class="tableblock halign-left valign-top">configurationFiles</td><td class="tableblock halign-left valign-top">application.properties</td><td class="tableblock halign-left valign-top">Location of configuration files to validate. The default is application.properties. Multiple values can be separated by comma and use wildcard pattern matching.</td></tr><tr><td class="tableblock halign-left valign-top">showAll</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to show all endpoints and simple expressions (both invalid and valid).</td></tr><tr><td class="tableblock halign-left valign-top">downloadTransitiveArtifacts</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">When sourcesArtifacts are declared, this flag can be used to download transitive dependencies, carefully enable this flag since it will try to download the whole dependency tree.</td></tr><tr><td class="tableblock halign-left valign-top">sourcesArtifacts</td><td class="tableblock halign-left valign-top"></td><td class="tableblock halign-left valign-top">List of sources transitive dependencies that contain camel routes, this option can be used to download extra dependencies that contain camel route that your project may depend on.</td></tr><tr><td class="tableblock halign-left valign-top">extraMavenRepositories</td><td class="tableblock halign-left valign-top"></td><td class="tableblock halign-left valign-top">List of extra maven repositories.</td></tr></tbody></table>

For example to turn on ignoring usage of deprecated options from the command line, you can run:

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

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

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

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

> **Important**
> Only regular `@Test` methods are supported. For example using `@ParameterizedTest` can lead to inaccurate results reported.

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

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

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

```java
@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_

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

> **Important**
> Routes that can be route coveraged **MUST** have a unique id assigned, in other words you cannot use anonymous routes.

You do this using `routeId`:

-   Java
    
-   XML
    
-   YAML
    

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

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

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

### Generating route coverage report

After unit testing with:

```bash
mvn test
```

You can then run the goal to report the route coverage

```bash
mvn camel-report:route-coverage
```

Which then reports which routes has missing route coverage with precise source code line reporting:

```text
[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.

### Showing the body types

When the tests run with the message history on (such as `camel.main.messageHistory=true`), the route coverage dump also has the body types each step has been reached with, across the messages of the tests (from Camel 4.24). Run the goal with `bodyTypes` to show them:

```bash
mvn camel-report:route-coverage -Dcamel.bodyTypes=true
```

```text
  Line #       Count    Route          Body types
  ------       -----    -----          ----------
       3           2    from
       4           2      unmarshal    String
       7           2      to           LinkedHashMap | String (data and payload)
```

A step reached with more than one type is a part of the route that is dynamic. When the types are of more than one kind (`null`, `payload`, `data` or `collection`), as for the `to` here, the step needs attention: some messages reach it with data, others with a payload, so a step that writes the body, or reads its fields, fails for some of them. See [Message History](../components/4.22.x/eips/message-history.md) for the body types and their kinds.

To fail the build when a step has been reached with bodies of more than one kind, such as in a CI build that runs the tests with the messages of the expected workload, use `failOnMixedBodyKinds`:

```bash
mvn camel-report:route-coverage -Dcamel.failOnMixedBodyKinds=true
```

```text
[WARNING] 1 step(s) have been reached with bodies of more than one kind: some messages bring data and others a payload, so a step that writes the body, or reads its fields, fails for some of them:
    routes/orders.xml:7 to (route orders): LinkedHashMap | String (data and payload)
[ERROR] Failed to execute goal org.apache.camel:camel-report-maven-plugin:route-coverage (default-cli): There are 1 step(s) reached with bodies of more than one kind!
```

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

<table class="tableblock frame-all grid-all stretch"><colgroup><col> <col> <col></colgroup><tbody><tr><td class="tableblock halign-left valign-top">Parameter</td><td class="tableblock halign-left valign-top">Default Value</td><td class="tableblock halign-left valign-top">Description</td></tr><tr><td class="tableblock halign-left valign-top">failOnError</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to fail if any of the routes has not 100% coverage.</td></tr><tr><td class="tableblock halign-left valign-top">includeTest</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to include test source code.</td></tr><tr><td class="tableblock halign-left valign-top">includes</td><td class="tableblock halign-left valign-top"></td><td class="tableblock halign-left valign-top">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.</td></tr><tr><td class="tableblock halign-left valign-top">excludes</td><td class="tableblock halign-left valign-top"></td><td class="tableblock halign-left valign-top">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.</td></tr><tr><td class="tableblock halign-left valign-top">anonymousRoutes</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top"><strong>Deprecated</strong> Whether to allow anonymous routes (routes without any route id assigned). By using route id’s then it is 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.</td></tr><tr><td class="tableblock halign-left valign-top">generateJacocoXmlReport</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to generate a coverage-report in Jacoco XML format. When enabled it will generate the file: <code>target/site/jacoco/xmlJacoco.xml</code></td></tr><tr><td class="tableblock halign-left valign-top">generateHtmlReport</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to generate a coverage-report in HTML format. When enabled it will generate the file: <code>target/site/route-coverage/html/index.html</code></td></tr><tr><td class="tableblock halign-left valign-top">bodyTypes</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to show the body types each step has been reached with, which the route coverage dump has when the tests ran with the message history on (Camel 4.24 or newer).</td></tr><tr><td class="tableblock halign-left valign-top">failOnMixedBodyKinds</td><td class="tableblock halign-left valign-top">false</td><td class="tableblock halign-left valign-top">Whether to fail when a step has been reached with bodies of more than one kind (null, payload, data or collection) in the tests: some messages reach it with data and others with a payload, so a step that writes the body, or reads its fields, fails for some of them.</td></tr></tbody></table>