rspec-core 2.99.0.beta2 → 2.99.0.rc1

data/lib/rspec/core/deprecated_mutable_array_proxy.rb

@@ -0,0 +1,32 @@
+module RSpec
+  module Core
+    class DeprecatedMutableArrayProxy
+
+      def initialize(array)
+        @array = array
+      end
+
+      mutated_methods =
+        [
+          :<<, :[]=, :clear, :collect!, :compact!, :concat, :delete,
+          :delete_at, :delete_if, :fill, :flatten!, :keep_if, :map!,
+          :pop, :push, :reject!, :replace, :reverse!, :rotate!,
+          :select!, :shift, :shuffle!, :slice!, :sort!, :sort_by!,
+          :uniq!, :unshift
+        ]
+      array_methods = Array.instance_methods.map(&:to_sym)
+
+      (array_methods & mutated_methods).each do |name|
+        define_method(name) do |*args, &block|
+          RSpec.deprecate "Mutating the `RSpec.configuration.formatters` array"
+          @array.__send__ name, *args, &block
+        end
+      end
+
+      (array_methods - mutated_methods).each do |name|
+        define_method(name) { |*args, &block| @array.__send__ name, *args, &block }
+      end
+
+    end
+  end
+end

data/lib/rspec/core/example.rb

@@ -85,6 +85,8 @@ module RSpec
 
       # @deprecated access options via metadata instead
       def options
+        RSpec.deprecate("`RSpec::Core::Example#options`",
+                        :replacement => "`RSpec::Core::Example#metadata`")
         @options
       end
 
@@ -112,7 +114,7 @@ module RSpec
               begin
                 run_before_each
                 @example_group_instance.instance_eval_with_args(self, &@example_block)
-              rescue Pending::PendingDeclaredInExample => e
+              rescue Pending::SkipDeclaredInExample => e
                 @pending_declared_in_example = e.message
               rescue Exception => e
                 set_exception(e)

data/lib/rspec/core/example_group.rb

@@ -49,139 +49,166 @@ module RSpec
         end
 
         delegate_to_metadata :described_class, :file_path
-        alias_method :display_name, :description
-        # @private
-        alias_method :describes, :described_class
 
         # @private
-        # @macro [attach] define_example_method
-        #   @param [String] name
-        #   @param [Hash] extra_options
-        #   @param [Block] implementation
-        #   @yield [Example] the example object
-        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})
-              examples << RSpec::Core::Example.new(self, desc, options, block)
-              examples.last
-            end
-          END_RUBY
+        def display_name
+          RSpec.deprecate('`RSpec::Core::ExampleGroup.display_name`',
+                          :replacement => "`RSpec::Core::ExampleGroup.description`")
+          description
         end
 
-        # Defines an example within a group.
-        # @example
-        #   example do
-        #   end
-        #
-        #   example "does something" do
-        #   end
-        #
-        #   example "does something", :with => 'additional metadata' do
-        #   end
-        #
-        #   example "does something" do |ex|
-        #     # ex is the Example object that evals this block
-        #   end
-        define_example_method :example
-        # Defines an example within a group.
-        # @example
-        define_example_method :it
-        # Defines an example within a group.
-        # This is here primarily for backward compatibility with early versions
-        # of RSpec which used `context` and `specify` instead of `describe` and
-        # `it`.
-        define_example_method :specify
-
-        # Shortcut to define an example with `:focus` => true
-        # @see example
-        define_example_method :focus,   :focused => true, :focus => true
-        # Shortcut to define an example with `:focus` => true
-        # @see example
-        define_example_method :focused, :focused => true, :focus => true
-        # Shortcut to define an example with `:focus` => true
-        # @see example
-        define_example_method :fit,     :focused => true, :focus => true
-
-        # 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'
-        # Shortcut to define an example with :pending => 'Temporarily disabled with xit'
-        # @see example
-        define_example_method :xit,      :pending => 'Temporarily disabled with xit'
-        # Shortcut to define an example with :pending => 'Temporarily disabled with xspecify'
-        # @see example
-        define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'
-
-        # Works like `alias_method :name, :example` with the added benefit of
-        # assigning default metadata to the generated example.
-        #
-        # @note Use with caution. This extends the language used in your
-        #   specs, but does not add any additional documentation.  We use this
-        #   in rspec to define methods like `focus` and `xit`, but we also add
-        #   docs for those methods.
-        def alias_example_to name, extra={}
-          (class << self; self; end).define_example_method name, extra
+        # @private
+        def describes
+          RSpec.deprecate('`RSpec::Core::ExampleGroup.describes`',
+                          :replacement => "`RSpec::Core::ExampleGroup.described_class`")
+          described_class
         end
