[Java, .Net] Support customizations (#409)

* Allows the title and icon in the html report to replaced with a custom title and icon.
* Supports replacing and extending the default javascript and css of the report.

Closes: #403

Co-authored-by: Gáspár Nagy <[email protected]>

Author: mpkorstanje

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+### Added
+- [.Net] Support customizations ([#409](https://github.com/cucumber/html-formatter/pull/409))
+- [Java] Support customizations ([#409](https://github.com/cucumber/html-formatter/pull/409))
+
 ### Changed
 - Upgrade `react-components` to [23.2.0](https://github.com/cucumber/react-components/releases/tag/v23.2.0)
 

Makefile

@@ -1,5 +1,5 @@
 javascript_source = $(wildcard javascript/src/*)
-assets = main.css main.js main.js.LICENSE.txt index.mustache.html
+assets = main.css main.js main.js.LICENSE.txt index.mustache.html icon.url
 ruby_assets = $(addprefix ruby/assets/,$(assets))
 java_assets = $(addprefix java/src/main/resources/io/cucumber/htmlformatter/,$(assets))
 dotnet_assets = $(addprefix dotnet/Cucumber.HtmlFormatter/Resources/,$(assets))
@@ -15,24 +15,28 @@ clean: ## Remove javascript built module and related artifacts from java and rub
 	rm -rf $(ruby_assets) $(java_assets) $(dotnet_assets) javascript/dist
 .PHONY: .clean
 
-ruby/assets/index.mustache.html: javascript/src/index.mustache.html
+ruby/assets/%: javascript/dist/src/%
 	cp $< $@
 
 ruby/assets/%: javascript/dist/%
 	cp $< $@
 
-java/src/main/resources/io/cucumber/htmlformatter/index.mustache.html: javascript/src/index.mustache.html
+java/src/main/resources/io/cucumber/htmlformatter/%: javascript/dist/src/%
 	cp $< $@
 
 java/src/main/resources/io/cucumber/htmlformatter/%: javascript/dist/%
 	cp $< $@
 
-dotnet/Cucumber.HtmlFormatter/Resources/index.mustache.html: javascript/src/index.mustache.html
+dotnet/Cucumber.HtmlFormatter/Resources/%: javascript/dist/src/%
 	cp $< $@
 
 dotnet/Cucumber.HtmlFormatter/Resources/%: javascript/dist/%
 	cp $< $@
 
+javascript/dist/src/index.mustache.html: javascript/dist/main.js
+
+javascript/dist/src/icon.url: javascript/dist/main.js
+
 javascript/dist/main.js.LICENSE.txt: javascript/dist/main.js
 
 javascript/dist/main.css: javascript/dist/main.js

README.md

@@ -10,6 +10,17 @@ This formatter is built into the following Cucumber implementations:
 * [cucumber-ruby](https://github.com/cucumber/cucumber-ruby/blob/main/lib/cucumber/formatter/html.rb)
 * [cucumber-jvm](https://github.com/cucumber/cucumber-jvm/blob/main/core/src/main/java/io/cucumber/core/plugin/HtmlFormatter.java)
 * [cucumber-js](https://github.com/cucumber/cucumber-js/blob/main/src/formatter/html_formatter.ts)
+* [Reqnroll](https://github.com/reqnroll/Reqnroll/blob/main/Reqnroll/Formatters/Html/HtmlFormatter.cs)
+
+## Customizations
+
+_Supported by: Java and .Net_
+
+The formatter can be configured with:
+ * A custom page title and icon
+ * Additional CSS to support [styling react components](https://github.com/cucumber/react-components?tab=readme-ov-file#styling).
+ * Additional Javascript for other customisations.
+ * The default Javascript and CSS can be replaced to support building custom react components. 
 
 ## Contributing
 

dotnet/Cucumber.HtmlFormatter/Cucumber.HtmlFormatter.snk renamed to dotnet/Cucumber.HtmlFormatter.snk

@@ -9,7 +9,7 @@
     <NoWarn>1591</NoWarn>
     <Deterministic Condition="'$(Configuration)' == 'Release'">false</Deterministic>
     <SignAssembly>true</SignAssembly>
-    <AssemblyOriginatorKeyFile>Cucumber.HtmlFormatter.snk</AssemblyOriginatorKeyFile>
+    <AssemblyOriginatorKeyFile>..\Cucumber.HtmlFormatter.snk</AssemblyOriginatorKeyFile>
   </PropertyGroup>
 
   <PropertyGroup Label="Version">

dotnet/Cucumber.HtmlFormatter/Cucumber.HtmlFormatter.csproj

@@ -0,0 +1,70 @@
+namespace Cucumber.HtmlFormatter;
+
+/// <summary>
+/// Settings for HTML report generation
+/// </summary>
+public class HtmlReportSettings
+{
+    private const string DEFAULT_TITLE = "Cucumber";
+    private string? _icon = null;
+
+    /// <summary>
+    /// Gets or sets the title of the HTML report.
+    /// Default is "Cucumber".
+    /// </summary>
+    public string Title { get; set; } = DEFAULT_TITLE;
+
+    /// <summary>
+    /// Gets or sets the icon for the HTML report.
+    /// Default is the Cucumber icon as a base64-encoded SVG.
+    /// </summary>
+    public string Icon
+    {
+        get => _icon ?? LoadDefaultIcon();
+        set => _icon = value;
+    }
+
+    /// <summary>
+    /// Gets or sets custom CSS to include in the HTML report.
+    /// Default is empty.
+    /// </summary>
+    public string CustomCss { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets custom Javascript to include after the main Javascript section of the HTML report.
+    /// Default is empty.
+    /// </summary>
+    public string CustomScript { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the function that loads the main Javascript resource for the HTML report.
+    /// This should only be customized if you use a custom node.js project to serve the HTML report,
+    /// for smaller customizations you can use the <see cref="CustomScript"/> and <see cref="CustomCss"/> property.
+    /// </summary>
+    public Func<string> JavascriptResourceLoader { get; set; }
+
+    /// <summary>
+    /// Gets or sets the function that loads the main CSS resource for the HTML report.
+    /// This should only be customized if you use a custom node.js project to serve the HTML report,
+    /// for smaller customizations you can use the <see cref="CustomScript"/> and <see cref="CustomCss"/> property.
+    /// </summary>
+    public Func<string> CssResourceLoader { get; set; }
+
+    /// <summary>
+    /// Creates a new instance of HtmlReportSettings with default values.
+    /// </summary>
+    public HtmlReportSettings()
+    {
+        JavascriptResourceLoader = LoadJavascriptResource;
+        CssResourceLoader = LoadCssResource;
+    }
+
+    private static string LoadDefaultIcon()
+        => MessagesToHtmlWriter.GetResource("icon.url");
+
+    private static string LoadJavascriptResource()
+        => MessagesToHtmlWriter.GetResource("main.js");
+
+    private static string LoadCssResource()
+        => MessagesToHtmlWriter.GetResource("main.css");
+}

dotnet/Cucumber.HtmlFormatter/HtmlReportSettings.cs

@@ -0,0 +1,2 @@
+using System.Runtime.CompilerServices;
+[assembly: InternalsVisibleTo("Cucumber.HtmlFormatterTest, PublicKey=00240000048000009400000006020000002400005253413100040000010001003d3d7a4a4bb40fd4ad4b18dea92bd57f04946bbce990a7e72a406f026c0af1544510e1069718f7bdc8134fca21b4fb61d8ff139af7c19f2d855a0bf7539667334371478c323ff84e91ccb6a5bc3027fea39ca84658087b7f7f76c30af7adacb315442a0cbec817b71017f363fc4d8a751b98b6e60b00149b08c84ca984ab5ddd")]

dotnet/Cucumber.HtmlFormatter/InternalsVisibleTo.cs

@@ -9,70 +9,91 @@ public class MessagesToHtmlWriter : IDisposable
     private readonly Action<StreamWriter, Envelope> _streamSerializer;
     private readonly string _template;
     private readonly JsonInHtmlWriter _jsonInHtmlWriter;
+    private readonly HtmlReportSettings _settings;
     private bool _streamClosed = false;
     private bool _preMessageWritten = false;
     private bool _firstMessageWritten = false;
     private bool _postMessageWritten = false;
     private readonly bool _isAsyncInitialized = false;
 
     [Obsolete("Cucumber.HtmlFormatter moving to async only operations. Please use the MessagesToHtmlWriter(Stream, Func<StreamWriter, Envelope, Task>) constructor", false)]
-    public MessagesToHtmlWriter(Stream stream, Action<StreamWriter, Envelope> streamSerializer) : this(new StreamWriter(stream), streamSerializer)
-    {
-    }
-    public MessagesToHtmlWriter(Stream stream, Func<StreamWriter, Envelope, Task> asyncStreamSerializer) : this(new StreamWriter(stream), asyncStreamSerializer) { }
+    public MessagesToHtmlWriter(Stream stream, Action<StreamWriter, Envelope> streamSerializer) 
+        : this(new StreamWriter(stream), streamSerializer) { }
+
+    public MessagesToHtmlWriter(Stream stream, Func<StreamWriter, Envelope, Task> asyncStreamSerializer, HtmlReportSettings? settings = null) 
+        : this(new StreamWriter(stream), asyncStreamSerializer, settings) { }
 
     [Obsolete("Cucumber.HtmlFormatter moving to async only operations. Please use the MessagesToHtmlWriter(StreamWriter, Func<StreamWriter, Envelope, Task>) constructor", false)]
     public MessagesToHtmlWriter(StreamWriter writer, Action<StreamWriter, Envelope> streamSerializer)
     {
-        this._writer = writer;
-        this._streamSerializer = streamSerializer;
+        _writer = writer;
+        _streamSerializer = streamSerializer;
+        _settings = new HtmlReportSettings();
         // Create async wrapper for sync serializer
-        this._asyncStreamSerializer = (w, e) =>
+        _asyncStreamSerializer = (w, e) =>
         {
             streamSerializer(w, e);
             return Task.CompletedTask;
         };
-        _template = GetResource("index.mustache.html");
+        _template = LoadTemplateResource();
         _jsonInHtmlWriter = new JsonInHtmlWriter(writer);
         _isAsyncInitialized = false;
     }
-    public MessagesToHtmlWriter(StreamWriter writer, Func<StreamWriter, Envelope, Task> asyncStreamSerializer)
+
+    public MessagesToHtmlWriter(StreamWriter writer, Func<StreamWriter, Envelope, Task> asyncStreamSerializer, HtmlReportSettings? settings = null)
     {
-        this._writer = writer;
-        this._asyncStreamSerializer = asyncStreamSerializer;
+        _writer = writer;
+        _asyncStreamSerializer = asyncStreamSerializer;
+        _settings = settings ?? new();
         // Create sync wrapper for async serializer (will block)
-        this._streamSerializer = (w, e) => asyncStreamSerializer(w, e).GetAwaiter().GetResult();
-        _template = GetResource("index.mustache.html");
+        _streamSerializer = (w, e) => asyncStreamSerializer(w, e).GetAwaiter().GetResult();
+        _template = LoadTemplateResource();
         _jsonInHtmlWriter = new JsonInHtmlWriter(writer);
         _isAsyncInitialized = true;
     }
 
     private void WritePreMessage()
     {
-        WriteTemplateBetween(_writer, _template, null, "{{css}}");
-        WriteResource(_writer, "main.css");
-        WriteTemplateBetween(_writer, _template, "{{css}}", "{{messages}}");
+        WriteTemplateBetween(_writer, _template, null, "{{title}}");
+        _writer.Write(_settings.Title);
+        WriteTemplateBetween(_writer, _template, "{{title}}", "{{icon}}");
+        _writer.Write(_settings.Icon);
+        WriteTemplateBetween(_writer, _template, "{{icon}}", "{{css}}");
+        _writer.Write(_settings.CssResourceLoader());
+        WriteTemplateBetween(_writer, _template, "{{css}}", "{{custom_css}}");
+        _writer.Write(_settings.CustomCss);
+        WriteTemplateBetween(_writer, _template, "{{custom_css}}", "{{messages}}");
     }
 
     private async Task WritePreMessageAsync()
     {
-        await WriteTemplateBetweenAsync(_writer, _template, null, "{{css}}");
-        await WriteResourceAsync(_writer, "main.css");
-        await WriteTemplateBetweenAsync(_writer, _template, "{{css}}", "{{messages}}");
+        await WriteTemplateBetweenAsync(_writer, _template, null, "{{title}}");
+        await _writer.WriteAsync(_settings.Title);
+        await WriteTemplateBetweenAsync(_writer, _template, "{{title}}", "{{icon}}");
+        await _writer.WriteAsync(_settings.Icon);
+        await WriteTemplateBetweenAsync(_writer, _template, "{{icon}}", "{{css}}");
+        await _writer.WriteAsync(_settings.CssResourceLoader());
+        await WriteTemplateBetweenAsync(_writer, _template, "{{css}}", "{{custom_css}}");
+        await _writer.WriteAsync(_settings.CustomCss);
+        await WriteTemplateBetweenAsync(_writer, _template, "{{custom_css}}", "{{messages}}");
     }
 
     private void WritePostMessage()
     {
         WriteTemplateBetween(_writer, _template, "{{messages}}", "{{script}}");
-        WriteResource(_writer, "main.js");
-        WriteTemplateBetween(_writer, _template, "{{script}}", null);
+        _writer.Write(_settings.JavascriptResourceLoader());
+        WriteTemplateBetween(_writer, _template, "{{script}}", "{{custom_script}}");
+        _writer.Write(_settings.CustomScript);
+        WriteTemplateBetween(_writer, _template, "{{custom_script}}", null);
     }
 
     private async Task WritePostMessageAsync()
     {
         await WriteTemplateBetweenAsync(_writer, _template, "{{messages}}", "{{script}}");
-        await WriteResourceAsync(_writer, "main.js");
-        await WriteTemplateBetweenAsync(_writer, _template, "{{script}}", null);
+        await _writer.WriteAsync(_settings.JavascriptResourceLoader());
+        await WriteTemplateBetweenAsync(_writer, _template, "{{script}}", "{{custom_script}}");
+        await _writer.WriteAsync(_settings.CustomScript);
+        await WriteTemplateBetweenAsync(_writer, _template, "{{custom_script}}", null);
     }
 
     public void Write(Envelope envelope)
@@ -186,18 +207,6 @@ public async Task DisposeAsync()
         }
     }
 
-    private void WriteResource(StreamWriter writer, string v)
-    {
-        var resource = GetResource(v);
-        writer.Write(resource);
-    }
-
-    private async Task WriteResourceAsync(StreamWriter writer, string v)
-    {
-        var resource = GetResource(v);
-        await writer.WriteAsync(resource);
-    }
-
     private void WriteTemplateBetween(StreamWriter writer, string template, string? begin, string? end)
     {
         CalculateBeginAndLength(template, begin, end, out var beginIndex, out var lengthToWrite);
@@ -217,7 +226,7 @@ private async Task WriteTemplateBetweenAsync(StreamWriter writer, string templat
         await writer.WriteAsync(template.Substring(beginIndex, lengthToWrite));
     }
 
-    private string GetResource(string name)
+    internal static string GetResource(string name)
     {
         var assembly = typeof(MessagesToHtmlWriter).Assembly;
         var resourceStream = assembly.GetManifestResourceStream("Cucumber.HtmlFormatter.Resources." + name);
@@ -226,4 +235,9 @@ private string GetResource(string name)
         var resource = new StreamReader(resourceStream).ReadToEnd();
         return resource;
     }
+
+    private static string LoadTemplateResource()
+    {
+        return GetResource("index.mustache.html");
+    }
 }

dotnet/Cucumber.HtmlFormatter/MessagesToHtmlWriter.cs

@@ -2,4 +2,5 @@
 *.html
 *.js
 *.css
-*.txt
+*.txt
+*.url

dotnet/Cucumber.HtmlFormatter/Resources/.gitignore

@@ -5,6 +5,8 @@
     <LangVersion>latest</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+    <SignAssembly>true</SignAssembly>
+    <AssemblyOriginatorKeyFile>..\Cucumber.HtmlFormatter.snk</AssemblyOriginatorKeyFile>
   </PropertyGroup>
 
   <ItemGroup>