Deprecate AfterConfiguration hook (#1570)

aurelien-reeves · web-flow · commit 42f325fbcbf0 · 2021-09-14T10:47:26.000+02:00
* Deprecate usage of AfterConfiguration hook

* Upgrade UPGRADING.md accordingly

* Update feature tests to use InstallPlugin rather than AfterConfiguration

* Update some rdocs

* Add a notice in post_configuration_hook.feature

* Add entry in CHANGELOG.md

* Add an InstallPlugin feature based on AfterConfiguration one
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -50,6 +50,10 @@ Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blo
 
 ### Deprecated
 
+- `AfterConfiguration` is deprecated. Please use `InstallPlugin` or `BeforeAll` instead.
+  See the [UPGRADING.md](./UPGRADING.md#upgrading-to-710) to update your code accordingly.
+  ([1570](https://github.com/cucumber/cucumber-ruby/pull/1570))
+
 - The built-in Wire protocol
 
   The Wire protocol is still officially supported, but as an optional plugin rather
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -44,3 +44,13 @@ require 'cucumber/wire'
 ```
 
 The wire protocol will be installed, and no deprecation message will be shown anymore.
+
+## AfterConfiguration hook
+
+Usage of `AfterConfiguration` hook will be deprecated in 7.1.0.
+
+Use the new `InstallPlugin` hook if you need the `configuration` parameter.
+
+Use the new `BeforeAll` hook if you don't need the `configuration` parameter.
+
+More information about hooks can be found in [features/docs/writing_support_code/hooks/README.md](./features/docs/writing_support_code/hooks/README.md).
diff --git a/features/docs/api/listen_for_events.feature b/features/docs/api/listen_for_events.feature
@@ -17,7 +17,7 @@ Feature: Listen for events
       """
     And a file named "features/support/my_listener.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         io = config.out_stream
         config.on_event :step_activated do |event|
           io.puts "Success!"
@@ -44,7 +44,7 @@ Feature: Listen for events
     And the standard step definitions
     And a file named "features/support/my_listener.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         io = config.out_stream
         config.on_event :test_step_finished do |event|
           io.puts event.result.passed?
diff --git a/features/docs/events/gherkin_source_read_event.feature b/features/docs/events/gherkin_source_read_event.feature
@@ -20,7 +20,7 @@ Feature: Gherkin Source Read Event
       """
     And a file named "features/support/events.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         config.on_event :gherkin_source_read do |event|
           config.out_stream.puts "path: #{event.path}"
           config.out_stream.puts "body:\n#{event.body}"
diff --git a/features/docs/events/step_activated_event.feature b/features/docs/events/step_activated_event.feature
@@ -20,7 +20,7 @@ Feature: Step Activated Event
       """
     And a file named "features/support/events.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         config.on_event :step_activated do |event|
           config.out_stream.puts "The step: #{event.test_step.location}"
           config.out_stream.puts "The step definition: #{event.step_match.location}"
diff --git a/features/docs/events/step_definition_registered_event.feature b/features/docs/events/step_definition_registered_event.feature
@@ -15,7 +15,7 @@ Feature: Step definition registered
       """
     And a file named "features/support/events.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         config.on_event :step_definition_registered do |event|
           config.out_stream.puts "The step definition: #{event.step_definition.location}"
         end
diff --git a/features/docs/events/test_case_finished_event.feature b/features/docs/events/test_case_finished_event.feature
@@ -1,7 +1,7 @@
 Feature: Test Case Finished Event
 
-  This event is fired after each scenario or examples table row (generally named a 
-  Test Case) has finished executing. You can use the event to learn about the 
+  This event is fired after each scenario or examples table row (generally named a
+  Test Case) has finished executing. You can use the event to learn about the
   result of the test case.
 
   See [the API documentation](http://www.rubydoc.info/github/cucumber/cucumber-ruby/Cucumber/Events/TestCaseFinished) for more information about the data available on this event.
@@ -16,7 +16,7 @@ Feature: Test Case Finished Event
       """
     And a file named "features/support/events.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         config.on_event :test_case_finished do |event|
           config.out_stream.puts "Results"
           config.out_stream.puts "-------"
diff --git a/features/docs/events/test_case_started_event.feature b/features/docs/events/test_case_started_event.feature
@@ -19,7 +19,7 @@ Feature: Test Case Started Event
     And a file named "features/support/events.rb" with:
       """
       stdout = nil
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         stdout = config.out_stream # make sure all the `puts` calls can write to the same output
         config.on_event :test_case_started do |event|
           stdout.puts "before"
@@ -30,7 +30,7 @@ Feature: Test Case Started Event
         end
       end
 
-      Given(/this is a step/) do 
+      Given(/this is a step/) do
       end
 
       """
@@ -44,7 +44,7 @@ Feature: Test Case Started Event
       @scenario
       @feature
       Feature: A feature
-      
+
         @scenario
         Scenario: A passing scenario
           Given this is a step
diff --git a/features/docs/events/test_run_started_event.feature b/features/docs/events/test_run_started_event.feature
@@ -21,7 +21,7 @@ Feature: Test Run Started Event
       """
     And a file named "features/support/events.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         config.on_event :test_run_started do |event|
           config.out_stream.puts "test run started"
           config.out_stream.puts event.test_cases.map(&:location)
diff --git a/features/docs/events/test_step_finished_event.feature b/features/docs/events/test_step_finished_event.feature
@@ -1,7 +1,7 @@
 Feature: Test Step Finished Event
 
-  This event is fired after each step in a scenario or scenario outline example 
-  (generally named a Test Step) has finished executing. You can use the event to learn about the 
+  This event is fired after each step in a scenario or scenario outline example
+  (generally named a Test Step) has finished executing. You can use the event to learn about the
   result of the test step.
 
   See [the API documentation](http://www.rubydoc.info/github/cucumber/cucumber-ruby/Cucumber/Events/TestStepFinished) for more information about the data available on this event and the result object.
@@ -22,7 +22,7 @@ Feature: Test Step Finished Event
       """
     And a file named "features/support/events.rb" with:
       """
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         config.on_event :test_step_finished do |event|
           config.out_stream.puts "Test step: #{event.test_step}"
           config.out_stream.puts "The result is: #{event.result}"
diff --git a/features/docs/events/test_step_started_event.feature b/features/docs/events/test_step_started_event.feature
@@ -1,6 +1,6 @@
 Feature: Test Step Started Event
 
-  This event is fired just before each step in a scenario or scenario outline example 
+  This event is fired just before each step in a scenario or scenario outline example
   (generally named a Test Step) starts to be executed. This event is read-only, so there
   is no way to prevent the test step from running, but you can use it for logging or user
   notification.
@@ -19,7 +19,7 @@ Feature: Test Step Started Event
     And a file named "features/support/events.rb" with:
       """
       stdout = nil
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         stdout = config.out_stream # make sure all the `puts` calls can write to the same output
         config.on_event :test_step_started do |event|
           stdout.puts "before"
diff --git a/features/docs/extending_cucumber/custom_filter.feature b/features/docs/extending_cucumber/custom_filter.feature
@@ -1,6 +1,6 @@
 Feature: Custom filter
 
-  Scenario: Add a custom filter via AfterConfiguration hook
+  Scenario: Add a custom filter via InstallPlugin hook
     Given a file named "features/test.feature" with:
       """
       Feature:
@@ -20,7 +20,7 @@ Feature: Custom filter
         end
       end
 
-      AfterConfiguration do |config|
+      InstallPlugin do |config|
         config.filters << MakeAnythingPass.new
       end
       """
diff --git a/features/docs/writing_support_code/hooks/install_plugin_hook.feature b/features/docs/writing_support_code/hooks/install_plugin_hook.feature
@@ -0,0 +1,36 @@
+Feature: InstallPlugin Hook
+
+  In order to extend Cucumber
+  As a developer
+  I want to manipulate the Cucumber configuration after it has been created
+
+  Scenario: Changing the output format
+    Given a file named "features/support/env.rb" with:
+      """
+      InstallPlugin do |config|
+        config.formats << ['message', {}, config.out_stream]
+      end
+      """
+    And a file named "features/simple_scenario.feature" with:
+      """
+      Feature:
+        Scenario:
+          Given a step
+      """
+    When I run `cucumber features --publish-quiet`
+    Then the stderr should not contain anything
+    And the output should contain NDJSON with key "uri" and value "features/simple_scenario.feature"
+
+  Scenario: feature directories read from configuration
+    Given a file named "features/support/env.rb" with:
+      """
+      InstallPlugin do |config|
+        config.out_stream << "InstallPlugin hook read feature directories: #{config.feature_dirs.join(', ')}"
+      end
+      """
+    When I run `cucumber features --publish-quiet`
+    Then the stderr should not contain anything
+    And the output should contain:
+      """
+      InstallPlugin hook read feature directories: features
+      """
diff --git a/features/docs/writing_support_code/hooks/post_configuration_hook.feature b/features/docs/writing_support_code/hooks/post_configuration_hook.feature
@@ -4,6 +4,8 @@ Feature: Post Configuration Hook [#423]
   As a developer
   I want to manipulate the Cucumber configuration after it has been created
 
+  Note: This hook has been deprecated in favor of InstallPlugin.
+
   Scenario: Changing the output format
     Given a file named "features/support/env.rb" with:
       """
diff --git a/lib/cucumber/events.rb b/lib/cucumber/events.rb
@@ -11,7 +11,7 @@ module Cucumber
   # To subscribe to an event, use {Cucumber::Configuration#on_event}
   #
   # @example
-  #   AfterConfiguration do |config|
+  #   InstallPlugin do |config|
   #     config.on_event :test_case_finished do |event|
   #       puts event.result
   #     end
diff --git a/lib/cucumber/glue/dsl.rb b/lib/cucumber/glue/dsl.rb
@@ -109,6 +109,8 @@ def if_nil(value, default)
 
       # Registers a proc that will run after Cucumber is configured. You can register as
       # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
+      #
+      # DEPRECATED: please use InstallPlugin or BeforeAll instead
       def AfterConfiguration(&proc)
         Dsl.register_rb_hook('after_configuration', [], proc)
       end
diff --git a/lib/cucumber/glue/registry_and_more.rb b/lib/cucumber/glue/registry_and_more.rb
@@ -4,6 +4,7 @@
 require 'cucumber/cucumber_expressions/cucumber_expression'
 require 'cucumber/cucumber_expressions/regular_expression'
 require 'cucumber/cucumber_expressions/cucumber_expression_generator'
+require 'cucumber/deprecate'
 require 'cucumber/glue/dsl'
 require 'cucumber/glue/snippet'
 require 'cucumber/glue/hook'
@@ -135,6 +136,8 @@ def end_scenario
       end
 
       def after_configuration(configuration)
+        deprecate_after_configuration_hook if hooks[:after_configuration].any?
+
         hooks[:after_configuration].each do |hook|
           hook.invoke('AfterConfiguration', configuration)
         end
@@ -225,6 +228,14 @@ def invoked_step_definition_hash
       def hooks
         @hooks ||= Hash.new { |h, k| h[k] = [] }
       end
+
+      def deprecate_after_configuration_hook
+        Cucumber.deprecate(
+          'See https://github.com/cucumber/cucumber-ruby/blob/main/UPGRADING.md#upgrading-to-710 for more info',
+          ' AfterConfiguration hook',
+          '8.0.0'
+        )
+      end
     end
 
     def self.backtrace_line(proc, name)
diff --git a/spec/cucumber/glue/registry_and_more_spec.rb b/spec/cucumber/glue/registry_and_more_spec.rb
@@ -287,6 +287,22 @@ class << registry.current_world
           expect(scenario).to receive(:accept_hook?).with(b) { false }
           expect(registry.hooks_for(:around, scenario)).to eq [a]
         end
+
+        it 'shows a deprecation warning for after_configuration hooks' do
+          stub_const('Cucumber::Deprecate::STRATEGY', Cucumber::Deprecate::ForUsers)
+          allow(STDERR).to receive(:puts)
+
+          dsl.AfterConfiguration() {}
+
+          registry.after_configuration(nil)
+
+          expect(STDERR).to have_received(:puts).with(
+            a_string_including([
+              'WARNING: # AfterConfiguration hook is deprecated and will be removed after version 8.0.0.',
+              'See https://github.com/cucumber/cucumber-ruby/blob/main/UPGRADING.md#upgrading-to-710 for more info.'
+            ].join(' '))
+          )
+        end
       end
     end
   end