+      end
 
-        # @private
-        # @macro [attach] define_nested_shared_group_method
-        #
-        #   @see SharedExampleGroup
-        def self.define_nested_shared_group_method(new_name, report_label=nil)
-          module_eval(<<-END_RUBY, __FILE__, __LINE__)
-            def #{new_name}(name, *args, &customization_block)
-              group = describe("#{report_label || "it should behave like"} \#{name}") do
-                find_and_eval_shared("examples", name, *args, &customization_block)
-              end
-              group.metadata[:shared_group_name] = name
-              group
+      # @private
+      # @macro [attach] define_example_method
+      #   @param [String] name
+      #   @param [Hash] extra_options
+      #   @param [Block] implementation
+      #   @yield [Example] the example object
+      def self.define_example_method(name, extra_options={})
+        module_eval(<<-END_RUBY, __FILE__, __LINE__)
+          def self.#{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
-          END_RUBY
-        end
+            options = build_metadata_hash_from(args)
+            options.update(:pending => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
+            # Backport from RSpec 3 to assist with upgrading
+            options.update(:pending => options[:skip]) if options[:skip]
+            options.update(#{extra_options.inspect})
+            examples << RSpec::Core::Example.new(self, desc, options, block)
+            examples.last
+          end
+        END_RUBY
+      end
+
+      # Defines an example within a group.
+      # @example
+      #   example do
+      #   end
+      #
+      #   example "does something" do
+      #   end
+      #
+      #   example "does something", :with => 'additional metadata' do
+      #   end
+      #
+      #   example "does something" do |ex|
+      #     # ex is the Example object that evals this block
+      #   end
+      define_example_method :example
+      # Defines an example within a group.
+      # @example
+      define_example_method :it
+      # Defines an example within a group.
+      # This is here primarily for backward compatibility with early versions
+      # of RSpec which used `context` and `specify` instead of `describe` and
+      # `it`.
+      define_example_method :specify
+
+      # Shortcut to define an example with `:focus` => true
+      # @see example
+      define_example_method :focus,   :focused => true, :focus => true
+      # Shortcut to define an example with `:focus` => true
+      # @see example
+      define_example_method :fit,     :focused => true, :focus => true
+
+      # 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'
+      # Shortcut to define an example with :pending => 'Temporarily disabled with xit'
+      # @see example
+      define_example_method :xit,      :pending => 'Temporarily disabled with xit'
+      # Shortcut to define an example with :pending => 'Temporarily disabled with xspecify'
+      # @see example
+      define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'
+
+      # Shortcut to define an example with `:focus` => true
+      # @see example
+      def self.focused(desc=nil, *args, &block)
+        RSpec.deprecate("`RSpec::Core::ExampleGroup.focused`",
+                        :replacement => "`RSpec::Core::ExampleGroup.focus`")
+
+        metadata = Hash === args.last ? args.pop : {}
+        metadata.merge!(:focus => true, :focused => true)
+        args << metadata
+
+        example(desc, *args, &block)
+      end
+
+      # Works like `alias_method :name, :example` with the added benefit of
+      # assigning default metadata to the generated example.
+      #
+      # @note Use with caution. This extends the language used in your
+      #   specs, but does not add any additional documentation.  We use this
+      #   in rspec to define methods like `focus` and `xit`, but we also add
+      #   docs for those methods.
+      def self.alias_example_to name, extra={}
+        RSpec.deprecate("`RSpec::Core::ExampleGroup.alias_example_to`",
+                        :replacement => "`RSpec::Core::Configuration#alias_example_to`")
+        define_example_method name, extra
+      end
 
-        # Generates a nested example group and includes the shared content
-        # mapped to `name` in the nested group.
-        define_nested_shared_group_method :it_behaves_like, "behaves like"
-        # Generates a nested example group and includes the shared content
-        # mapped to `name` in the nested group.
-        define_nested_shared_group_method :it_should_behave_like
+      # @private
+      # @macro [attach] define_nested_shared_group_method
+      #
+      #   @see SharedExampleGroup
+      def self.define_nested_shared_group_method(new_name, report_label=nil)
+        module_eval(<<-END_RUBY, __FILE__, __LINE__)
+          def self.#{new_name}(name, *args, &customization_block)
+            group = describe("#{report_label || "it should behave like"} \#{name}") do
+              find_and_eval_shared("examples", name, *args, &customization_block)
+            end
+            group.metadata[:shared_group_name] = name
+            group
+          end
+        END_RUBY
+      end
 
-        # Works like `alias_method :name, :it_behaves_like` with the added
-        # benefit of assigning default metadata to the generated example.
-        #
-        # @note Use with caution. This extends the language used in your
-        #   specs, but does not add any additional documentation.  We use this
-        #   in rspec to define `it_should_behave_like` (for backward
-        #   compatibility), but we also add docs for that method.
-        def alias_it_behaves_like_to name, *args, &block
-          (class << self; self; end).define_nested_shared_group_method name, *args, &block
-        end
+      # Generates a nested example group and includes the shared content
+      # mapped to `name` in the nested group.
+      define_nested_shared_group_method :it_behaves_like, "behaves like"
+      # Generates a nested example group and includes the shared content
+      # mapped to `name` in the nested group.
+      define_nested_shared_group_method :it_should_behave_like
+
+      # Works like `alias_method :name, :it_behaves_like` with the added
+      # benefit of assigning default metadata to the generated example.
+      #
+      # @note Use with caution. This extends the language used in your
+      #   specs, but does not add any additional documentation.  We use this
+      #   in rspec to define `it_should_behave_like` (for backward
+      #   compatibility), but we also add docs for that method.
+      def self.alias_it_behaves_like_to name, *args, &block
+        RSpec.deprecate("`RSpec::Core::ExampleGroup.alias_it_behaves_like_to`",
+                        :replacement => "`RSpec::Core::Configuration#alias_it_behaves_like_to`")
+        define_nested_shared_group_method name, *args, &block
       end
 
       # Includes shared content mapped to `name` directly in the group in which
@@ -296,8 +323,18 @@ WARNING
       def self.describe(*args, &example_group_block)
         @_subclass_count ||= 0
         @_subclass_count += 1
+
+        if Symbol === args.first || Hash === args.first
+          description_arg_behavior_changing_in_rspec_3 = DescriptionBehaviorChange.new(
+            args.first, CallerFilter.first_non_rspec_line
+          )
+        end
+
         args << {} unless args.last.is_a?(Hash)
-        args.last.update(:example_group_block => example_group_block)
+        args.last.update(
+          :example_group_block => example_group_block,
+          :description_arg_behavior_changing_in_rspec_3 => description_arg_behavior_changing_in_rspec_3
+        )
 
         # TODO 2010-05-05: Because we don't know if const_set is thread-safe
         child = const_set(
@@ -308,6 +345,18 @@ WARNING
         child
       end
 
+      DescriptionBehaviorChange = Struct.new(:arg, :call_site) do
+        def warning
+          <<-EOS.gsub(/^\s+\|/, '')
+            |The semantics of `describe <a #{arg.class.name}>` are changing in RSpec 3. In RSpec 2,
+            |this would be treated as metadata, but as the first `describe` argument,
+            |this will be treated as the described object in RSpec 3. If you want this
+            |to be treated as metadata, pass a description as the first argument.
+            |(Example group defined at #{call_site})
+          EOS
+        end
+      end
+
       class << self
         alias_method :context, :describe
       end

data/lib/rspec/core/filter_manager.rb

@@ -66,23 +66,51 @@ module RSpec
     # @see Configuration#filter_run_including
     # @see Configuration#filter_run_excluding
     class FilterManager
-      DEFAULT_EXCLUSIONS = {
-        :if     => lambda { |value| !value },
-        :unless => lambda { |value| value }
-      }
+      class << self
+        def const_missing(name)
+          case name
+          when :DEFAULT_EXCLUSIONS
+            RSpec.deprecate("RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS is deprecated")
+            default_exclusions
+          when :STANDALONE_FILTERS
+            RSpec.deprecate("RSpec::Core::FilterManager::STANDALONE_FILTERS is deprecated")
+            standalone_filters
+          else
+            super
+          end
+        end
+
+        # @private
+        def default_exclusions
+          @default_exclusions ||= {
+            :if     => lambda { |value| !value },
+            :unless => lambda { |value| value }
+          }
+        end
 
-      STANDALONE_FILTERS = [:locations, :line_numbers, :full_description]
+        # @private
+        def standalone_filters
+          @standalone_filters ||= [:locations, :line_numbers, :full_description]
+        end
+      end
 
       module Describable
         PROC_HEX_NUMBER = /0x[0-9a-f]+\s?@/
         PROJECT_DIR = File.expand_path('.')
 
         def description
-          reject { |k, v| RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS[k] == v }.inspect.gsub(PROC_HEX_NUMBER, '').gsub(PROJECT_DIR, '.').gsub(' (lambda)','').gsub('__is_lambda__=true','')
+          reject { |k, v| RSpec::Core::FilterManager.default_exclusions[k] == v }.inspect.
+            gsub(PROC_HEX_NUMBER, '').gsub(PROJECT_DIR, '.').gsub(' (lambda)','').gsub('__is_lambda__=true','')
         end
 
         def empty_without_conditional_filters?
-          reject { |k, v| RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS[k] == v }.empty?
+          RSpec.deprecate("(inclusion_filter | exclusion_filter)#empty_without_conditional_filters? is deprecated")
+          rules_empty?
+        end
+
+        # @private
+        def rules_empty?
+          reject { |k, v| RSpec::Core::FilterManager.default_exclusions[k] == v }.empty?
         end
       end
 
@@ -115,7 +143,7 @@ module RSpec
       attr_reader :exclusions, :inclusions
 
       def initialize
-        @exclusions = DEFAULT_EXCLUSIONS.dup.extend(Describable)
+        @exclusions = self.class.default_exclusions.dup.extend(Describable)
         @inclusions = {}.extend(Describable)
         extend(BackwardCompatibility)
       end
@@ -131,7 +159,7 @@ module RSpec
       end
 
       def empty?
-        inclusions.empty? && exclusions.empty_without_conditional_filters?
+        inclusions.empty? && exclusions.rules_empty?
       end
 
       def prune(examples)
@@ -143,6 +171,11 @@ module RSpec
       end
 
       def exclude!(*args)
+        RSpec.deprecate("FilterManager#exclude! is deprecated. Use FilterManager#exclude_only")
+        exclude_only(*args)
+      end
+
+      def exclude_only(*args)
         replace(@exclusions, @inclusions, *args)
       end
 
@@ -159,6 +192,11 @@ module RSpec
       end
 
       def include!(*args)
+        RSpec.deprecate("FilterManager#include! is deprecated. Use FilterManager#include_only")
+        include_only(*args)
+      end
+
+      def include_only(*args)
         unless_standalone(*args) { replace(@inclusions, @exclusions, *args) }
       end
 
@@ -196,7 +234,7 @@ module RSpec
       end
 
       def is_standalone_filter?(filter)
-        STANDALONE_FILTERS.any? {|key| filter.has_key?(key)}
+        self.class.standalone_filters.any? {|key| filter.has_key?(key)}
       end
     end
   end