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

@@ -9,7 +9,7 @@ Feature: shared context
   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 +19,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 +76,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 +107,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