Use a message based usage formatter (#3086)

Use a message based usage formatter.

The --plugin usage now produces a human readable report where for each step definition usage statistics are calculated. Individual duration for each step are also included.

```
Expression/Text                           Duration   Mean ±  Error Location                                                          
I have {int} cukes in my belly              0.002s 0.002s ± 0.000s io.cucumber.skeleton.StepDefinitions.I_have_cukes_in_my_belly(int)
  I have 42 cukes in my belly               0.002s                 src/test/resources/io/cucumber/skeleton/belly.feature:3           
a forgotten step, unused, but not unloved                          io.cucumber.skeleton.StepDefinitions.an_unused_step()             
  UNUSED                                                                                                                             
```

With this implementation any unused step definitions also automatically show up in the report as step definitions without steps. This also allow the report to be reused for the unused steps formatter.

```
1 unused step definition(s)

Location                                              Expression                                 
io.cucumber.skeleton.StepDefinitions.an_unused_step() # a forgotten step, unused, but not unloved
```
A `--plugin usage-json` was added to provide a json based report. This reports structure differs significantly from the original json output from the usage plugin.

Author: mpkorstanje

CHANGELOG.md

@@ -1,4 +1,4 @@
-~~# Changelog
+# Changelog
 
 All notable changes to the current version this project will be documented in
 this file. For previous versions see the [release-notes archive](release-notes).
@@ -13,8 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - [Core] Prefer URIs with authority ([#3098](https://github.com/cucumber/cucumber-jvm/pull/3098) M.P. Korstanje)
 
+### Added
+- [Core] Add a `UsageJsonFormatter`, use with `--plugin usage-json` ([#3086](https://github.com/cucumber/cucumber-jvm/pull/3086) M.P. Korstanje)
+
 ### Changed
 - [Core] Use a message based `TimeLineFormatter` ([#3095](https://github.com/cucumber/cucumber-jvm/pull/3095) M.P. Korstanje)
+- [Core] Use a message based `UsageFormatter` ([#3086](https://github.com/cucumber/cucumber-jvm/pull/3086) M.P. Korstanje)
+- [Core] Use a message based `UnusedFormatter` ([#3086](https://github.com/cucumber/cucumber-jvm/pull/3086) M.P. Korstanje)
+
 
 ## [7.30.0] - 2025-10-01
 ### Changed
@@ -579,4 +585,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [7.2.0]: https://github.com/cucumber/cucumber-jvm/compare/v7.1.0...v7.2.0
 [7.1.0]: https://github.com/cucumber/cucumber-jvm/compare/v7.0.0...v7.1.0
 [7.0.0]: https://github.com/cucumber/cucumber-jvm/compare/v7.0.0-RC1...v7.0.0
-[7.0.0-RC1]: https://github.com/cucumber/cucumber-jvm/compare/v6.11.0...v7.0.0-RC1~~
+[7.0.0-RC1]: https://github.com/cucumber/cucumber-jvm/compare/v6.11.0...v7.0.0-RC1

cucumber-bom/pom.xml

@@ -25,6 +25,7 @@
         <tag-expressions.version>8.0.0</tag-expressions.version>
         <teamcity-formatter.version>0.1.1</teamcity-formatter.version>
         <testng-xml-formatter.version>0.6.0</testng-xml-formatter.version>
+        <usage-formatter.version>0.1.0</usage-formatter.version>
     </properties>
 
     <dependencyManagement>
@@ -90,6 +91,11 @@
                 <artifactId>testng-xml-formatter</artifactId>
                 <version>${testng-xml-formatter.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.cucumber</groupId>
+                <artifactId>usage-formatter</artifactId>
+                <version>${usage-formatter.version}</version>
+            </dependency>
 
             <!-- Modules in cucumber-jvm -->
             <dependency>

cucumber-core/README.md

@@ -51,6 +51,7 @@ cucumber.glue=                  # comma separated package names.
   
 cucumber.plugin=                # comma separated plugin strings. 
                                 # example: pretty, json:path/to/report.json
+                                # example: com.example.MyCustomPlugin:path/to/report.xml
 
 cucumber.object-factory=        # object factory class name.
                                 # example: com.example.MyObjectFactory
@@ -104,9 +105,28 @@ The performance gain on real projects depends on the feature size.
 
 When not specified, the `RandomUuidGenerator` is used.
 
-## Plugin ##
+## Built in plugins ##
 
-By implementing the Plugin interface, classes can listen to execution events 
+Cucumber comes with several built-in plugins. See the configuration options or the CLIs `--help` command for guidance on
+activating them.
+
+* [html](https://github.com/cucumber/html-formatter): Renders a html report of the text execution
+* [json](https://github.com/cucumber/cucumber-json-formatter): Renders a json report of the text execution. In maintenance mode.
+* [junit](https://github.com/cucumber/junit-xml-formatter): Renders a JUnit xml report of the text execution.
+* [progress](https://github.com/cucumber/pretty-formatter): Renders sequence of dots indicating test execution progress.
+* [message](https://github.com/cucumber/messages): Logs cucumbers execution as a stream of json messages.
+* rerun: Creates a file with scenarios that should be rerun.
+* [summary](https://github.com/cucumber/pretty-formatter): Renders summary report of the test execution.
+* [testng](https://github.com/cucumber/testng-xml-formatter): Renders a TestNG xml report of the text execution.
+* timeline: Renders a timeline of the test execution.
+* [unused](https://github.com/cucumber/usage-formatter): Renders a plain text report of unused step definitions.
+* [usage](https://github.com/cucumber/usage-formatter): Renders a plain text report of step definition usage statistics.
+* [usage-json](https://github.com/cucumber/usage-formatter): Renders a json text report of step definition usage statistics.
+* [teamcity](https://github.com/cucumber/teamcity-formatter/):  Interspaces Cucumbers output with TeamCity Service Messages
+
+## Custom Plugins ##
+
+By implementing the `Plugin` interface, classes can listen to execution events 
 inside Cucumber JVM. Consider using a Plugin when creating test execution reports.
 
 ## FileSystem ##

cucumber-core/pom.xml

@@ -14,6 +14,7 @@
     <properties>
         <project.Automatic-Module-Name>io.cucumber.core</project.Automatic-Module-Name>
         <apiguardian-api.version>1.1.2</apiguardian-api.version>
+        <assertj.version>3.27.6</assertj.version>
         <jackson.version>2.20.0</jackson.version>
         <jsoup.version>1.21.2</jsoup.version>
         <junit-jupiter.version>5.14.0</junit-jupiter.version>
@@ -48,6 +49,13 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
+            <dependency>
+                <groupId>org.assertj</groupId>
+                <artifactId>assertj-bom</artifactId>
+                <version>${assertj.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -76,6 +84,10 @@
             <groupId>io.cucumber</groupId>
             <artifactId>testng-xml-formatter</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.cucumber</groupId>
+            <artifactId>usage-formatter</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.cucumber</groupId>
             <artifactId>tag-expressions</artifactId>
@@ -188,12 +200,25 @@
             <scope>test</scope>
         </dependency>
 
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest</artifactId>
+            <version>${hamcrest.version}</version>
+            <scope>test</scope>
+        </dependency>
+
         <dependency>
             <groupId>org.skyscreamer</groupId>
             <artifactId>jsonassert</artifactId>
             <version>1.5.3</version>
             <scope>test</scope>
         </dependency>
+
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

cucumber-core/src/main/java/io/cucumber/core/options/PluginOption.java

@@ -16,6 +16,7 @@
 import io.cucumber.core.plugin.TimelineFormatter;
 import io.cucumber.core.plugin.UnusedStepsSummaryPrinter;
 import io.cucumber.core.plugin.UsageFormatter;
+import io.cucumber.core.plugin.UsageJsonFormatter;
 import io.cucumber.plugin.ConcurrentEventListener;
 import io.cucumber.plugin.EventListener;
 import io.cucumber.plugin.Plugin;
@@ -55,6 +56,7 @@ public class PluginOption implements Options.Plugin {
         plugins.put("timeline", TimelineFormatter.class);
         plugins.put("unused", UnusedStepsSummaryPrinter.class);
         plugins.put("usage", UsageFormatter.class);
+        plugins.put("usage-json", UsageJsonFormatter.class);
         plugins.put("teamcity", TeamCityPlugin.class);
         PLUGIN_CLASSES = unmodifiableMap(plugins);
     }

cucumber-core/src/main/java/io/cucumber/core/plugin/UnusedStepsSummaryPrinter.java

@@ -1,80 +1,54 @@
 package io.cucumber.core.plugin;
 
+import io.cucumber.messages.types.Envelope;
 import io.cucumber.plugin.ColorAware;
 import io.cucumber.plugin.ConcurrentEventListener;
 import io.cucumber.plugin.event.EventPublisher;
-import io.cucumber.plugin.event.Status;
-import io.cucumber.plugin.event.StepDefinedEvent;
-import io.cucumber.plugin.event.TestRunFinished;
-import io.cucumber.plugin.event.TestStepFinished;
+import io.cucumber.usageformatter.MessagesToUsageWriter;
+import io.cucumber.usageformatter.UnusedReportSerializer;
 
+import java.io.IOException;
 import java.io.OutputStream;
-import java.util.Map;
-import java.util.Map.Entry;
-import java.util.Set;
-import java.util.TreeMap;
-import java.util.TreeSet;
-
-import static io.cucumber.core.plugin.Formats.ansi;
-import static io.cucumber.core.plugin.Formats.monochrome;
-import static java.util.Locale.ROOT;
 
+/**
+ * Formatter to measure performance of steps. Includes average and median step
+ * duration.
+ */
 public final class UnusedStepsSummaryPrinter implements ColorAware, ConcurrentEventListener {
 
-    private final Map<String, String> registeredSteps = new TreeMap<>();
-    private final Set<String> usedSteps = new TreeSet<>();
-    private final UTF8PrintWriter out;
-    private Formats formats = ansi();
+    private final MessagesToUsageWriter writer;
 
+    @SuppressWarnings("WeakerAccess") // Used by PluginFactory
     public UnusedStepsSummaryPrinter(OutputStream out) {
-        this.out = new UTF8PrintWriter(out);
+        this.writer = MessagesToUsageWriter.builder(new UnusedReportSerializer())
+                .build(out);
     }
 
     @Override
     public void setEventPublisher(EventPublisher publisher) {
-        // Record any steps registered
-        publisher.registerHandlerFor(StepDefinedEvent.class, this::handleStepDefinedEvent);
-        // Remove any steps that run
-        publisher.registerHandlerFor(TestStepFinished.class, this::handleTestStepFinished);
-        // Print summary when done
-        publisher.registerHandlerFor(TestRunFinished.class, event -> finishReport());
-    }
-
-    private void handleStepDefinedEvent(StepDefinedEvent event) {
-        registeredSteps.put(event.getStepDefinition().getLocation(), event.getStepDefinition().getPattern());
-    }
-
-    private void handleTestStepFinished(TestStepFinished event) {
-        String codeLocation = event.getTestStep().getCodeLocation();
-        if (codeLocation != null) {
-            usedSteps.add(codeLocation);
-        }
+        publisher.registerHandlerFor(Envelope.class, this::write);
     }
 
-    private void finishReport() {
-        // Remove all used steps
-        usedSteps.forEach(registeredSteps::remove);
-
-        if (registeredSteps.isEmpty()) {
-            return;
+    private void write(Envelope event) {
+        try {
+            writer.write(event);
+        } catch (IOException e) {
+            throw new IllegalStateException(e);
         }
 
-        Format format = formats.get(Status.UNUSED.name().toLowerCase(ROOT));
-        out.println(format.text(registeredSteps.size() + " Unused steps:"));
-
-        // Output results when done
-        for (Entry<String, String> entry : registeredSteps.entrySet()) {
-            String location = entry.getKey();
-            String pattern = entry.getValue();
-            out.println(format.text(location) + " # " + pattern);
+        // TODO: Plugins should implement the closable interface
+        // and be closed by Cucumber
+        if (event.getTestRunFinished().isPresent()) {
+            try {
+                writer.close();
+            } catch (IOException e) {
+                throw new IllegalStateException(e);
+            }
         }
-
-        out.close();
     }
 
     @Override
     public void setMonochrome(boolean monochrome) {
-        formats = monochrome ? monochrome() : ansi();
+        // no-op, no colors printed
     }
-
 }