opal-rspec 0.4.3 → 0.5.0.beta1

data/{vendor_lib/rspec/matchers/matcher.rb → rspec-expectations/lib/rspec/matchers/dsl.rb}

@@ -1,8 +1,18 @@
-require 'set'
-
 module RSpec
   module Matchers
+    # Defines the custom matcher DSL.
     module DSL
+      # Defines a custom matcher.
+      # @see RSpec::Matchers
+      def define(name, &declarations)
+        define_method name do |*expected|
+          RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected)
+        end
+      end
+      alias_method :matcher, :define
+
+      RSpec.configure { |c| c.extend self } if RSpec.respond_to?(:configure)
+
       # Contains the methods that are available from within the
       # `RSpec::Matchers.define` DSL for creating custom matchers.
       module Macros
@@ -12,9 +22,6 @@ module RSpec
         # passes. Similarly, when the matcher is passed to `expect(...).not_to` and the
         # block returns `false`, then the expectation passes.
         #
-        # Use `match_for_should` when used in conjunction with
-        # `match_for_should_not`.
-        #
         # @example
         #
         #     RSpec::Matchers.define :be_even do
@@ -39,7 +46,6 @@ module RSpec
             end
           end
         end
-        alias match_for_should match
 
         # Use this to define the block for a negative expectation (`expect(...).not_to`)
         # when the positive and negative forms require different handling. This
@@ -47,7 +53,7 @@ module RSpec
         # asynchronous processes that require different timeouts.
         #
         # @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
-        def match_for_should_not(&match_block)
+        def match_when_negated(&match_block)
           define_user_override(:does_not_match?, match_block) do |actual|
             @actual = actual
             super(*actual_arg_for(match_block))
@@ -90,13 +96,13 @@ module RSpec
         #     RSpec::Matchers.define :have_strength do |expected|
         #       match { your_match_logic }
         #
-        #       failure_message_for_should do |actual|
+        #       failure_message do |actual|
         #         "Expected strength of #{expected}, but had #{actual.strength}"
         #       end
         #     end
         #
         # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
-        def failure_message_for_should(&definition)
+        def failure_message(&definition)
           define_user_override(__method__, definition)
         end
 
@@ -109,13 +115,13 @@ module RSpec
         #     RSpec::Matchers.define :have_strength do |expected|
         #       match { your_match_logic }
         #
-        #       failure_message_for_should_not do |actual|
+        #       failure_message_when_negated do |actual|
         #         "Expected not to have strength of #{expected}, but did"
         #       end
         #     end
         #
         # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
-        def failure_message_for_should_not(&definition)
+        def failure_message_when_negated(&definition)
           define_user_override(__method__, definition)
         end
 
@@ -143,10 +149,21 @@ module RSpec
           define_method(:diffable?) { true }
         end
 
+        # Declares that the matcher can be used in a block expectation.
+        # Users will not be able to use your matcher in a block
+        # expectation without declaring this.
+        # (e.g. `expect { do_something }.to matcher`).
+        def supports_block_expectations
+          define_method(:supports_block_expectations?) { true }
+        end
+
         # Convenience for defining methods on this matcher to create a fluent
         # interface. The trick about fluent interfaces is that each method must
         # return self in order to chain methods together. `chain` handles that
-        # for you.
+        # for you. If the method is invoked and the
+        # `include_chain_clauses_in_custom_matcher_descriptions` config option
+        # hash been enabled, the chained method name and args will be added to the
+        # default description and failure message.
         #
         # @example
         #
@@ -164,6 +181,7 @@ module RSpec
         def chain(name, &definition)
           define_user_override(name, definition) do |*args, &block|
             super(*args, &block)
+            @chained_method_clauses.push([name, args])
             self
           end
         end
@@ -192,6 +210,34 @@ module RSpec
           our_def ||= lambda { super(*actual_arg_for(user_def)) }
           define_method(method_name, &our_def)
         end
+
+        # Defines deprecated macro methods from RSpec 2 for backwards compatibility.
+        # @deprecated Use the methods from {Macros} instead.
+        module Deprecated
+          # @deprecated Use {Macros#match} instead.
+          def match_for_should(&definition)
+            RSpec.deprecate("`match_for_should`", :replacement => "`match`")
+            match(&definition)
+          end
+
+          # @deprecated Use {Macros#match_when_negated} instead.
+          def match_for_should_not(&definition)
+            RSpec.deprecate("`match_for_should_not`", :replacement => "`match_when_negated`")
+            match_when_negated(&definition)
+          end
+
+          # @deprecated Use {Macros#failure_message} instead.
+          def failure_message_for_should(&definition)
+            RSpec.deprecate("`failure_message_for_should`", :replacement => "`failure_message`")
+            failure_message(&definition)
+          end
+
+          # @deprecated Use {Macros#failure_message_when_negated} instead.
+          def failure_message_for_should_not(&definition)
+            RSpec.deprecate("`failure_message_for_should_not`", :replacement => "`failure_message_when_negated`")
+            failure_message_when_negated(&definition)
+          end
+        end
       end
 
       # Defines default implementations of the matcher
