3.7.0 (#345)

* wip - custom favicon

* create img path

* default favicon works

* custom favicon definition

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 Back to [Readme](README.md).
 
+## [3.7.0] - 2024-07-09
+
+### Added
+
+* Custom favicon definition through property (#340)
+
 ## [3.6.3] - 2024-06-10
 
 ### Changed
@@ -877,6 +883,8 @@ the core component is now the reporting engine that is the base for other forms
 
 Initial project version on GitHub and Maven Central.
 
+[3.7.0]: https://github.com/trivago/cluecumber-report-plugin/tree/v3.7.0
+
 [3.6.3]: https://github.com/trivago/cluecumber-report-plugin/tree/v3.6.3
 
 [3.6.2]: https://github.com/trivago/cluecumber-report-plugin/tree/v3.6.2

README.md

@@ -15,6 +15,11 @@ Cluecumber comes in two flavors:
 * [__Cluecumber Core__](core) -  generates reports from Java code
 * [__Cluecumber Maven__](maven) - generates reports from Maven
 
+The look can be adjusted by setting
+* optional custom CSS
+* optional custom favicon
+* Custom parameters
+
 ![Cluecumber animation](documentation/img/cluecumber.gif)
 
 A fully generated example report can be [viewed here](https://softwaretester.blog/cluecumber)!

core/README.md

@@ -30,6 +30,7 @@ _Clear and concise JVM reporting for the Cucumber BDD JSON format_
   - [Defining the report start page](#defining-the-report-start-page)
   - [Defining a custom report title](#defining-a-custom-report-title)
   - [Defining a custom CSS file](#defining-a-custom-css-file)
+  - [Defining a custom favicon](#defining-a-custom-favicon)
   - [Defining custom passed, skipped and failed colors](#defining-custom-passed-skipped-and-failed-colors)
   - [Enabling a compact view of multiple runs of the same scenarios](#enabling-a-compact-view-of-multiple-runs-of-the-same-scenarios)
 - [Appendix](#appendix)
@@ -345,6 +346,20 @@ Likewise, if you want to hide elements from the report, you can also add this to
 }
 ```
 
+
+## Defining a custom favicon
+
+The favicon is displayed in the browser tab and can be customized by setting the `customFavicon` property. This must be
+a png file of size 16x16 or 32x32 pixels
+
+![Custom Favicon](../documentation/img/custom_favicon.png)
+
+```java
+new CluecumberCore.Builder()
+        .setCustomFavicon("custom/favicon.png")
+        .build().generateReports(jsonDirectory, reportDirectory);
+```
+
 ## 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

core/pom.xml

@@ -6,13 +6,13 @@
     <modelVersion>4.0.0</modelVersion>
 
     <artifactId>cluecumber-core</artifactId>
-    <version>3.6.3</version>
+    <version>3.7.0</version>
     <packaging>jar</packaging>
 
     <parent>
         <artifactId>cluecumber-parent</artifactId>
         <groupId>com.trivago.rta</groupId>
-        <version>3.6.3</version>
+        <version>3.7.0</version>
     </parent>
 
     <name>Cluecumber Core</name>

core/src/main/java/com/trivago/cluecumber/core/CluecumberCore.java

@@ -32,12 +32,14 @@ public class CluecumberCore {
 
     /**
      * The constructor for the Cluecumber core.
+     *
      * @param builder The builder instance.
      * @throws CluecumberException Thrown in case of any error.
      */
     private CluecumberCore(Builder builder) throws CluecumberException {
         cluecumberEngine = DaggerCluecumberCoreGraph.create().getCluecumberEngine();
         cluecumberEngine.setCustomCssFile(builder.customCssFile);
+        cluecumberEngine.setCustomFavicon(builder.customFavicon);
         cluecumberEngine.setCustomNavigationLinks(builder.customNavigationLinks);
         cluecumberEngine.setCustomPageTitle(builder.customPageTitle);
         cluecumberEngine.setCustomParameters(builder.customParameters);
@@ -75,6 +77,7 @@ public void generateReports(final String jsonDirectory, final String reportDirec
      */
     public static class Builder {
         private String customCssFile;
+        private String customFavicon;
         private LinkedHashMap<String, String> customNavigationLinks;
         private String customPageTitle;
         private LinkedHashMap<String, String> customParameters;
@@ -116,6 +119,17 @@ public Builder setCustomCssFile(final String customCssFile) {
             return this;
         }
 
+        /**
+         * Custom favicon to display in the browser tab.
+         *
+         * @param customFavicon The path to a favicon png file.
+         * @return The {@link Builder}.
+         */
+        public Builder setCustomFaviconFile(final String customFavicon) {
+            this.customFavicon = customFavicon;
+            return this;
+        }
+
         /**
          * Custom navigation links to display at the end of the default navigation.
          *

engine/README.md

@@ -4,5 +4,4 @@ This is the main component that creates the reports; used by [Cluecumber Core](.
 and [Cluecumber Maven](../maven).
 
 __Note:__ This is not intended to be used as a standalone dependency. Instead, use [Cluecumber Core](../core) when
-generating reports
-from code!
+generating reports from code!

engine/pom.xml

@@ -8,11 +8,11 @@
     <parent>
         <artifactId>cluecumber-parent</artifactId>
         <groupId>com.trivago.rta</groupId>
-        <version>3.6.3</version>
+        <version>3.7.0</version>
     </parent>
 
     <artifactId>cluecumber-engine</artifactId>
-    <version>3.6.3</version>
+    <version>3.7.0</version>
     <packaging>jar</packaging>
 
     <name>Cluecumber Engine</name>

engine/src/main/java/com/trivago/cluecumber/engine/CluecumberEngine.java

@@ -284,6 +284,13 @@ public void setCustomCssFile(final String customCss) throws MissingFileException
         propertyManager.setCustomCssFile(customCss);
     }
 
+    public void setCustomFavicon(final String customFavicon) throws MissingFileException {
+        if (customFavicon == null) {
+            return;
+        }
+        propertyManager.setCustomFaviconFile(customFavicon);
+    }
+
     /**
      * Set a custom color for passed scenarios.
      *

engine/src/main/java/com/trivago/cluecumber/engine/properties/PropertyManager.java

@@ -62,6 +62,7 @@ public class PropertyManager {
     private boolean groupPreviousScenarioRuns = false;
     private boolean expandPreviousScenarioRuns = false;
     private String customCssFile;
+    private String customFaviconFile;
     private String customParametersFile;
     private Settings.CustomParamDisplayMode customParametersDisplayMode =
             Settings.CustomParamDisplayMode.ALL_PAGES;
@@ -128,7 +129,8 @@ public String getGeneratedHtmlReportDirectory() {
      * @param generatedHtmlReportDirectory The path.
      * @throws WrongOrMissingPropertyException Thrown on any error.
      */
-    public void setGeneratedHtmlReportDirectory(final String generatedHtmlReportDirectory) throws WrongOrMissingPropertyException {
+    public void setGeneratedHtmlReportDirectory(final String generatedHtmlReportDirectory)
+            throws WrongOrMissingPropertyException {
         if (!isSet(generatedHtmlReportDirectory)) {
             throw new WrongOrMissingPropertyException("generatedHtmlReportDirectory");
         }
@@ -197,7 +199,8 @@ public Settings.CustomParamDisplayMode getCustomParametersDisplayMode() {
      */
     public void setCustomParametersDisplayMode(String customParametersDisplayMode) {
         try {
-            this.customParametersDisplayMode = Settings.CustomParamDisplayMode.valueOf(customParametersDisplayMode.toUpperCase());
+            this.customParametersDisplayMode =
+                    Settings.CustomParamDisplayMode.valueOf(customParametersDisplayMode.toUpperCase());
         } catch (IllegalArgumentException e) {
             logger.warn("Unknown setting for custom parameter page(s): '" + customParametersDisplayMode +
                         "'. Must be one of " + Arrays.toString(Settings.CustomParamDisplayMode.values()));
@@ -422,6 +425,31 @@ public void setCustomCssFile(final String customCssFile) throws MissingFileExcep
         }
     }
 
+    /**
+     * Get the custom favicon file path.
+     *
+     * @return The path.
+     */
+    public String getCustomFaviconFile() {
+        return customFaviconFile;
+    }
+
+    /**
+     * Set the custom favicon file path.
+     *
+     * @param customFaviconFile The path.
+     * @throws MissingFileException Thrown if the file is not found.
+     */
+    public void setCustomFaviconFile(final String customFaviconFile) throws MissingFileException {
+        this.customFaviconFile = customFaviconFile;
+        if (!isSet(customFaviconFile)) {
+            return;
+        }
+        if (!fileIO.isExistingFile(customFaviconFile)) {
+            throw new MissingFileException(customFaviconFile + " (customFaviconFile)");
+        }
+    }
+
     /**
      * Get the custom hex color for passed elements.
      *
@@ -523,7 +551,9 @@ public void logProperties() {
                 logger.logInfoSeparator();
             }
             customParameters.entrySet().stream().map(entry -> "- custom parameter                 : " +
-                                                              entry.getKey() + " -> " + entry.getValue()).forEach(logString -> logger.info(logString, DEFAULT));
+                                                              entry.getKey() + " -> " +
+                                                              entry.getValue()).forEach(
+                    logString -> logger.info(logString, DEFAULT));
         }
 
         logger.logInfoSeparator(DEFAULT);
@@ -548,22 +578,37 @@ public void logProperties() {
                     logString -> logger.info(logString, DEFAULT));
         }
 
-
         if (isSet(customCssFile)) {
             logger.info("- custom CSS file                  : " + customCssFile, DEFAULT);
         }
+        if (isSet(customFaviconFile)) {
+            logger.info("- custom favicon file              : " + customFaviconFile, DEFAULT);
+        }
 
         logger.info("- colors (passed, failed, skipped) : " +
                     customStatusColorPassed + ", " + customStatusColorFailed + ", " + customStatusColorSkipped, DEFAULT);
-
         logger.logInfoSeparator(DEFAULT);
     }
 
+    /**
+     * Check if a string is set.
+     *
+     * @param string The string to check.
+     * @return true if the string is set.
+     */
     private boolean isSet(final String string) {
         return string != null && !string.trim().isEmpty();
     }
 
-    private void checkHexColorValidity(String color, String colorPropertyName) throws WrongOrMissingPropertyException {
+    /**
+     * Check if a hex color is valid.
+     *
+     * @param color             The color string.
+     * @param colorPropertyName The name of the color property.
+     * @throws WrongOrMissingPropertyException Thrown if the color is invalid.
+     */
+    private void checkHexColorValidity(String color, String colorPropertyName)
+            throws WrongOrMissingPropertyException {
         if (!Pattern.compile(COLOR_PATTERN).matcher(color).matches()) {
             throw new WrongOrMissingPropertyException(colorPropertyName);
         }
@@ -587,7 +632,8 @@ public void setStartPage(final String startPage) {
         try {
             this.startPage = Settings.StartPage.valueOf(startPage.toUpperCase());
         } catch (IllegalArgumentException e) {
-            logger.warn("Unknown start page '" + startPage + "'. Must be one of " + Arrays.toString(Settings.StartPage.values()));
+            logger.warn("Unknown start page '" + startPage + "'. Must be one of " +
+                        Arrays.toString(Settings.StartPage.values()));
             this.startPage = Settings.StartPage.ALL_SCENARIOS;
         }
     }

engine/src/main/java/com/trivago/cluecumber/engine/rendering/ReportGenerator.java

@@ -92,10 +92,11 @@ public void generateReport(final AllScenariosPageCollection allScenariosPageColl
         createDirectories(reportDirectory);
         copyStaticReportAssets(reportDirectory);
         copyCustomCss(reportDirectory);
+        copyCustomFavicon(reportDirectory);
 
         boolean redirectToFirstScenarioPage =
                 propertyManager.getStartPage() == Settings.StartPage.ALL_SCENARIOS &&
-                        allScenariosPageCollection.getTotalNumberOfScenarios() == 1;
+                allScenariosPageCollection.getTotalNumberOfScenarios() == 1;
 
         generateStartPage(redirectToFirstScenarioPage);
         for (PageVisitor visitor : visitors) {
@@ -148,12 +149,27 @@ private void copyCustomCss(final String reportDirectory) throws CluecumberExcept
         ), reportDirectory + "/css/cluecumber-custom.css");
     }
 
+    /**
+     * Copy custom favicon to the specified target directory.
+     */
+    private void copyCustomFavicon(final String reportDirectory) throws CluecumberException {
+        String customFavicon = propertyManager.getCustomFaviconFile();
+        if (customFavicon != null && !customFavicon.isEmpty()) {
+            fileSystemManager.copyResource(customFavicon, reportDirectory + "/img/favicon.png");
+        } else {
+            copyFileFromJarToReportDirectory("/img/favicon.png");
+        }
+    }
+
     /**
      * Copy all needed static report assets to the specified target directory.
      *
      * @throws CluecumberException The {@link CluecumberException}.
      */
     private void copyStaticReportAssets(final String reportDirectory) throws CluecumberException {
+        // Copy image resources
+        fileSystemManager.createDirectory(reportDirectory + "/img");
+
         // Copy CSS resources
         fileSystemManager.createDirectory(reportDirectory + "/css");
         copyFileFromJarToReportDirectory("/css/bootstrap.min.css");

engine/src/main/resources/template/macros/page.ftl

@@ -35,6 +35,7 @@ limitations under the License.
     <base href="${base}">
     <head title="${title}">
         <title>${title}</title>
+        <link rel="icon" href="img/favicon.png" type="image/png" />
         <#include "../snippets/common_headers.ftl">
         <#include "../snippets/css.ftl">
         <#include "../snippets/js.ftl">

engine/src/test/java/com/trivago/cluecumber/engine/rendering/ReportGeneratorTest.java

@@ -92,7 +92,7 @@ public void fileOperationsTest() throws CluecumberException {
 
         reportGenerator.generateReport(allScenariosPageCollection);
 
-        verify(fileSystemManager, times(8)).createDirectory(anyString());
-        verify(fileSystemManager, times(17)).copyResourceFromJar(anyString(), anyString());
+        verify(fileSystemManager, times(9)).createDirectory(anyString());
+        verify(fileSystemManager, times(18)).copyResourceFromJar(anyString(), anyString());
     }
 }

examples/maven-example/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>blog.softwaretester</groupId>
     <artifactId>maven-example</artifactId>
-    <version>3.6.3</version>
+    <version>3.7.0</version>
     <packaging>pom</packaging>
 
     <properties>
@@ -74,6 +74,9 @@
                     <!-- Optional custom CSS for custom styling -->
                     <!-- <customCss>custom/custom.css</customCss> -->
 
+                    <!-- Optional custom favicon (needs to be a png) -->
+                    <!-- <customFavicon>custom/favicon.png</customFavicon> -->
+
                     <!-- Optional properties to expand scenario hooks, step hooks, doc strings, attachments and step outputs when scenario details are shown (default: false) -->
                     <expandSubSections>false</expandSubSections>
                     <expandBeforeAfterHooks>true</expandBeforeAfterHooks>

makefile

@@ -1,8 +1,8 @@
 build-and-test:
 	mvn clean install
-	mvn verify -f=examples/maven-example -e
+	(cd examples/maven-example && mvn verify -e)
 	open examples/maven-example/target/cluecumber-report/pages/scenario-detail/scenario_1.html
 
 show-versions:
-	mvn versions:display-dependency-updates
-	mvn versions:display-plugin-updates
+	mvn versions:display-dependency-updates -U -ntp
+	mvn versions:display-plugin-updates -U -ntp