rspec-core 2.99.0.beta1 → 2.99.0.beta2

data/Changelog.md

@@ -1,3 +1,43 @@
+### 2.99.0.beta2 / 2014-02-17
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.99.0.beta1...v2.99.0.beta2)
+
+Enhancements:
+
+* Add `is_expected` for one-liners that read well with the
+  `expect`-based syntax. `is_expected` is simply defined as
+  `expect(subject)` and can be used in an expression like:
+  `it { is_expected.to read_well }`. (Myron Marston)
+* Backport `skip` from RSpec 3, which acts like `pending` did in RSpec 2
+  when not given a block, since the behavior of `pending` is changing in
+  RSpec 3. (Xavier Shay)
+
+Deprecations:
+
+* Deprecate inexact `mock_with` config options. RSpec 3 will only support
+  the exact symbols `:rspec`, `:mocha`, `:flexmock`, `:rr` or `:nothing`
+  (or any module that implements the adapter interface). RSpec 2 did
+  fuzzy matching but this will not be supported going forward.
+  (Myron Marston)
+* Deprecate `show_failures_in_pending_blocks` config option. To achieve
+  the same behavior as the option enabled, you can use a custom
+  formatter instead. (Xavier Shay)
+* Add a deprecation warning for the fact that the behavior of `pending`
+  is changing in RSpec 3 -- rather than skipping the example (as it did
+  in 2.x when no block was provided), it will run the example and mark
+  it as failed if no exception is raised. Use `skip` instead to preserve
+  the old behavior. (Xavier Shay)
+* Deprecate 's', 'n', 'spec' and 'nested' as aliases for documentation
+  formatter. (Jon Rowe)
+* Deprecate `RSpec::Core::Reporter#abort` in favor of
+  `RSpec::Core::Reporter#finish`. (Jon Rowe)
+
+Bug Fixes:
+
+* Fix failure (undefined method `path`) in end-of-run summary
+  when `raise_errors_for_deprecations!` is configured. (Myron Marston)
+* Fix issue were overridding spec ordering from the command line wasnt
+  fully recognised interally. (Jon Rowe)
+
 ### 2.99.0.beta1 / 2013-11-07
 [full changelog](http://github.com/rspec/rspec-core/compare/v2.14.7...v2.99.0.beta1)
 

data/features/command_line/line_number_option.feature

@@ -46,9 +46,9 @@ Feature: --line_number option
 
       describe 9 do
 
-        it { should be > 8 }
+        it { is_expected.to be > 8 }
 
-        it { should be < 10 }
+        it { is_expected.not_to be < 10 }
 
       end
       """

data/features/example_groups/basic_structure.feature

@@ -23,7 +23,7 @@ Feature: basic structure (describe/it)
       end
     end
     """
-    When I run `rspec sample_spec.rb -fn`
+    When I run `rspec sample_spec.rb -f doc`
     Then the output should contain:
       """
       something

data/features/expectation_framework_integration/configure_expectation_framework.feature

@@ -23,7 +23,7 @@ Feature: configure expectation framework
       end
 
       describe 6 do
-        it { should be_a_multiple_of(3) }
+        it { is_expected.to be_a_multiple_of 3 }
       end
       """
     When I run `rspec example_spec.rb`

data/features/subject/explicit_subject.feature

@@ -73,7 +73,7 @@ Feature: explicit subject
           context "with index out of bounds" do
             before { Array.should_receive(:one_two_three).once.and_return([1,2,3]) }
             subject { Array.one_two_three[42] }
-            it { should be_nil }
+            it { is_expected.to be_nil }
           end
         end
       end

data/features/subject/one_liner_syntax.feature

@@ -0,0 +1,71 @@
+Feature: One-liner syntax
+
+  RSpec supports a one-liner syntax for setting an expectation
+  on the `subject`. RSpec will give the examples a doc string
+  that is auto-generated from the matcher used in the example.
+  This is designed specifically to help avoid duplication in
+  situations where the doc string and the matcher used in the
+  example mirror each other exactly. When used excessively,
+  it can produce documentation output that does not read well
+  or contribute to understanding the object you are describing.
+
+  This comes in two flavors:
+
+    * `is_expected` is defined simply as `expect(subject)` and is
+      designed for when you are using rspec-expectations with its
+      newer expect-based syntax.
+    * `should` was designed back when rspec-expectations only had
+      a should-based syntax. However, it continues to be available
+      and work even if the `:should` syntax is disabled (since that
+      merely removes `Object#should` but this is
+      `RSpec::Core::ExampleGroup#should`).
+
+  Note: this feature is only available when using rspec-expectations.
+
+  Scenario: implicit subject
+    Given a file named "example_spec.rb" with:
+      """ruby
+      describe Array do
+        describe "when first created" do
+          # Rather than:
+          # it "should be empty" do
+          #   subject.should be_empty
+          # end
+
+          it { should be_empty }
+          # or
+          it { is_expected.to be_empty }
+        end
+      end
+      """
+    When I run `rspec example_spec.rb --format doc`
+    Then the examples should all pass
+     And the output should contain:
+       """
+       Array
+         when first created
+           should be empty
+           should be empty
+       """
+
+  Scenario: explicit subject
+    Given a file named "example_spec.rb" with:
+      """ruby
+      describe Array do
+        describe "with 3 items" do
+          subject { [1,2,3] }
+          it { should_not be_empty }
+          # or
+          it { is_expected.not_to be_empty }
+        end
+      end
+      """
+    When I run `rspec example_spec.rb --format doc`
+    Then the examples should all pass
+     And the output should contain:
+       """
+       Array
+         with 3 items
+           should not be empty
+           should not be empty
+       """

data/lib/rspec/core/caller_filter.rb

@@ -3,53 +3,58 @@ module RSpec
   # non-rspec lines. This enables errors to be reported at the call site in
   # the code using the library, which is far more useful than the particular
   # internal method that raised an error.
-  class CallerFilter
-
-    RSPEC_LIBS = %w[
-      core
-      mocks
-      expectations
-      matchers
-      rails
-    ]
-
-    ADDITIONAL_TOP_LEVEL_FILES = %w[ autorun ]
-
-    LIB_REGEX = %r{/lib/rspec/(#{(RSPEC_LIBS + ADDITIONAL_TOP_LEVEL_FILES).join('|')})(\.rb|/)}
-
-    if RUBY_VERSION >= '2.0.0'
-      def self.first_non_rspec_line
-        # `caller` is an expensive method that scales linearly with the size of
-        # the stack. The performance hit for fetching it in chunks is small,
-        # and since the target line is probably near the top of the stack, the
-        # overall improvement of a chunked search like this is significant.
-        #
-        # See benchmarks/caller.rb for measurements.
-
-        # Initial value here is mostly arbitrary, but is chosen to give good
-        # performance on the common case of creating a double.
-        increment = 5
-        i         = 1
-        line      = nil
-
-        while !line
-          stack = caller(i, increment)
-          raise "No non-lib lines in stack" unless stack
-
-          line = stack.find { |l| l !~ LIB_REGEX }
-
-          i         += increment
-          increment *= 2 # The choice of two here is arbitrary.
-        end
 
-        line
-      end
-    else
-      # Earlier rubies do not support the two argument form of `caller`. This
-      # fallback is logically the same, but slower.
-      def self.first_non_rspec_line
-        caller.find { |line| line !~ LIB_REGEX }
+  unless defined?(CallerFilter)
+
+    class CallerFilter
+
+      RSPEC_LIBS = %w[
+        core
+        mocks
+        expectations
+        matchers
+        rails
+      ]
+
+      ADDITIONAL_TOP_LEVEL_FILES = %w[ autorun ]
+
+      LIB_REGEX = %r{/lib/rspec/(#{(RSPEC_LIBS + ADDITIONAL_TOP_LEVEL_FILES).join('|')})(\.rb|/)}
+
+      if RUBY_VERSION >= '2.0.0'
+        def self.first_non_rspec_line
+          # `caller` is an expensive method that scales linearly with the size of
+          # the stack. The performance hit for fetching it in chunks is small,
+          # and since the target line is probably near the top of the stack, the
+          # overall improvement of a chunked search like this is significant.
+          #
+          # See benchmarks/caller.rb for measurements.
+
+          # Initial value here is mostly arbitrary, but is chosen to give good
+          # performance on the common case of creating a double.
+          increment = 5
+          i         = 1
+          line      = nil
+
+          while !line
+            stack = caller(i, increment)
+            return nil unless stack
+
+            line = stack.find { |l| l !~ LIB_REGEX }
+
+            i         += increment
+            increment *= 2 # The choice of two here is arbitrary.
+          end
+
+          line
+        end
+      else
+        # Earlier rubies do not support the two argument form of `caller`. This
+        # fallback is logically the same, but slower.
+        def self.first_non_rspec_line
+          caller.find { |line| line !~ LIB_REGEX }
+        end
       end
     end
+
   end
 end

data/lib/rspec/core/configuration.rb

@@ -190,7 +190,27 @@ module RSpec
 
       # When a block passed to pending fails (as expected), display the failure
       # without reporting it as a failure (default: false).
-      add_setting :show_failures_in_pending_blocks
+      def show_failures_in_pending_blocks=(value)
+        RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''))
+          |RSpec.configuration.show_failures_in_pending_blocks is being removed
+          |with no replacement. Called from #{CallerFilter.first_non_rspec_line}.
+        EOS
+
+        @show_failures_in_pending_blocks = value
+      end
+
+      def show_failures_in_pending_blocks
+        RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''))
+          |RSpec.configuration.show_failures_in_pending_blocks is being removed
+          |with no replacement. Called from #{CallerFilter.first_non_rspec_line}.
+        EOS
+
+        @show_failures_in_pending_blocks
+      end
+
+      def show_failures_in_pending_blocks?
+        !!show_failures_in_pending_blocks
+      end
 
       # Convert symbols to hashes with the symbol as a key with a value of
       # `true` (default: false).
@@ -250,6 +270,7 @@ module RSpec
         @filter_manager = FilterManager.new
         @preferred_options = {}
         @seed = srand % 0xFFFF
+        @ordering_already_forced = false
         @failure_color = :red
         @success_color = :green
         @pending_color = :yellow
@@ -266,9 +287,9 @@ module RSpec
       # Used to set higher priority option values from the command line.
       def force(hash)
         if hash.has_key?(:seed)
-          hash[:order], hash[:seed] = order_and_seed_from_seed(hash[:seed])
+          hash[:order], hash[:seed] = order_and_seed_from_seed(hash[:seed], true)
         elsif hash.has_key?(:order)
-          set_order_and_seed(hash)
+          set_order_and_seed(hash, true)
         end
         @preferred_options.merge!(hash)
         self.warnings = value_for :warnings, nil
@@ -427,14 +448,19 @@ module RSpec
         when String, Symbol
           require case framework.to_s
                   when /rspec/i
+                    deprecate_unless_mock_adapter_name_is_exact(framework, :rspec)
                     'rspec/core/mocking/with_rspec'
                   when /mocha/i
+                    deprecate_unless_mock_adapter_name_is_exact(framework, :mocha)
                     'rspec/core/mocking/with_mocha'
                   when /rr/i
+                    deprecate_unless_mock_adapter_name_is_exact(framework, :rr)
                     'rspec/core/mocking/with_rr'
                   when /flexmock/i
+                    deprecate_unless_mock_adapter_name_is_exact(framework, :flexmock)
                     'rspec/core/mocking/with_flexmock'
                   else
+                    deprecate_unless_mock_adapter_name_is_exact(framework, :nothing)
                     'rspec/core/mocking/with_absolutely_nothing'
                   end
           RSpec::Core::MockFrameworkAdapter
@@ -567,10 +593,13 @@ module RSpec
       end
 
       def debug=(bool)
-        if bool
-          # Usually this is called automatically by the --debug CLI option, so the
-          # deprecation message doesn't mention `RSpec::Core::Configuration#debug=`
+        if bool == :cli
           RSpec.deprecate("RSpec's built-in debugger support",
+                          :replacement => "a CLI option like `-rruby-debug` or `-rdebugger`",
+                          :call_site => nil)
+          bool = true
+        elsif bool
+          RSpec.deprecate("RSpec::Core::Configuration#debug=",
                           :replacement => "a CLI option like `-rruby-debug` or `-rdebugger`")
         else
           # ...but the only way to call this with a false value is to
@@ -1260,7 +1289,12 @@ MESSAGE
 
       def built_in_formatter(key)
         case key.to_s
-        when 'd', 'doc', 'documentation', 's', 'n', 'spec', 'nested'
+        when 'd', 'doc', 'documentation'
+          require 'rspec/core/formatters/documentation_formatter'
+          RSpec::Core::Formatters::DocumentationFormatter
+        when 's', 'n', 'spec', 'nested'
+          RSpec.deprecate "Using `#{key.to_s}` as a shortcut for the DocumentationFormatter",
+            :replacement => "`d`, `doc`, or `documentation`"
           require 'rspec/core/formatters/documentation_formatter'
           RSpec::Core::Formatters::DocumentationFormatter
         when 'h', 'html'
@@ -1319,26 +1353,22 @@ MESSAGE
         File.new(path, 'w')
       end
 
-      def order_and_seed_from_seed(value)
-        @group_ordering_block = RANDOM_ORDERING
-        @example_ordering_block = RANDOM_ORDERING
-        @order, @seed = 'rand', value.to_i
-        [@order, @seed]
+      def order_and_seed_from_seed(value, force = false)
+        order_and_seed_from_order "rand:#{value}", force
       end
 
-      def set_order_and_seed(hash)
-        hash[:order], seed = order_and_seed_from_order(hash[:order])
+      def set_order_and_seed(hash, force = false)
+        hash[:order], seed = order_and_seed_from_order(hash[:order], force)
         hash[:seed] = seed if seed
       end
 
-      def order_and_seed_from_order(type)
+      def order_and_seed_from_order(type, force = false)
         order, seed = type.to_s.split(':')
         @order = order
         @seed  = seed = seed.to_i if seed
 
         if order.to_s.match(/rand/)
-          @group_ordering_block = RANDOM_ORDERING
-          @example_ordering_block = RANDOM_ORDERING
+          ordering = RANDOM_ORDERING
         elsif %w[ default defined ].include?(order)
           if order == 'default'
             RSpec.deprecate("RSpec::Core::Configuration#order = 'default'",
@@ -1346,10 +1376,15 @@ MESSAGE
           end
 
           @order, @seed = nil, nil
-          @group_ordering_block = DEFAULT_ORDERING
-          @example_ordering_block = DEFAULT_ORDERING
+          ordering = DEFAULT_ORDERING
         end
 
+        unless @ordering_already_forced
+          @group_ordering_block = ordering
+          @example_ordering_block = ordering
+        end
+        @ordering_already_forced = true if force
+
         return order, seed
       end
 
@@ -1357,6 +1392,11 @@ MESSAGE
         [DEFAULT_ORDERING, RANDOM_ORDERING].include?(block)
       end
 
+      def deprecate_unless_mock_adapter_name_is_exact(name, expected)
+        return if name == expected
+        RSpec.deprecate("`config.mock_with #{name.inspect}`", :replacement => "`config.mock_with :#{expected}`")
+      end
+
     end
   end
 end

data/lib/rspec/core/example.rb

@@ -44,7 +44,7 @@ module RSpec
       delegate_to_metadata :full_description, :execution_result, :file_path, :pending, :location
 
       # Returns the string submitted to `example` or its aliases (e.g.
-      # `specify`, `it`, etc).  If no string is submitted (e.g. `it { should
+      # `specify`, `it`, etc).  If no string is submitted (e.g. `it { is_expected.to
       # do_something }`) it returns the message generated by the matcher if
       # there is one, otherwise returns a message including the location of the
       # example.

data/lib/rspec/core/example_group.rb

@@ -62,6 +62,22 @@ module RSpec
         def self.define_example_method(name, extra_options={})
           module_eval(<<-END_RUBY, __FILE__, __LINE__)
             def #{name}(desc=nil, *args, &block)
+              if #{name.inspect} == :pending
+                RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\\|/, ''))
+                  |The semantics of `RSpec::Core::ExampleGroup#pending` are changing in RSpec 3.
+                  |In RSpec 2.x, it caused the example to be skipped. In RSpec 3, the example will
+                  |still be run but is expected to fail, and will be marked as a failure (rather
+                  |than as pending) if the example passes, just like how `pending` with a block
+                  |from within an example already works.
+                  |
+                  |To keep the same skip semantics, change `pending` to `skip`.  Otherwise, if you
+                  |want the new RSpec 3 behavior, you can safely ignore this warning and continue
+                  |to upgrade to RSpec 3 without addressing it.
+                  |
+                  |Called from \#{CallerFilter.first_non_rspec_line}.
+                  |
+                EOS
+              end
               options = build_metadata_hash_from(args)
               options.update(:pending => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
               options.update(#{extra_options.inspect})
@@ -108,6 +124,10 @@ module RSpec
         # Shortcut to define an example with :pending => true
         # @see example
         define_example_method :pending,  :pending => true
+        # Shortcut to define an example with :pending => true
+        # Backported from RSpec 3 to aid migration.
+        # @see example
+        define_example_method :skip,     :pending => true
         # Shortcut to define an example with :pending => 'Temporarily disabled with xexample'
         # @see example
         define_example_method :xexample, :pending => 'Temporarily disabled with xexample'