[JUnit Platform] Deprecate @cucumber in favour of @suite

CHANGELOG.md

@@ -33,6 +33,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 * [Core] Pretty formatter to print step DataTables ([#2330](https://github.com/cucumber/cucumber-jvm/pull/2330) Arty Sidorenko)
 
 ### Deprecated
+* [JUnit Platform] Deprecated `@Cucumber` in favour of `@Suite` ([#2362](https://github.com/cucumber/cucumber-jvm/pull/2362) M.P. Korstanje)
 
 ### Removed
 * [Core] Removed `--strict` and `--no-strict` options ([#1788](https://github.com/cucumber/cucumber-jvm/issues/1788) M.P. Korstanje)

examples/calculator-java-junit5/pom.xml

@@ -27,6 +27,11 @@
             <artifactId>cucumber-junit-platform-engine</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.junit.platform</groupId>
+            <artifactId>junit-platform-suite</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-api</artifactId>
@@ -47,6 +52,18 @@
 
     <build>
         <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <!-- Work around. Surefire does not include enough information to disambiguate between different
+                         examples. -->
+                    <configurationParameters>
+                        cucumber.junit-platform.naming-strategy=long
+                    </configurationParameters>
+                </configuration>
+            </plugin>
+
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-antrun-plugin</artifactId>

examples/calculator-java-junit5/src/test/java/io/cucumber/examples/calculator/RunCucumberTest.java

@@ -1,13 +1,18 @@
 package io.cucumber.examples.calculator;
 
-import io.cucumber.junit.platform.engine.Cucumber;
+import org.junit.platform.suite.api.ConfigurationParameter;
+import org.junit.platform.suite.api.SelectClasspathResource;
+import org.junit.platform.suite.api.Suite;
+
+import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;
 
 /**
  * Work around. Surefire does not use JUnits Test Engine discovery
  * functionality. Alternatively execute the the
  * org.junit.platform.console.ConsoleLauncher with the maven-antrun-plugin.
  */
-@Cucumber
+@Suite
+@SelectClasspathResource("io/cucumber/examples/calculator")
+@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "io.cucumber.examples.calculator")
 public class RunCucumberTest {
-
 }

junit-platform-engine/README.md

@@ -22,27 +22,16 @@ and execute Cucumber scenarios.
 Maven Surefire and Gradle do not yet support discovery of non-class based tests
 (see: [gradle/#4773](https://github.com/gradle/gradle/issues/4773),
 [SUREFIRE-1724](https://issues.apache.org/jira/browse/SUREFIRE-1724)). As a
-workaround you can either use the `@Cucumber` annotation or the JUnit Platform
-Console Launcher.
+workaround you can either use the
+[JUnit Platform Suite Engine](https://junit.org/junit5/docs/current/user-guide/#junit-platform-suite-engine) 
+or the [JUnit Platform Console Launcher](https://junit.org/junit5/docs/current/user-guide/#running-tests-console-launcher).
 
-### Use the @Cucumber annotation ###
+To improve the readability of the reports provide the
+`cucumber.junit-platform.naming-strategy=long` configuration parameter.
 
-Cucumber will scan the package of a class annotated with `@Cucumber` for feature
-files.  
+### Use the @Suite annotation ###
 
-To use this feature, add the `@Cucumber` annotation to the test runner. Doing so
-will make Cucumber run the feature files in the package containing the test
-runner.
-
-```java
-package com.example.app;
-
-import io.cucumber.junit.platform.engine.Cucumber;
-
-@Cucumber
-public class RunCucumberTest {
-}
-```
+See [Suites with different configurations](#suites-with-different-configurations).
 
 ### Use the JUnit Console Launcher ###
 
@@ -128,6 +117,39 @@ tasks {
 }
 ```
 
+## Suites with different configurations
+
+The JUnit Platform Suite Engine can be used to run Cucumber multiple times with
+different configurations. Add the `junit-platform-suite` dependency:
+
+```xml
+<dependency>
+   <groupId>org.junit.platform</groupId>
+   <artifactId>junit-platform-suite</artifactId>
+   <version>${junit-platform.version}</version>
+   <scope>test</scope>
+</dependency>
+```
+
+Then define suites as needed:
+
+```java
+package com.example;
+
+import org.junit.platform.suite.api.ConfigurationParameter;
+import org.junit.platform.suite.api.SelectClasspathResource;
+import org.junit.platform.suite.api.Suite;
+
+import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;
+
+@Suite
+@SelectClasspathResource("com/example")
+@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "com.example")
+public class RunCucumberTest {
+}
+```
+
+
 ## Parallel execution ## 
 
 By default, Cucumber runs tests sequentially in a single thread. Running  tests

junit-platform-engine/src/main/java/io/cucumber/junit/platform/engine/Constants.java

@@ -1,6 +1,7 @@
 package io.cucumber.junit.platform.engine;
 
 import org.apiguardian.api.API;
+import org.apiguardian.api.API.Status;
 import org.junit.platform.engine.support.hierarchical.DefaultParallelExecutionConfigurationStrategy;
 import org.junit.platform.engine.support.hierarchical.ParallelExecutionConfigurationStrategy;
 
@@ -85,6 +86,7 @@ public final class Constants {
      * This is useful for tools that only report the test name such as Maven and
      * Gradle.
      */
+    @API(status = Status.EXPERIMENTAL, since = "7.0.0")
     public static final String JUNIT_PLATFORM_NAMING_STRATEGY_PROPERTY_NAME = "cucumber.junit-platform.naming-strategy";
 
     /**

junit-platform-engine/src/main/java/io/cucumber/junit/platform/engine/Cucumber.java

@@ -1,6 +1,7 @@
 package io.cucumber.junit.platform.engine;
 
 import org.apiguardian.api.API;
+import org.apiguardian.api.API.Status;
 import org.junit.platform.commons.annotation.Testable;
 
 import java.lang.annotation.ElementType;
@@ -12,21 +13,37 @@
  * Test discovery annotation. Marks the package of the annotated class for test
  * discovery.
  * <p>
- * Some build tools do not support the
+ * Maven and Gradle do not support the
  * {@link org.junit.platform.engine.discovery.DiscoverySelectors} used by
- * Cucumber. As a work around Cucumber will scan the package of the annotated
+ * Cucumber. As a workaround Cucumber will scan the package of the annotated
  * class for feature files and execute them.
  * <p>
  * Note about Testable: While this class is annotated with @Testable the
  * recommended way for IDEs and other tooling use the selectors implemented by
  * Cucumber to discover feature files.
+ * <p>
+ * DEPRECATED: Please use the JUnit Platform Suite to run Cucumber in
+ * combination with Surefire or Gradle. E.g: <code><pre>{@code
+ *  package com.example;
+ *
+ *  import org.junit.platform.suite.api.ConfigurationParameter;
+ *  import org.junit.platform.suite.api.SelectClasspathResource;
+ *  import org.junit.platform.suite.api.Suite;
  *
- * @see CucumberTestEngine
+ * import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;
+ *  &#64;Suite
+ *  &#64;SelectClasspathResource("com/example")
+ *  &#64;ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "com.example")
+ *  public class RunCucumberTest {
+ *  }
+ * }</pre></code> @see CucumberTestEngine @deprecated Please use the JUnit
+ * Platform Suite.
  */
-@API(status = API.Status.STABLE)
+@API(status = Status.DEPRECATED)
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Testable
+@Deprecated
 public @interface Cucumber {
 
 }

pom.xml

@@ -35,8 +35,8 @@
 
         <!--Test Dependencies-->
         <junit.version>4.13.2</junit.version>
-        <junit-jupiter.version>5.7.2</junit-jupiter.version>
-        <junit-platform.version>1.7.2</junit-platform.version>
+        <junit-jupiter.version>5.8.0-M1</junit-jupiter.version>
+        <junit-platform.version>1.8.0-M1</junit-platform.version>
         <hamcrest.version>2.2</hamcrest.version>
         <mockito.version>3.11.2</mockito.version>
         <!--Maven plugins-->
@@ -210,6 +210,11 @@
                 <artifactId>junit-platform-testkit</artifactId>
                 <version>${junit-platform.version}</version>
             </dependency>
+            <dependency>
+                <groupId>org.junit.platform</groupId>
+                <artifactId>junit-platform-suite</artifactId>
+                <version>${junit-platform.version}</version>
+            </dependency>
             <dependency>
                 <groupId>org.mockito</groupId>
                 <artifactId>mockito-junit-jupiter</artifactId>