Add a warning when the should syntax is used.

Signed-off-by: Sam Phippen <samphippen@googlemail.com>

lib/rspec/mocks/configuration.rb

@@ -43,13 +43,27 @@ def syntax
         syntaxes << :expect if Syntax.expect_enabled?
         syntaxes
       end
+
+      def reset_syntaxes_to_default
+        self.syntax = [:should, :expect]
+        @should_warn_about_should = true
+      end
+
+      def warn_about_should
+        if @should_warn_about_should
+          Kernel.warn("Should style expectations will be disabled by default in the\
+ next major version of RSpec (4), we recommend that you use expect style expectations\
+ or enable the syntax explicitly. <link_to_some_docs>.")
+          @should_warn_about_should = false
+        end
+      end
     end
 
     def self.configuration
       @configuration ||= Configuration.new
     end
 
-    configuration.syntax = [:should, :expect]
+    configuration.reset_syntaxes_to_default
   end
 end
 

lib/rspec/mocks/syntax.rb

@@ -12,16 +12,19 @@ def self.enable_should(syntax_host = default_should_syntax_host)
 
         syntax_host.class_eval do
           def should_receive(message, opts={}, &block)
+            ::RSpec::Mocks.configuration.warn_about_should
             opts[:expected_from] ||= caller(1)[0]
             ::RSpec::Mocks.expect_message(self, message.to_sym, opts, &block)
           end
 
           def should_not_receive(message, &block)
+            ::RSpec::Mocks.configuration.warn_about_should
             opts = {:expected_from => caller(1)[0]}
             ::RSpec::Mocks.expect_message(self, message.to_sym, opts, &block).never
           end
 
           def stub(message_or_hash, opts={}, &block)
+            ::RSpec::Mocks.configuration.warn_about_should
             if ::Hash === message_or_hash
               message_or_hash.each {|message, value| stub(message).and_return value }
             else

spec/rspec/mocks/configuration_spec.rb

@@ -85,6 +85,11 @@ def sandboxed
             expect(configured_syntax).to eq([:should])
           end
 
+          it "does not warn about the should syntax" do
+            Kernel.should_not_receive(:warn).with(/style expectations/i)
+            Object.new.should_not_receive(:nil?)
+          end
+
           it 'is a no-op when configured a second time' do
             Syntax.default_should_syntax_host.should_not_receive(:method_added)
             ::RSpec::Mocks::ExampleMethods.should_not_receive(:method_undefined)
@@ -110,6 +115,43 @@ def sandboxed
           it 'reports that both syntaxes are enabled' do
             expect(configured_syntax).to eq([:should, :expect])
           end
+
+          it "does not warn about the should syntax" do
+            Kernel.should_not_receive(:warn).with(/style expectations/i)
+            Object.new.should_not_receive(:nil?)
+          end
+        end
+
+        context "by default" do
+          before { configure_default_syntax }
+
+          it "it warns about should once, regardless of how many times it is called" do
+            expect(Kernel).to receive(:warn).once.with(/style expectations/i)
+            o = Object.new
+            o2 = Object.new
+            o.should_receive(:nil?)
+            o2.should_receive(:nil?)
+
+            o.nil?
+            o2.nil?
+          end
+
+          it "warns about should not once, regardless of how many times it is called" do
+            expect(Kernel).to receive(:warn).once.with(/style expectations/i)
+            o = Object.new
+            o2 = Object.new
+            o.should_not_receive(:nil?)
+            o2.should_not_receive(:nil?)
+          end
+
+          it "warns about stubbing once, regardless of how many times it is called" do
+            expect(Kernel).to receive(:warn).once.with(/style expectations/i)
+            o = Object.new
+            o2 = Object.new
+
+            o.stub(:faces)
+            o2.stub(:faces)
+          end
         end
       end
 
@@ -122,6 +164,10 @@ def configure_syntax(syntax)
           def configured_syntax
             RSpec::Mocks.configuration.syntax
           end
+
+          def configure_default_syntax
+            RSpec::Mocks.configuration.reset_syntaxes_to_default
+          end
         end
       end
 
@@ -142,6 +188,14 @@ def configured_syntax
               end
             end
           end
+
+          def configure_default_syntax
+            RSpec.configure do |rspec|
+              rspec.mock_with :rspec do |c|
+                c.reset_syntaxes_to_default
+              end
+            end
+          end
         end
       end
     end