开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Clear and Concise Cucumber Reporting for Maven

• Cluecumber Report Maven Plugin
  • Example report
  • Changelog
• Prerequisites
• Maven POM settings
  • Mandatory Configuration Parameters
    • sourceJsonReportDirectory
    • generatedHtmlReportDirectory
  • Optional Configuration Parameters
    • Plugin Logging
    • Add Custom Information to the Report
      • Add Custom Information Using Properties
      • Add Custom Information Using a File
      • Where to Display Custom Parameters
    • Skip Report Generation
    • Fail Scenarios on Pending or Undefined Steps
    • Auto-expand Certain Report Sections
    • Auto-expand Attachments
  • Optional Configuration Parameters for Changing the Report Appearance
    • Defining the report start page
    • Defining a custom report title
    • Defining a custom CSS file
    • Defining custom passed, skipped and failed colors
• Running the reporting goal directly via command line
  • Passing properties via command line
  • Passing custom parameters via command line
• Example project
• Appendix
  • Building
  • Generated pages
  • License

Cluecumber Report Maven Plugin

This plugin creates aggregated test reports from Cucumber compatible JSON files that are generated by Cucumber BDD, Karate and other frameworks.

This project was created because other projects...

• use legacy technology or were not maintained
• generate HTML code in Java making it hard to adapt
• show too much unneeded or even wrong information
• have a high memory consumption when generating reports from large JSON files
• do not support new Cucumber features
• have limited customization options

Note: From Cluecumber 1.10.2 on, Cluecumber fully supports Cucumber's new scenario start timestamps!

If you need to run Cucumber tests in parallel, please check out our Cucable project!

Example report

A fully generated example report can also be viewed online!

Changelog

All changes are documented in the full changelog.

Prerequisites

In order to have the JSON files as a source for the Cluecumber Report generation, you need to specify this option in your Cucumber runner configuration:

Cucumber 1.x:

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

Cucumber >= 2.x:

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

This will generate JSON results for all Cucumber tests.

Maven POM settings

<plugin>
    <groupId>com.trivago.rta</groupId>
    <artifactId>cluecumber-report-plugin</artifactId>
    <version>Check the version number above</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>

Mandatory Configuration Parameters

There are two mandatory parameters that have to be specified within the Maven POM configuration section or system properties:

Note: Typically, both properties point to directories inside the Maven target directory.

sourceJsonReportDirectory

This specifies the source folder of the Cucumber JSON result files.

<configuration>
    <sourceJsonReportDirectory>c:/example/json-files</sourceJsonReportDirectory>
    ...
</configuration>

generatedHtmlReportDirectory

This points to the root directory of the generated Cluecumber HTML report.

<configuration>
    <generatedHtmlReportDirectory>c:/example/my-report</generatedHtmlReportDirectory>
    ...
</configuration>

Optional Configuration Parameters

Plugin Logging

By default, Cluecumber logs all information including

• its own name and version
• all passed property values
• the generated report location

This can be configured by passing the logLevel property:

<logLevel>default|compact|minimal|off</logLevel>

• default will log all the mentioned information
• compact will only log the source and target directories, plugin name and version and the generated report location
• minimal will only log the generated report location
• off will prevent any logging

Add Custom Information to the Report

Add Custom Information Using Properties

The customParameters block can be used to define custom information that should be displayed on the report start page.

Note: Underscores in the parameter names are automatically turned into spaces in the report. Valid URLs that start with a protocol (http, https, ftp) are automatically recognized and turned into clickable links. If a parameter name starts with an underscore (_), only the value is displayed.

<configuration>
    <customParameters>
        <Custom_Parameter>This is a test</Custom_Parameter>
        <Custom_URL>http://www.google.com</Custom_URL>
        <_Text>This is a long text that is displayed without the key. This can be used to display longer texts in the report!</_Text>
    </customParameters>
    ...
</configuration>

The property definitions above are shown in the report like this:

Add Custom Information Using a File

You can also set custom parameters by specifying the path to a .properties file in the customParametersFile property like this:

<configuration>
    <customParametersFile>path/to/your/customParameters.properties</customParametersFile>
    ...
</configuration>

This file needs to have a format like this:

Custom_Parameter=This is a test
Custom_URL=http://www.google.com
_Text=This is a long text that is displayed without the key. This can be used to display longer texts in the report!

Note: These custom parameters behave exactly like the ones defined by the customParameters property and will be added on top of already defined properties. If a property has the same name as an existing one, its value will be overwritten!

The property definitions above are shown in the report like this:

Where to Display Custom Parameters

You can decide how to display the custom parameters in the report using the customParametersDisplayMode property.

The following display modes are available for displaying the custom parameters:

• SCENARIO_PAGES: Displays only on the scenario and scenario sequence pages. (default)
• ALL_PAGES: Display on all the pages in the report.

<configuration>
    <customParametersDisplayMode>ALL_PAGES</customParametersDisplayMode>
    ...
</configuration>

The default value for this property is START_PAGE.

Skip Report Generation

The skip property is used to skip the report generation. The default value is false

<configuration>
    <skip>true</skip>
    ...
</configuration>

Fail Scenarios on Pending or Undefined Steps