@@ -199,6 +245,8 @@ module RSpec
       # override any of these using the {RSpec::Matchers::DSL::Macros Macros} methods
       # from within an `RSpec::Matchers.define` block.
       module DefaultImplementations
+        include BuiltIn::BaseMatcher::DefaultFailureMessages
+
         # @api private
         # Used internally by objects returns by `should` and `should_not`.
         def diffable?
@@ -207,17 +255,28 @@ module RSpec
 
         # The default description.
         def description
-          "#{name_to_sentence}#{expected_to_sentence}"
+          "#{name_to_sentence}#{to_sentence expected}#{chained_method_clause_sentences}"
+        end
+
+        # Matchers do not support block expectations by default. You
+        # must opt-in.
+        def supports_block_expectations?
+          false
         end
 
-        # The default failure message for positive expectations.
-        def failure_message_for_should
-          "expected #{actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"
+        # Most matchers do not expect call stack jumps.
+        def expects_call_stack_jump?
+          false
         end
 
-        # The default failure message for negative expectations.
-        def failure_message_for_should_not
-          "expected #{actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
+      private
+
+        def chained_method_clause_sentences
+          return '' unless Expectations.configuration.include_chain_clauses_in_custom_matcher_descriptions?
+
+          @chained_method_clauses.map do |(method_name, method_args)|
+            " #{split_words(method_name)}#{to_sentence(method_args)}"
+          end.join
         end
       end
 
@@ -235,17 +294,28 @@ module RSpec
         # Converts matcher name and expected args to an English expresion.
         include RSpec::Matchers::Pretty
 
+        # Supports the matcher composability features of RSpec 3+.
+        include Composable
+
         # Makes the macro methods available to an `RSpec::Matchers.define` block.
         extend Macros
+        extend Macros::Deprecated
+
+        # Exposes the value being matched against -- generally the object
+        # object wrapped by `expect`.
+        attr_reader :actual
 
-        attr_reader   :expected, :actual, :rescued_exception
-        attr_accessor :matcher_execution_context
+        # Exposes the exception raised during the matching by `match_unless_raises`.
+        # Could be useful to extract details for a failure message.
+        attr_reader :rescued_exception
 
         # @api private
-        def initialize(name, declarations, *expected)
+        def initialize(name, declarations, matcher_execution_context, *expected)
           @name     = name
           @actual   = nil
-          @expected = expected
+          @expected_as_array = expected
+          @matcher_execution_context = matcher_execution_context
+          @chained_method_clauses = []
 
           class << self
             # See `Macros#define_user_override` above, for an explanation.
@@ -254,6 +324,24 @@ module RSpec
           end.class_exec(*expected, &declarations)
         end
 
+        # Provides the expected value. This will return an array if
+        # multiple arguments were passed to the matcher; otherwise it
+        # will return a single value.
+        # @see #expected_as_array
+        def expected
+          if expected_as_array.size == 1
+            expected_as_array[0]
+          else
+            expected_as_array
+          end
+        end
+
+        # Returns the expected value as an an array. This exists primarily
+        # to aid in upgrading from RSpec 2.x, since in RSpec 2, `expected`
+        # always returned an array.
+        # @see #expected
+        attr_reader :expected_as_array
+
         # Adds the name (rather than a cryptic hex number)
         # so we can identify an instance of
         # the matcher in error messages (e.g. for `NoMethodError`)
@@ -263,16 +351,16 @@ module RSpec
 
         if RUBY_VERSION.to_f >= 1.9
           # Indicates that this matcher responds to messages
-          # from the `matcher_execution_context` as well.
+          # from the `@matcher_execution_context` as well.
           # Also, supports getting a method object for such methods.
           def respond_to_missing?(method, include_private=false)
-            super || matcher_execution_context.respond_to?(method, include_private)
+            super || @matcher_execution_context.respond_to?(method, include_private)
           end
         else # for 1.8.7
           # Indicates that this matcher responds to messages
-          # from the `matcher_execution_context` as well.
+          # from the `@matcher_execution_context` as well.
           def respond_to?(method, include_private=false)
-            super || matcher_execution_context.respond_to?(method, include_private)
+            super || @matcher_execution_context.respond_to?(method, include_private)
           end
         end
 
