Add config.when_first_matching_example_defined.

Author: myronmarston

Changelog.md

@@ -5,6 +5,8 @@ Enhancements:
 
 * Remove unneeded `:execution_result` example groups metadata, saving a
   bit of memory. (Myron Marston, #2172)
+* Add new `config.when_first_matching_example_defined` hook. (Myron
+  Marston, #2175)
 
 Bug Fixes:
 

lib/rspec/core/configuration.rb

@@ -1597,6 +1597,39 @@ def define_derived_metadata(*filters, &block)
         @derived_metadata_blocks.append(block, meta)
       end
 
+      # Defines a callback that runs after the first example with matching
+      # metadata is defined. If no examples are defined with matching metadata,
+      # it will not get called at all.
+      #
+      # This can be used as an alternative to `before(:suite)` to define some
+      # expensive one-time setup that will be skipped if none of the loaded
+      # examples need it.
+      #
+      # @example
+      #   RSpec.configure do |config|
+      #     # only spend time bootstrapping the database if any
+      #     # examples tagged with `:db` have been loaded.
+      #     config.when_first_matching_example_defined(:db) do
+      #       ORM.bootstrap_db
+      #     end
+      #   end
+      def when_first_matching_example_defined(*filters, &block)
+        specified_meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
+
+        callback = lambda do |example_or_group_meta|
+          # Example groups do not have `:example_group` metadata
+          # (instead they have `:parent_example_group` metadata).
+          return unless example_or_group_meta.key?(:example_group)
+
+          # Ensure the callback only fires once.
+          @derived_metadata_blocks.items_for(specified_meta).delete(callback)
+
+          block.call
+        end
+
+        @derived_metadata_blocks.append(callback, specified_meta)
+      end
+
       # @private
       def apply_derived_metadata_to(metadata)
         @derived_metadata_blocks.items_for(metadata).each do |block|

spec/rspec/core/configuration_spec.rb

@@ -1554,6 +1554,111 @@ def exclude?(line)
       end
     end
 
+    describe "#when_first_matching_example_defined" do
+      include_examples "warning of deprecated `:example_group` during filtering configuration", :when_first_matching_example_defined
+
+      it "runs the block when the first matching example is defined" do
+        sequence = []
+        RSpec.configuration.when_first_matching_example_defined(:foo) do
+          sequence << :callback
+        end
+
+        RSpec.describe do
+          example("ex 1")
+          sequence << :before_first_matching_example_defined
+          example("ex 2", :foo)
+          sequence << :after_first_matching_example_defined
+        end
+
+        expect(sequence).to eq [:before_first_matching_example_defined, :callback, :after_first_matching_example_defined]
+      end
+
+      it "does not fire when later matching examples are defined" do
+        sequence = []
+        RSpec.configuration.when_first_matching_example_defined(:foo) do
+          sequence << :callback
+        end
+
+        RSpec.describe do
+          example("ex 1", :foo)
+          sequence.clear
+
+          sequence << :before_second_matching_example_defined
+          example("ex 2", :foo)
+          sequence << :after_second_matching_example_defined
+        end
+
+        expect(sequence).to eq [:before_second_matching_example_defined, :after_second_matching_example_defined]
+      end
+
+      it "does not run the block if no matching examples are defined" do
+        sequence = []
+        RSpec.configuration.when_first_matching_example_defined(:foo) do
+          sequence << :callback
+        end
+
+        RSpec.describe do
+          example("ex 1")
+          example("ex 2", :bar)
+        end
+
+        expect(sequence).to eq []
+      end
+
+      it 'does not run the block if groups match the metadata but no examples do' do
+        called = false
+        RSpec.configuration.when_first_matching_example_defined(:foo => true) do
+          called = true
+        end
+
+        RSpec.describe "group 1", :foo => true do
+        end
+
+        RSpec.describe "group 2", :foo => true do
+          example("ex", :foo => false)
+        end
+
+        expect(called).to be false
+      end
+
+      it "still runs after the first matching example even if there is a group that matches earlier" do
+        sequence = []
+        RSpec.configuration.when_first_matching_example_defined(:foo) do
+          sequence << :callback
+        end
+
+        RSpec.describe "group", :foo do
+        end
+
+        RSpec.describe do
+          example("ex 1")
+          sequence << :before_first_matching_example_defined
+          example("ex 2", :foo)
+          sequence << :after_first_matching_example_defined
+        end
+
+        expect(sequence).to eq [:before_first_matching_example_defined, :callback, :after_first_matching_example_defined]
+      end
+
+      context "when a group is defined with matching metadata" do
+        it "runs the callback after the first example in the group is defined" do
+          sequence = []
+          RSpec.configuration.when_first_matching_example_defined(:foo) do
+            sequence << :callback
+          end
+
+          sequence << :before_group
+          RSpec.describe "group", :foo do
+            sequence << :before_example
+            example("ex")
+            sequence << :after_example
+          end
+
+          expect(sequence).to eq [:before_group, :before_example, :callback, :after_example]
+        end
+      end
+    end
+
     describe "#add_setting" do
       describe "with no modifiers" do
         context "with no additional options" do