[Core] Warn when cucumber.options is used (#2685)

In #1779 we deprecated and removed cucumber.options. Unfortunately
there are a slew of outdated tutorials still in existence. And this
outdated knowledge creates a slow trickle of questions on
StackOverflow. It would be nice if we can stop this waste of everyone's
time.

Fixes: #2673

Author: mpkorstanje

CHANGELOG.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- [Core] Warn when `cucumber.options` is used ([#2685](https://github.com/cucumber/cucumber-jvm/pull/2685) M.P. Korstanje)
 
 ## [7.11.0] - 2023-01-12
 ### Added

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

@@ -118,6 +118,13 @@ public final class Constants {
      */
     public static final String OBJECT_FACTORY_PROPERTY_NAME = "cucumber.object-factory";
 
+    /**
+     * Property name formerly used to pass command line options to Cucumber:
+     * {@value} This property is no longer read by Cucumber. Please use any of
+     * the
+     */
+    static final String OPTIONS_PROPERTY_NAME = "cucumber.options";
+
     /**
      * Property name to enable plugins: {@value}
      * <p>

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

@@ -3,6 +3,8 @@
 import io.cucumber.core.exception.CucumberException;
 import io.cucumber.core.feature.FeatureWithLines;
 import io.cucumber.core.feature.GluePath;
+import io.cucumber.core.logging.Logger;
+import io.cucumber.core.logging.LoggerFactory;
 import io.cucumber.tagexpressions.TagExpressionParser;
 
 import java.nio.file.Path;
@@ -24,6 +26,7 @@
 import static io.cucumber.core.options.Constants.FILTER_TAGS_PROPERTY_NAME;
 import static io.cucumber.core.options.Constants.GLUE_PROPERTY_NAME;
 import static io.cucumber.core.options.Constants.OBJECT_FACTORY_PROPERTY_NAME;
+import static io.cucumber.core.options.Constants.OPTIONS_PROPERTY_NAME;
 import static io.cucumber.core.options.Constants.PLUGIN_PROPERTY_NAME;
 import static io.cucumber.core.options.Constants.PLUGIN_PUBLISH_ENABLED_PROPERTY_NAME;
 import static io.cucumber.core.options.Constants.PLUGIN_PUBLISH_QUIET_PROPERTY_NAME;
@@ -32,10 +35,13 @@
 import static io.cucumber.core.options.Constants.WIP_PROPERTY_NAME;
 import static io.cucumber.core.options.OptionsFileParser.parseFeatureWithLinesFile;
 import static java.util.Arrays.stream;
+import static java.util.function.Function.identity;
 import static java.util.stream.Collectors.toList;
 
 public final class CucumberPropertiesParser {
 
+    private static final Logger log = LoggerFactory.getLogger(CucumberPropertiesParser.class);
+
     public RuntimeOptionsBuilder parse(Map<String, String> properties) {
         return parse(properties::get);
     }
@@ -96,14 +102,19 @@ public RuntimeOptionsBuilder parse(CucumberPropertiesProvider properties) {
             ObjectFactoryParser::parseObjectFactory,
             builder::setObjectFactoryClass);
 
+        parse(properties,
+            OPTIONS_PROPERTY_NAME,
+            identity(),
+            warnWhenCucumberOptionsIsUsed());
+
         parseAll(properties,
             PLUGIN_PROPERTY_NAME,
-            splitAndMap(Function.identity()),
+            splitAndMap(identity()),
             builder::addPluginName);
 
         parse(properties,
             PLUGIN_PUBLISH_TOKEN_PROPERTY_NAME,
-            s -> s, // No validation - validated on server
+            identity(), // No validation - validated on server
             builder::setPublishToken);
 
         parse(properties,
@@ -129,6 +140,16 @@ public RuntimeOptionsBuilder parse(CucumberPropertiesProvider properties) {
         return builder;
     }
 
+    private static Consumer<String> warnWhenCucumberOptionsIsUsed() {
+        // Quite a few old blogs still recommend the use of cucumber.options
+        // This should take care of recurring question involving this property.
+        return commandLineOptions -> log.warn(() -> String.format("" +
+                "Passing commandline options via the property '%s' is no longer supported. " +
+                "Please use individual properties instead. " +
+                "See the java doc on %s for details.",
+            OPTIONS_PROPERTY_NAME, Constants.class.getName()));
+    }
+
     private <T> void parse(
             CucumberPropertiesProvider properties, String propertyName, Function<String, T> parser, Consumer<T> setter
     ) {

cucumber-core/src/test/java/io/cucumber/core/options/CucumberPropertiesParserTest.java

@@ -2,6 +2,8 @@
 
 import io.cucumber.core.backend.ObjectFactory;
 import io.cucumber.core.exception.CucumberException;
+import io.cucumber.core.logging.LogRecordListener;
+import io.cucumber.core.logging.WithLogRecordListener;
 import io.cucumber.core.order.StandardPickleOrders;
 import io.cucumber.core.snippets.SnippetType;
 import io.cucumber.tagexpressions.TagExpressionParser;
@@ -30,6 +32,7 @@
 import static org.junit.jupiter.api.Assertions.assertAll;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
+@WithLogRecordListener
 class CucumberPropertiesParserTest {
 
     private final CucumberPropertiesParser cucumberPropertiesParser = new CucumberPropertiesParser();
@@ -138,6 +141,16 @@ void should_parse_object_factory() {
         assertThat(options.getObjectFactoryClass(), equalTo(CustomObjectFactory.class));
     }
 
+    @Test
+    void should_warn_about_cucumber_options(LogRecordListener logRecordListener) {
+        properties.put(Constants.OPTIONS_PROPERTY_NAME, "--help");
+        cucumberPropertiesParser.parse(properties).build();
+        assertThat(logRecordListener.getLogRecords().get(0).getMessage(), equalTo("" +
+                "Passing commandline options via the property 'cucumber.options' is no longer supported. " +
+                "Please use individual properties instead. " +
+                "See the java doc on io.cucumber.core.options.Constants for details."));
+    }
+
     @Test
     void should_parse_plugin() {
         properties.put(Constants.PLUGIN_PROPERTY_NAME, "message:target/cucumber.ndjson, html:target/cucumber.html");