The optional failScenariosOnPendingOrUndefinedSteps property can be set to true if you scenarios should be marked as failed when they contain pending or skipped steps. The default setting is false, meaning that those scenarios will be marked as skipped.

<configuration>
    <failScenariosOnPendingOrUndefinedSteps>true</failScenariosOnPendingOrUndefinedSteps>
    ...
</configuration>

Auto-expand Certain Report Sections

The expandBeforeAfterHooks, expandStepHooks and expandDocStrings options can be set to true to expand or collapse before/after hooks, step hooks or docstrings respectively on scenario detail pages.

If they are not set, they default to false. This means that the report user has to use the buttons on a scenario detail page to expand those sections on demand.

<configuration>
    <expandBeforeAfterHooks>true|false</expandBeforeAfterHooks>
    <expandStepHooks>true|false</expandStepHooks>
    <expandDocStrings>true|false</expandDocStrings>
    ...
</configuration>

Auto-expand Attachments

By default, attachments are collapsed and can be toggled individually. If the expandAttachments options is set to true, they are automatically expanded.

<configuration>
    <expandAttachments>true|false</expandAttachments>
    ...
</configuration>

Optional Configuration Parameters for Changing the Report Appearance

Defining the report start page

The default start page of the reports (if not overwritten by the startPage property) is the scenario overview page.

<configuration>
    <startPage>ALL_SCENARIOS</startPage>
    ...
</configuration>

This can be customized with one of the following values:

• ALL_SCENARIOS (scenario overview page, default)
• SCENARIO_SEQUENCE (scenario sequence page)
• ALL_TAGS (tag overview page)
• ALL_STEPS (step overview page)
• ALL_FEATURES (feature overview page)

Defining a custom report title

By default, the page html title of the report pages is Cluecumber Report plus the current page name, e.g. Cluecumber Report - All Tags.

By setting the property customPageTitle, this can be changed:

<configuration>
    <customPageTitle>My Report</customPageTitle>
    ...
</configuration>

This would lead to a report title like this:

Defining a custom CSS file

The customCSS property can be used to define a custom CSS file that will be automatically loaded on top of Cluecumber's default styles.

If you have a custom CSS file called custom/custom.css in your project, you could use it to change the report's background and header colors:

body {
    background-color: black;
}

h3, h4, h5 {
    color: white;
}

To use this files, specify it like so in your pom file or as a system property:

<configuration>
    <customCss>custom/custom.css</customCss>
    ...
</configuration>

When generating the report, this file is automatically included as cluecumber_custom.css and applied on top of all other styles:

Likewise, if you want to hide elements from the report, you can also add this to the custom css like so:

.some_element {
    display: none;
}

Defining custom passed, skipped and failed colors

It is possible to set these properties to change the color scheme for passed, failed and skipped steps and scenarios including the displayed diagrams. The values have to be valid hex colors:

<configuration>
    <customStatusColorPassed>#017FAF</customStatusColorPassed>
    <customStatusColorFailed>#C94A38</customStatusColorFailed>
    <customStatusColorSkipped>#F48F00</customStatusColorSkipped>
    ...
</configuration>    

The result of this customization is:

Before	After

Running the reporting goal directly via command line

In some cases it may be desirable to run the reporting as a completely separate step, e.g. in CI pipelines. This can be done by running

mvn cluecumber-report:reporting

directly from the command line.

Note: If you want this invocation to consider the configuration that is included in your POM file, the configuration block must be outside of your executions block. Otherwise, it only applies to the specified execution and is ignored when you run mvn cluecumber-report:reporting from the command line:

<executions>
    <execution>
        <id>report</id>
        <phase>post-integration-test</phase>
        <goals>
            <goal>reporting</goal>
        </goals>
        <configuration>
            <!-- This configuration block applies ONLY to this execution -->
        </configuration>
    </execution>
</executions>
<configuration>
    <!-- This configuration block applies to all executions including command line invocation -->
</configuration>

Passing properties via command line

You can also pass properties directly on the command line, e.g.

mvn cluecumber-report:reporting -DsourceJsonReportDirectory=path_to_json_files -D...

Passing custom parameters via command line

If you want to set a custom parameter, you can do it like this:

Set an empty property in your pom file's properties block:

<properties>
    <someProperty/>
</properties>

Also define it in the Cluecumber section in your POM:

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

When invoking the reporting, you can now pass this property via the -D option:

mvn cluecumber-report:reporting -DsomeProperty="this is cool" -D...

Note: If you don't pass this property, Cluecumber will ignore it and not show it in the report.

Example project

You can test the complete flow and POM configuration by checking out the Cluecumber example project.

Appendix

Building

Cluecumber requires Java >= 8 and Maven >= 3.3.9. It is available in Maven central.

Generated pages

• All Scenarios: all scenarios grouped by their status passed, failed or skipped.
• Scenario Sequence: all scenarios in running order including their individual status information
• Scenario Details: all steps, hooks, stack traces and attachments of a single scenario
• All Features: an overview of all features
• All Tags: all used tags in scenarios, features and example tables including their individual status information
• All Steps: all steps in use including their individual status information
• Scenarios by Tag: all scenarios including a specific tag
• Scenarios by Feature: all scenarios belonging to a specific feature
• Scenario by Step: all scenarios that include a specific step

License

Copyright 2018 - 2022 trivago N.V.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.