@@ -283,14 +371,14 @@ module RSpec
         end
 
         # Takes care of forwarding unhandled messages to the
-        # `matcher_execution_context` (typically the current
+        # `@matcher_execution_context` (typically the current
         # running `RSpec::Core::Example`). This is needed by
         # rspec-rails so that it can define matchers that wrap
         # Rails' test helper methods, but it's also a useful
         # feature in its own right.
         def method_missing(method, *args, &block)
-          if matcher_execution_context.respond_to?(method)
-            matcher_execution_context.__send__ method, *args, &block
+          if @matcher_execution_context.respond_to?(method)
+            @matcher_execution_context.__send__ method, *args, &block
           else
             super(method, *args, &block)
           end
@@ -299,3 +387,5 @@ module RSpec
     end
   end
 end
+
+RSpec::Matchers.extend RSpec::Matchers::DSL

data/{vendor_lib → rspec-expectations/lib}/rspec/matchers/generated_descriptions.rb

@@ -1,17 +1,24 @@
 module RSpec
   module Matchers
     class << self
-      attr_accessor :last_matcher, :last_should
+      # @private
+      attr_accessor :last_matcher, :last_expectation_handler
     end
 
+    # @api private
+    # Used by rspec-core to clear the state used to generate
+    # descriptions after an example.
     def self.clear_generated_description
       self.last_matcher = nil
-      self.last_should = nil
+      self.last_expectation_handler = nil
     end
 
+    # @api private
+    # Generates an an example description based on the last expectation.
+    # Used by rspec-core's one-liner syntax.
     def self.generated_description
-      return nil if last_should.nil?
-      "#{last_should.to_s.gsub('_',' ')} #{last_description}"
+      return nil if last_expectation_handler.nil?
+      "#{last_expectation_handler.verb} #{last_description}"
     end
 
   private
@@ -20,11 +27,11 @@ module RSpec
       last_matcher.respond_to?(:description) ? last_matcher.description : <<-MESSAGE
 When you call a matcher in an example without a String, like this:
 
-specify { object.should matcher }
+specify { expect(object).to matcher }
 
 or this:
 
-it { should matcher }
+it { is_expected.to matcher }
 
 RSpec expects the matcher to have a #description method. You should either
 add a String to the example this matcher is being used in, or give it a

data/rspec-expectations/lib/rspec/matchers/matcher_delegator.rb

@@ -0,0 +1,33 @@
+module RSpec
+  module Matchers
+    # Provides the necessary plumbing to wrap a matcher with a decorator.
+    # @private
+    class MatcherDelegator
+      include Composable
+      attr_reader :base_matcher
+
+      def initialize(base_matcher)
+        @base_matcher = base_matcher
+      end
+
+      def method_missing(*args, &block)
+        base_matcher.__send__(*args, &block)
+      end
+
+      if ::RUBY_VERSION.to_f > 1.8
+        def respond_to_missing?(name, include_all=false)
+          super || base_matcher.respond_to?(name, include_all)
+        end
+      else
+        def respond_to?(name, include_all=false)
+          super || base_matcher.respond_to?(name, include_all)
+        end
+      end
+
+      def initialize_copy(other)
+        @base_matcher = @base_matcher.clone
+        super
+      end
+    end
+  end
+end

data/rspec-expectations/lib/rspec/matchers/matcher_protocol.rb

