Add new config.include_context API for including shared contexts.

Author: myronmarston

Changelog.md

@@ -13,6 +13,9 @@ Enhancements:
   others in a one-off manner.  For example, `rspec spec/unit
   spec/acceptance --order defined` will run unit specs before acceptance
   specs. (Myron Marston, #2253)
+* Add new `config.include_context` API for configuring global or
+  filtered inclusion of shared contexts in example groups.
+  (Myron Marston, #2256)
 
 Bug Fixes:
 

features/example_groups/shared_context.feature

@@ -1,15 +1,13 @@
 Feature: shared context
 
-  Use `shared_context` to define a block that will be evaluated in the context
-  of example groups either explicitly, using `include_context`, or implicitly by
-  matching metadata.
+  Use `shared_context` to define a block that will be evaluated in the context of example groups either locally, using `include_context` in an example group, or globally using `config.include_context`.
 
   When implicitly including shared contexts via matching metadata, the normal way is to define matching metadata on an example group, in which case the context is included in the entire group. However, you also have the option to include it in an individual example instead. RSpec treats every example as having a singleton example group (analogous to Ruby's singleton classes) containing just the one example.
 
   Background:
     Given a file named "shared_stuff.rb" with:
       """ruby
-      RSpec.shared_context "shared stuff", :a => :b do
+      RSpec.shared_context "shared stuff" do
         before { @some_var = :some_value }
         def shared_method
           "it works"
@@ -19,6 +17,10 @@ Feature: shared context
           'this is the subject'
         end
       end
+
+      RSpec.configure do |rspec|
+        rspec.include_context "shared stuff", :include_shared => true
+      end
       """
 
   Scenario: Declare a shared context and include it with `include_context`
@@ -72,7 +74,7 @@ Feature: shared context
       """ruby
       require "./shared_stuff.rb"
 
-      RSpec.describe "group that includes a shared context using metadata", :a => :b do
+      RSpec.describe "group that includes a shared context using metadata", :include_shared => true do
         it "has access to methods defined in shared context" do
           expect(shared_method).to eq("it works")
         end
@@ -103,7 +105,7 @@ Feature: shared context
           expect(self).not_to respond_to(:shared_method)
         end
 
-        it "has access to shared methods from examples with matching metadata", :a => :b do
+        it "has access to shared methods from examples with matching metadata", :include_shared => true do
           expect(shared_method).to eq("it works")
         end
       end

lib/rspec/core/configuration.rb

@@ -1153,7 +1153,7 @@ def exclusion_filter
       #     end
       #
       #     RSpec.configure do |config|
-      #       config.include(UserHelpers) # included in all modules
+      #       config.include(UserHelpers) # included in all groups
       #       config.include(AuthenticationHelpers, :type => :request)
       #     end
       #
@@ -1172,6 +1172,7 @@ def exclusion_filter
       #   example has a singleton example group containing just the one
       #   example.
       #
+      # @see #include_context
       # @see #extend
       # @see #prepend
       def include(mod, *filters)
@@ -1180,6 +1181,42 @@ def include(mod, *filters)
         end
       end
 
+      # Tells RSpec to include the named shared example group in example groups.
+      # Use `filters` to constrain the groups or examples in which to include
+      # the example group.
+      #
+      # @example
+      #
+      #     RSpec.shared_context "example users" do
+      #       let(:admin_user) { create_user(:admin) }
+      #       let(:guest_user) { create_user(:guest) }
+      #     end
+      #
+      #     RSpec.configure do |config|
+      #       config.include_context "example users", :type => :request
+      #     end
+      #
+      #     describe "admin page", :type => :request do
+      #       it "can be viewed by admins" do
+      #         login_with admin_user
+      #         get "/admin"
+      #         expect(response).to be_ok
+      #       end
+      #     end
+      #
+      # @note Filtered context inclusions can also be applied to
+      #   individual examples that have matching metadata. Just like
+      #   Ruby's object model is that every object has a singleton class
+      #   which has only a single instance, RSpec's model is that every
+      #   example has a singleton example group containing just the one
+      #   example.
+      #
+      # @see #include
+      def include_context(shared_group_name, *filters)
+        block = world.shared_example_group_registry.find([:main], shared_group_name)
+        include SharedExampleGroupModule.new(shared_group_name, block), *filters
+      end
+
       # Tells RSpec to extend example groups with `mod`. Methods defined in
       # `mod` are exposed to example groups (not examples). Use `filters` to
       # constrain the groups to extend.

spec/rspec/core/configuration_spec.rb

@@ -914,6 +914,46 @@ def file_at(relative_path)
       end
     end
 
+    describe "#include_context" do
+      context "with no metadata filters" do
+        it 'includes the named shared example group in all groups' do
+          RSpec.shared_examples "shared group" do
+            let(:foo) { 17 }
+          end
+          RSpec.configuration.include_context "shared group"
+
+          expect(RSpec.describe.new.foo).to eq 17
+        end
+      end
+
+      context "with metadata filters" do
+        it 'includes the named shared example group in matching groups' do
+          RSpec.shared_examples "shared group" do
+            let(:foo) { 18 }
+          end
+          RSpec.configuration.include_context "shared group", :include_it
+
+          expect(RSpec.describe.new).not_to respond_to(:foo)
+          expect(RSpec.describe("", :include_it).new.foo).to eq 18
+        end
+
+        it 'includes the named shared example group in the singleton class of matching examples' do
+          RSpec.shared_examples "shared group" do
+            let(:foo) { 19 }
+          end
+          RSpec.configuration.include_context "shared group", :include_it
+
+          foo_value = nil
+          describe_successfully do
+            it { expect { self.foo }.to raise_error(NoMethodError) }
+            it("", :include_it) { foo_value = foo }
+          end
+
+          expect(foo_value).to eq 19
+        end
+      end
+    end
+
     describe "#include" do
       include_examples "warning of deprecated `:example_group` during filtering configuration", :include, Enumerable