Add config.when_first_matching_example_defined.

Author: myronmarston

Changelog.md

@@ -9,6 +9,8 @@ Enhancements:
   (Myron Marston, #2189)
 * `RSpec::Core::Configuration#reporter` is now public API under semver.
   (Jon Rowe, #2193)
+* Add new `config.when_first_matching_example_defined` hook. (Myron
+  Marston, #2175)
 
 ### 3.5.0.beta1 / 2016-02-06
 [Full Changelog](http://github.com/rspec/rspec-core/compare/v3.4.3...v3.5.0.beta1)

features/.nav

@@ -20,6 +20,7 @@
   - before_and_after_hooks.feature
   - around_hooks.feature
   - filtering.feature
+  - when_first_matching_example_defined.feature
 - subject:
   - implicit_subject.feature
   - explicit_subject.feature

features/hooks/when_first_matching_example_defined.feature

@@ -0,0 +1,70 @@
+Feature: `when_first_matching_example_defined` hook
+
+  In large projects that use RSpec, it's common to have some expensive setup logic
+  that is only needed when certain kinds of specs have been loaded. If that kind of
+  spec has not been loaded, you'd prefer to avoid the cost of doing the setup.
+
+  The `when_first_matching_example_defined` hook makes it easy to conditionally
+  perform some logic when the first example is defined with matching metadata,
+  allowing you to ensure the necessary setup is performed only when needed.
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.when_first_matching_example_defined(:db) do
+          require "support/db"
+        end
+      end
+      """
+    And a file named "spec/support/db.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.before(:suite) do
+          puts "Bootstrapped the DB."
+        end
+
+        config.around(:example, :db) do |example|
+          puts "Starting a DB transaction."
+          example.run
+          puts "Rolling back a DB transaction."
+        end
+      end
+      """
+    And a file named ".rspec" with:
+      """
+      --require spec_helper
+      """
+    And a file named "spec/unit_spec.rb" with:
+      """
+      RSpec.describe "A unit spec" do
+        it "does not require a database" do
+          puts "in unit example"
+        end
+      end
+      """
+    And a file named "spec/integration_spec.rb" with:
+      """
+      RSpec.describe "An integration spec", :db do
+        it "requires a database" do
+          puts "in integration example"
+        end
+      end
+      """
+
+  Scenario: Running the entire suite loads the DB setup
+    When I run `rspec`
+    Then it should pass with:
+      """
+      Bootstrapped the DB.
+      Starting a DB transaction.
+      in integration example
+      Rolling back a DB transaction.
+      .in unit example
+      .
+      """
+
+  Scenario: Running just the unit spec does not load the DB setup
+    When I run `rspec spec/unit_spec.rb`
+    Then the examples should all pass
+    And the output should not contain "DB"

lib/rspec/core/configuration.rb

@@ -1553,6 +1553,41 @@ 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 to ensure some setup is performed (such as bootstrapping
+      # a DB or loading a specific file that adds significantly to the boot time)
+      # if needed (as indicated by the presence of an example with matching metadata)
+      # but avoided otherwise.
+      #
+      # @example
+      #   RSpec.configure do |config|
+      #     config.when_first_matching_example_defined(:db) do
+      #       # Load a support file that does some heavyweight setup,
+      #       # including bootstrapping the DB, but only if we have loaded
+      #       # any examples tagged with `:db`.
+      #       require 'support/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

@@ -1598,6 +1598,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