Skip to content

Commit

Permalink
Merge pull request #184 from trivago/2.1.0
Browse files Browse the repository at this point in the history 
2.1.0 - Customization, cleaned up design
  • Loading branch information
Benjamin Bischoff authored Jun 25, 2019
2 parents dff423f + edd3e0b commit f65e7fd
Show file tree
Hide file tree
Showing 222 changed files with 6,733 additions and 4,606 deletions.
22 changes: 22 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,46 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

Back to [Readme](README.md).

## [2.1.0] - UNRELEASED

### Added

* Fully customizable passed, failed and skipped colors through new properties (#172)
* Proper pluralization of all words within summaries and headers
* Ability to set a custom report title (#176)
* Support for custom parameters with hidden keys (#183)

### Changed

* Better layout with larger graphs for tag, feature and step summary pages (#180)
* Moved timing information to a dedicated box in each report page
* Refined navigation (#177)
* Increased max report width

## [2.0.1] - 2019-06-15

### Fixed

* Error when `customParametersFile` property was not set (#171)
* Wrong log format for `customCssFile` property

### Added

* Better error messages for missing files

## [2.0.0] - 2019-06-14

### Added

* Ability to set custom parameters via a properties file through the `customParametersFile` property (#167, contributed by gazler22)

### Fixed

* Custom parameters are now displayed in the order of definition (#157)
* Better logging and error handling

### Changed

* Major internal architecture change to ease future extension

## [1.11.0] - 2019-05-21
Expand Down Expand Up @@ -479,6 +500,7 @@ steps with status `pending` or `undefined` (default value is `false`) (#74)

Initial project version on GitHub and Maven Central.

[2.1.0]: https://github.com/trivago/cluecumber-report-plugin/tree/2.1.0
[2.0.1]: https://github.com/trivago/cluecumber-report-plugin/tree/2.0.1
[2.0.0]: https://github.com/trivago/cluecumber-report-plugin/tree/2.0.0
[1.11.0]: https://github.com/trivago/cluecumber-report-plugin/tree/1.11.0
Expand Down
184 changes: 91 additions & 93 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,28 +25,23 @@
- [sourceJsonReportDirectory](#sourcejsonreportdirectory)
- [generatedHtmlReportDirectory](#generatedhtmlreportdirectory)
- [Optional Configuration Parameters](#optional-configuration-parameters)
- [customParameters](#customparameters)
- [customParametersFile](#customparametersfile)
- [skip](#skip)
- [failScenariosOnPendingOrUndefinedSteps](#failscenariosonpendingorundefinedsteps)
- [customCSS](#customcss)
- [expandBeforeAfterHooks, expandStepHooks, expandDocStrings](#expandbeforeafterhooks-expandstephooks-expanddocstrings)
- [Add Custom Information to the Report](#add-custom-information-to-the-report)
- [Add Custom Information Using Properties](#add-custom-information-using-properties)
- [Add Custom Information Using a File](#add-custom-information-using-a-file)
- [Skip Report Generation](#skip-report-generation)
- [Fail Scenarios on Pending or Undefined Steps](#fail-scenarios-on-pending-or-undefined-steps)
- [Auto-expand Certain Report Sections](#auto-expand-certain-report-sections)
- [Optional Configuration Parameters for Changing the Report Appearance](#optional-configuration-parameters-for-changing-the-report-appearance)
- [Defining a custom report title](#defining-a-custom-report-title)
- [Defining a custom CSS file](#defining-a-custom-css-file)
- [Defining custom passed, skipped and failed colors](#defining-custom-passed-skipped-and-failed-colors)
- [Running the reporting goal directly via command line](#running-the-reporting-goal-directly-via-command-line)
- [Passing properties via command line](#passing-properties-via-command-line)
- [Passing custom parameters via command line](#passing-custom-parameters-via-command-line)
- [Example project](#example-project)
- [Appendix](#appendix)
- [Building](#building)
- [Generated pages](#generated-pages)
- [All Scenarios](#all-scenarios)
- [Scenario Sequence](#scenario-sequence)
- [Scenario Details](#scenario-details)
- [All Features](#all-features)
- [All Tags](#all-tags)
- [All Steps](#all-steps)
- [Scenario by Tag](#scenario-by-tag)
- [Scenario by Feature](#scenario-by-feature)
- [Scenario by Step](#scenario-by-step)
- [License](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
Expand All @@ -55,12 +50,13 @@

This plugin creates aggregated test reports from Cucumber compatible JSON files that are generated by [Cucumber BDD](https://github.com/cucumber), [Karate](https://github.com/intuit/karate) and other frameworks.

This project was created because
- other projects were using legacy technology or were not maintained
- other projects generate HTML code in Java making it hard to adapt
- the reporting generated from other plugins showed too much unneeded or even wrong information
- other projects' memory consumption when generating reports from large JSON files was too high
- other projects did not support new Cucumber features
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!

Expand Down Expand Up @@ -147,18 +143,22 @@ This points to the root directory of the generated Cluecumber HTML report.

## Optional Configuration Parameters

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

```xml
<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>
Expand All @@ -168,7 +168,7 @@ The property definitions above are shown in the report like this:

![custom parameters](documentation/img/custom_params.png)

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

Expand All @@ -193,7 +193,7 @@ The property definitions above are shown in the report like this:

![custom parameters](documentation/img/custom_params.png)

### skip
### Skip Report Generation

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

Expand All @@ -204,9 +204,9 @@ The `skip` property is used to skip the report generation. The default value is
</configuration>
```

### failScenariosOnPendingOrUndefinedSteps
### Fail Scenarios on Pending or Undefined Steps

This optional property can be set to `true` if you scenarios should be marked as `failed` when they contain `pending` or `skipped` 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`.

```xml
Expand All @@ -216,18 +216,52 @@ The default setting is `false`, meaning that those scenarios will be marked as `
</configuration>
```

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

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

## Optional Configuration Parameters for Changing the Report Appearance

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

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

This would lead to a report title like this:

![Custom Title](documentation/img/custom_title.png)

### 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:
```css
body {
background-color: dimgray;
background-color: black;
}

h3, h4 {
color: orange;
h3, h4, h5 {
color: white;
}
```

Expand All @@ -236,36 +270,42 @@ To use this files, specify it like so in your pom file or as a system property:
```xml
<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:

![Custom CSS](documentation/img/custom_css.png)

Likewise, if you want to hide elements from the report, e.g. the total time on the start page, you can also add this to the custom css like so:
Likewise, if you want to hide elements from the report, you can also add this to the custom css like so:

```css
[data-cluecumber-item="total-scenario-duration"] {
.some_element {
display: none;
}
```

### expandBeforeAfterHooks, expandStepHooks, expandDocStrings
### Defining custom passed, skipped and failed colors

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

```xml
<configuration>
<expandBeforeAfterHooks>true|false</expandBeforeAfterHooks>
<expandStepHooks>true|false</expandStepHooks>
<expandDocStrings>true|false</expandDocStrings>
<customStatusColorPassed>#00ff00</customStatusColorPassed>
<customStatusColorFailed>#ff0000</customStatusColorFailed>
<customStatusColorSkipped>#00ffff</customStatusColorSkipped>
...
</configuration>
</configuration>
```

The result of this customization is:

| Before | After |
|---|---|
| ![Chart Before](documentation/img/chart_before.png) | ![Chart After](documentation/img/chart_after.png) |

# 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.
Expand Down Expand Up @@ -342,59 +382,17 @@ It is available in [Maven central](https://search.maven.org/#search%7Cgav%7C1%7C

## Generated pages

### All Scenarios

This page shows an overview of all scenarios grouped by their status `passed`, `failed` or `skipped`:

![All Scenarios](documentation/img/AllScenarios.png)

### Scenario Sequence

This page shows an overview of all scenarios in running order including their individual status information:

![Scenario Sequence](documentation/img/ScenarioSequence.png)

### Scenario Details

This page shows all steps, hooks, stack traces and attachments of a single scenario:

![Scenario Details](documentation/img/ScenarioDetails.png)

### All Features

This page shows an overview of all features:

![All Features](documentation/img/AllFeatures.png)

### All Tags

This page shows an overview of all used tags in scenarios, features and example tables including their individual status information:

![All Tags](documentation/img/AllTags.png)

### All Steps

This page shows an overview of all steps in use including their individual status information:

![All Steps](documentation/img/AllSteps.png)

### Scenario by Tag

This page shows all scenarios including a specific tag:

![Scenarios by Tag](documentation/img/TagDetails.png)

### Scenario by Feature

This page shows all scenarios belonging to a specific feature:

![Scenarios by Feature](documentation/img/FeatureDetails.png)

### Scenario by Step

This page shows all scenarios that include a specific step:

![Scenarios by Step](documentation/img/StepDetails.png)
![Start Page](documentation/img/start_page.png)

* __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

Expand Down
2 changes: 1 addition & 1 deletion docs/css/cluecumber_custom.css → docs/css/cluecumber-additional.css
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
Copyright 2018 trivago N.V.
Copyright 2019 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.
Expand Down
24 changes: 24 additions & 0 deletions docs/css/cluecumber-custom.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@

.color-passed {
color: #28a745 !important;
}

.border-color-passed {
border: 2px solid #28a745 !important;
}

.color-failed {
color: #dc3545 !important;
}

.border-color-failed {
border: 2px solid #dc3545 !important;
}

.color-skipped {
color: #ffc107 !important;
}

.border-color-skipped {
border: 2px solid #ffc107 !important;
}
Loading

0 comments on commit f65e7fd

Please sign in to comment.