Cluecumber Reporting Engine

Cluecumber is a reporting tool that generates aggregated test reports from Cucumber-compatible JSON files. It supports JSON formats generated by Cucumber BDD, Karate, and other compatible frameworks.

There are two ways to use Cluecumber:

• Cluecumber Core: Used to generate reports directly from Java code (e.g., within Karate runners).
• Cluecumber Maven: Used to generate reports via Maven.

Reports can be customized with a custom logo, favicon, CSS, custom parameters, custom links, and custom embedded views.

Cluecumber Engine is the primary component responsible for generating reports. It is designed to be an internal component used by higher-level tools like Cluecumber Core and Cluecumber Maven.

Important: Do not use Cluecumber Engine as a standalone dependency. If you need to generate reports programmatically from your own code, you should use Cluecumber Core instead.

To generate a report, use the CluecumberCore.Builder to instantiate the reporter and call generateReports(jsonDirectory, reportDirectory).

Two parameters are mandatory:

• jsonDirectory: The source folder containing your Cucumber JSON result files.
• reportDirectory: The root directory where the Cluecumber HTML report will be generated.

Typically, both directories should be located within your Maven target folder.

String jsonDirectory = "examples/core-example/json";
String reportDirectory = "examples/core-example/target/cluecumber_report";

new CluecumberCore.Builder()
        .build().generateReports(jsonDirectory, reportDirectory);

Add the cluecumber-core dependency to your pom.xml to use Cluecumber for JVM reporting of Cucumber BDD JSON formats.

<dependency>
  <groupId>com.trivago.rta</groupId>
  <artifactId>cluecumber-core</artifactId>
  <version>4.0.0</version>
</dependency>

Before generating reports, you must ensure your Cucumber runner is configured to output JSON files. In your Cucumber runner configuration, add the json plugin pointing to a target directory.

@CucumberOptions(
    plugin = {"json:target/cucumber-report/cucumber.json"}
)

To include custom data in your report via the command line, follow these two steps:

1. In your pom.xml: Define an empty property in the <properties> block and map it inside the <customParameters> section of the Cluecumber configuration.
2. Via Command Line: Pass the property using the -D flag.

If the property is not passed during execution, Cluecumber will ignore it and it will not appear in the report.

<!-- 1. Setup in pom.xml -->
<properties>
    <someProperty/>
</properties>

<configuration>
    <customParameters>
        <My_Parameter_Name>${someProperty}</My_Parameter_Name>
    </customParameters>
</configuration>

# 2. Pass the value via CLI
mvn cluecumber:reporting -DsomeProperty="this is cool"

To use Cluecumber for Maven reporting, add the cluecumber-maven plugin to your pom.xml. It is recommended to bind the reporting goal to the post-integration-test phase to ensure reports are generated after tests complete.

<plugin>
    <groupId>com.trivago.rta</groupId>
    <artifactId>cluecumber-maven</artifactId>
    <version>4.0.0</version>
    <executions>
        <execution>
            <id>report</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>reporting</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <sourceJsonReportDirectory>${project.build.directory}/cucumber-report</sourceJsonReportDirectory>
        <generatedHtmlReportDirectory>${project.build.directory}/generated-report</generatedHtmlReportDirectory>
    </configuration>
</plugin>

Cluecumber requires Cucumber JSON result files as input. You must configure your Cucumber runner to generate these files by adding the json plugin to your @CucumberOptions:

@CucumberOptions(
        plugin = {"json:target/cucumber-report/cucumber.json"}
)

Building from source

To build Cluecumber from source, you need:

• Java >= 17
• Maven >= 3.9.9

Runtime requirements

To use cluecumber-core at runtime, you must have:

• Java >= 17 (via cluecumber-engine)