@@ -0,0 +1,99 @@
+module RSpec
+  module Matchers
+    # rspec-expectations can work with any matcher object that implements this protocol.
+    #
+    # @note This class is not loaded at runtime by rspec-expectations. It exists
+    #   purely to provide documentation for the matcher protocol.
+    class MatcherProtocol
+      # @!group Required Methods
+
+      # @method matches?
+      # @param actual [Object] The object being matched against.
+      # @yield For an expression like `expect(x).to matcher do...end`, the `do/end`
+      #   block binds to `to`. It passes that block, if there is one, on to this method.
+      # @return [Boolean] true if this matcher matches the provided object.
+
+      # @method failure_message
+      # This will only be called if {#matches?} returns false.
+      # @return [String] Explanation for the failure.
+
+      # @!endgroup
+
+      # @!group Optional Methods
+
+      # @method does_not_match?
+      # In a negative expectation such as `expect(x).not_to foo`, RSpec will
+      # call `foo.does_not_match?(x)` if this method is defined. If it's not
+      # defined it will fall back to using `!foo.matches?(x)`. This allows you
+      # to provide custom logic for the negative case.
+      #
+      # @param actual [Object] The object being matched against.
+      # @yield For an expression like `expect(x).not_to matcher do...end`, the `do/end`
+      #   block binds to `not_to`. It passes that block, if there is one, on to this method.
+      # @return [Boolean] true if this matcher does not match the provided object.
+
+      # @method failure_message_when_negated
+      # This will only be called when a negative match fails.
+      # @return [String] Explanation for the failure.
+      # @note This method is listed as optional because matchers do not have to
+      #   support negation. But if your matcher does support negation, this is a
+      #   required method -- otherwise, you'll get a `NoMethodError`.
+
+      # @method description
+      # The description is used for two things:
+      #
+      #   * When using RSpec's one-liner syntax
+      #     (e.g. `it { is_expected.to matcher }`), the description
+      #     is used to generate the example's doc string since you
+      #     have not provided one.
+      #   * In a composed matcher expression, the description is used
+      #     as part of the failure message (and description) of the outer
+      #     matcher.
+      #
+      # @return [String] Description of the matcher.
+
+      # @method supports_block_expectations?
+      # Indicates that this matcher can be used in a block expectation expression,
+      # such as `expect { foo }.to raise_error`. Generally speaking, this is
+      # only needed for matchers which operate on a side effect of a block, rather
+      # than on a particular object.
+      # @return [Boolean] true if this matcher can be used in block expressions.
+      # @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @method expects_call_stack_jump?
+      # Indicates that when this matcher is used in a block expectation
+      # expression, it expects the block to use a ruby construct that causes
+      # a call stack jump (such as raising an error or throwing a symbol).
+      #
+      # This is used internally for compound block expressions, as matchers
+      # which expect call stack jumps must be treated with care to work properly.
+      #
+      # @return [Boolean] true if the matcher expects a call stack jump
+      #
+      # @note This method is very rarely used or needed.
+      # @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @method diffable?
+      # @return [Boolean] true if `actual` and `expected` can be diffed.
+      # Indicates that this matcher provides `actual` and `expected` attributes,
+      # and that the values returned by these can be usefully diffed, which can
+      # be included in the output.
+
+      # @method actual
+      # @return [String, Object] If an object (rather than a string) is provided,
+      #   RSpec will use the `pp` library to convert it to multi-line output in
+      #   order to diff.
+      # The actual value for the purposes of a diff.
+      # @note This method is required if `diffable?` returns true.
+
+      # @method expected
+      # @return [String, Object] If an object (rather than a string) is provided,
+      #   RSpec will use the `pp` library to convert it to multi-line output in
+      #   order to diff.
+      # The expected value for the purposes of a diff.
+      # @note This method is required if `diffable?` returns true.
+
+      # @!endgroup
+    end
+  end
+end

data/rspec-expectations/lib/rspec/matchers/pretty.rb

@@ -0,0 +1,77 @@
+module RSpec
+  module Matchers
+    # @api private
+    # Contains logic to facilitate converting ruby symbols and
+    # objects to english phrases.
+    module Pretty
+      # @api private
+      # Converts a symbol into an english expression.
+      def split_words(sym)
+        sym.to_s.gsub(/_/, ' ')
+      end
+      module_function :split_words
+
+      # @api private
+      # Converts a collection of objects into an english expression.
+      def to_sentence(words)
+        return " #{words.inspect}" if !words || Struct === words
+        words = Array(words).map { |w| to_word(w) }
+        case words.length
+        when 0
+          ""
+        when 1
+          " #{words[0]}"
+        when 2
+          " #{words[0]} and #{words[1]}"
+        else
+          " #{words[0...-1].join(', ')}, and #{words[-1]}"
+        end
+      end
+
+      # @api private
+      # Converts the given item to string suitable for use in a list expression.
+      def to_word(item)
+        is_matcher_with_description?(item) ? item.description : item.inspect
+      end
+
+      # @private
+      # Provides an English expression for the matcher name.
+      def name_to_sentence
+        split_words(name)
+      end
+
+      # @api private
+      # Provides a name for the matcher.
+      def name
+        defined?(@name) ? @name : underscore(self.class.name.split("::").last)
+      end
+
+      # @private
+      # Borrowed from ActiveSupport
+      def underscore(camel_cased_word)
+        word = camel_cased_word.to_s.dup
+        word.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+    private
+
+      def is_matcher_with_description?(object)
+        RSpec::Matchers.is_a_matcher?(object) && object.respond_to?(:description)
+      end
+
+      # `{ :a => 5, :b => 2 }.inspect` produces:
+      #    {:a=>5, :b=>2}
+      # ...but it looks much better as:
+      #    {:a => 5, :b => 2}
+      #
+      # This is idempotent and safe to run on a string multiple times.
+      def improve_hash_formatting(inspect_string)
+        inspect_string.gsub(/(\S)=>(\S)/, '\1 => \2')
+      end
+    end
+  end
+end