module Mocha::ParameterMatchers
Used as parameters for {Expectation#with} to restrict the parameter values which will match the expectation. Can be nested.
Public Instance Methods
Matches if matcher
does not match.
@param [Base] matcher matcher whose logic to invert. @return [Not] parameter matcher.
@see Expectation#with
@example Actual parameter does not include the value 1
.
object = mock() object.expects(:method_1).with(Not(includes(1))) object.method_1([0, 2, 3]) # no error raised
@example Actual parameter does include the value 1
.
object = mock() object.expects(:method_1).with(Not(includes(1))) object.method_1([0, 1, 2, 3]) # error raised, because method_1 was not called with object not including 1
# File lib/mocha/parameter_matchers/not.rb, line 24 def Not(matcher) # rubocop:disable Naming/MethodName Not.new(matcher) end
Matches if all matchers
match.
@param [*Array<Base>] matchers parameter matchers. @return [AllOf] parameter matcher.
@see Expectation#with
@example All parameter matchers match.
object = mock() object.expects(:method_1).with(all_of(includes(1), includes(3))) object.method_1([1, 3]) # no error raised
@example One of the parameter matchers does not match.
object = mock() object.expects(:method_1).with(all_of(includes(1), includes(3))) object.method_1([1, 2]) # error raised, because method_1 was not called with object including 1 and 3
# File lib/mocha/parameter_matchers/all_of.rb, line 23 def all_of(*matchers) AllOf.new(*matchers) end
Matches if any matchers
match.
@param [*Array<Base>] matchers parameter matchers. @return [AnyOf] parameter matcher.
@see Expectation#with
@example One parameter matcher matches.
object = mock() object.expects(:method_1).with(any_of(1, 3)) object.method_1(1) # no error raised
@example The other parameter matcher matches.
object = mock() object.expects(:method_1).with(any_of(1, 3)) object.method_1(3) # no error raised
@example Neither parameter matcher matches.
object = mock() object.expects(:method_1).with(any_of(1, 3)) object.method_1(2) # error raised, because method_1 was not called with 1 or 3
# File lib/mocha/parameter_matchers/any_of.rb, line 29 def any_of(*matchers) AnyOf.new(*matchers) end
Matches any parameters. This is used as the default for a newly built expectation.
@return [AnyParameters] parameter matcher.
@see Expectation#with
@example Any parameters will match.
object = mock() object.expects(:method_1).with(any_parameters) object.method_1(1, 2, 3, 4) # no error raised object = mock() object.expects(:method_1).with(any_parameters) object.method_1(5, 6, 7, 8, 9, 0) # no error raised
# File lib/mocha/parameter_matchers/any_parameters.rb, line 21 def any_parameters AnyParameters.new end
Matches any object.
@return [Anything] parameter matcher.
@see Expectation#with
@example Any object will match.
object = mock() object.expects(:method_1).with(anything) object.method_1('foo') object.method_1(789) object.method_1(:bar) # no error raised
# File lib/mocha/parameter_matchers/anything.rb, line 18 def anything Anything.new end
Matches any Object
equalling value
.
@param [Object] value expected value. @return [Equals] parameter matcher.
@see Expectation#with
@see Object#==
@example Actual parameter equals expected parameter.
object = mock() object.expects(:method_1).with(equals(2)) object.method_1(2) # no error raised
@example Actual parameter does not equal expected parameter.
object = mock() object.expects(:method_1).with(equals(2)) object.method_1(3) # error raised, because method_1 was not called with an +Object+ that equals 2
# File lib/mocha/parameter_matchers/equals.rb, line 24 def equals(value) Equals.new(value) end
Matches a URI without regard to the ordering of parameters in the query string.
@param [String] uri URI to match. @return [EquivalentUri] parameter matcher.
@see Expectation#with
@example Actual URI is equivalent.
object = mock() object.expects(:method_1).with(equivalent_uri('http://example.com/foo?a=1&b=2)) object.method_1('http://example.com/foo?b=2&a=1') # no error raised
@example Actual URI is not equivalent.
object = mock() object.expects(:method_1).with(equivalent_uri('http://example.com/foo?a=1&b=2)) object.method_1('http://example.com/foo?a=1&b=3') # error raised, because the query parameters were different
# File lib/mocha/parameter_matchers/equivalent_uri.rb, line 26 def equivalent_uri(uri) EquivalentUri.new(uri) end
Matches Hash
containing all entries
.
@param [Hash] entries expected Hash
entries. @return [HasEntries] parameter matcher.
@see Expectation#with
@example Actual parameter contains all expected entries.
object = mock() object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2)) object.method_1('key_1' => 1, 'key_2' => 2, 'key_3' => 3) # no error raised
@example Actual parameter does not contain all expected entries.
object = mock() object.expects(:method_1).with(has_entries('key_1' => 1, 'key_2' => 2)) object.method_1('key_1' => 1, 'key_2' => 99) # error raised, because method_1 was not called with Hash containing entries: 'key_1' => 1, 'key_2' => 2
# File lib/mocha/parameter_matchers/has_entries.rb, line 26 def has_entries(entries) # rubocop:disable Naming/PredicateName HasEntries.new(entries) end
Matches Hash
containing entry with key
and value
.
@overload def has_entry
(key, value)
@param [Object] key key for entry. @param [Object] value value for entry.
@overload def has_entry
(single_entry_hash)
@param [Hash] single_entry_hash +Hash+ with single entry. @raise [ArgumentError] if +single_entry_hash+ does not contain exactly one entry.
@return [HasEntry] parameter matcher.
@see Expectation#with
@example Actual parameter contains expected entry supplied as key and value.
object = mock() object.expects(:method_1).with(has_entry('key_1', 1)) object.method_1('key_1' => 1, 'key_2' => 2) # no error raised
@example Actual parameter contains expected entry supplied as Hash
entry.
object = mock() object.expects(:method_1).with(has_entry('key_1' => 1)) object.method_1('key_1' => 1, 'key_2' => 2) # no error raised
@example Actual parameter does not contain expected entry supplied as key and value.
object = mock() object.expects(:method_1).with(has_entry('key_1', 1)) object.method_1('key_1' => 2, 'key_2' => 1) # error raised, because method_1 was not called with Hash containing entry: 'key_1' => 1
@example Actual parameter does not contain expected entry supplied as Hash
entry.
object = mock() object.expects(:method_1).with(has_entry('key_1' => 1)) object.method_1('key_1' => 2, 'key_2' => 1) # error raised, because method_1 was not called with Hash containing entry: 'key_1' => 1
# File lib/mocha/parameter_matchers/has_entry.rb, line 43 def has_entry(*options) # rubocop:disable Naming/PredicateName case options.length when 0 raise ArgumentError, 'No arguments. Expecting at least one.' when 1 key, value = parse_option(options[0]) when 2 key, value = options else raise ArgumentError, 'Too many arguments; use either a single argument (must be a Hash) or two arguments (a key and a value).' end HasEntry.new(key, value) end
Matches Hash
containing key
.
@param [Object] key expected key. @return [HasKey] parameter matcher.
@see Expectation#with
@example Actual parameter contains entry with expected key.
object = mock() object.expects(:method_1).with(has_key('key_1')) object.method_1('key_1' => 1, 'key_2' => 2) # no error raised
@example Actual parameter does not contain entry with expected key.
object = mock() object.expects(:method_1).with(has_key('key_1')) object.method_1('key_2' => 2) # error raised, because method_1 was not called with Hash containing key: 'key_1'
# File lib/mocha/parameter_matchers/has_key.rb, line 24 def has_key(key) # rubocop:disable Naming/PredicateName HasKey.new(key) end
Matches Hash
containing keys
.
@param [*Array<Object>] keys expected keys. @return [HasKeys] parameter matcher.
@see Expectation#with
@example Actual parameter contains entry with expected keys.
object = mock() object.expects(:method_1).with(has_keys(:key_1, :key_2)) object.method_1(:key_1 => 1, :key_2 => 2, :key_3 => 3) # no error raised
@example Actual parameter does not contain all expected keys.
object = mock() object.expects(:method_1).with(has_keys(:key_1, :key_2)) object.method_1(:key_2 => 2) # error raised, because method_1 was not called with Hash containing key: :key_1
# File lib/mocha/parameter_matchers/has_keys.rb, line 24 def has_keys(*keys) # rubocop:disable Naming/PredicateName HasKeys.new(*keys) end
Matches Hash
containing value
.
@param [Object] value expected value. @return [HasValue] parameter matcher.
@see Expectation#with
@example Actual parameter contains entry with expected value.
object = mock() object.expects(:method_1).with(has_value(1)) object.method_1('key_1' => 1, 'key_2' => 2) # no error raised
@example Actual parameter does not contain entry with expected value.
object = mock() object.expects(:method_1).with(has_value(1)) object.method_1('key_2' => 2) # error raised, because method_1 was not called with Hash containing value: 1
# File lib/mocha/parameter_matchers/has_value.rb, line 24 def has_value(value) # rubocop:disable Naming/PredicateName HasValue.new(value) end
Matches any object that responds with true
to +include?(item)+ for all items.
@param [*Array] items expected items. @return [Includes] parameter matcher.
@see Expectation#with
@example Actual parameter includes all items.
object = mock() object.expects(:method_1).with(includes('foo', 'bar')) object.method_1(['foo', 'bar', 'baz']) # no error raised
@example Actual parameter does not include all items.
object.method_1(['foo', 'baz']) # error raised, because ['foo', 'baz'] does not include 'bar'.
@example Actual parameter includes item which matches nested matcher.
object = mock() object.expects(:method_1).with(includes(has_key(:key))) object.method_1(['foo', 'bar', {:key => 'baz'}]) # no error raised
@example Actual parameter does not include item matching nested matcher.
object.method_1(['foo', 'bar', {:other_key => 'baz'}]) # error raised, because no element matches `has_key(:key)` matcher
@example Actual parameter is a String including substring.
object = mock() object.expects(:method_1).with(includes('bar')) object.method_1('foobarbaz') # no error raised
@example Actual parameter is a String not including substring.
object.method_1('foobaz') # error raised, because 'foobaz' does not include 'bar'
@example Actual parameter is a Hash
including the given key.
object = mock() object.expects(:method_1).with(includes(:bar)) object.method_1({:foo => 1, :bar => 2}) # no error raised
@example Actual parameter is a Hash
without the given key.
object.method_1({:foo => 1, :baz => 2}) # error raised, because hash does not include key 'bar'
@example Actual parameter is a Hash
with a key matching the given matcher.
object = mock() object.expects(:method_1).with(includes(regexp_matches(/ar/))) object.method_1({'foo' => 1, 'bar' => 2}) # no error raised
@example Actual parameter is a Hash
no key matching the given matcher.
object.method_1({'foo' => 1, 'baz' => 3}) # error raised, because hash does not include a key matching /ar/
# File lib/mocha/parameter_matchers/includes.rb, line 63 def includes(*items) Includes.new(*items) end
Matches any object that is an instance of klass
@param [Class] klass expected class. @return [InstanceOf] parameter matcher.
@see Expectation#with
@see Kernel#instance_of?
@example Actual parameter is an instance of String
.
object = mock() object.expects(:method_1).with(instance_of(String)) object.method_1('string') # no error raised
@example Actual parameter is not an instance of String
.
object = mock() object.expects(:method_1).with(instance_of(String)) object.method_1(99) # error raised, because method_1 was not called with an instance of String
# File lib/mocha/parameter_matchers/instance_of.rb, line 24 def instance_of(klass) InstanceOf.new(klass) end
Matches any object that is a klass
.
@param [Class] klass expected class. @return [IsA] parameter matcher.
@see Expectation#with
@see Kernel#is_a?
@example Actual parameter is a Integer
.
object = mock() object.expects(:method_1).with(is_a(Integer)) object.method_1(99) # no error raised
@example Actual parameter is not a Integer
.
object = mock() object.expects(:method_1).with(is_a(Integer)) object.method_1('string') # error raised, because method_1 was not called with an Integer
# File lib/mocha/parameter_matchers/is_a.rb, line 25 def is_a(klass) # rubocop:disable Naming/PredicateName IsA.new(klass) end
Matches any Object
that is a kind of klass
.
@param [Class] klass expected class. @return [KindOf] parameter matcher.
@see Expectation#with
@see Kernel#kind_of?
@example Actual parameter is a kind of Integer
.
object = mock() object.expects(:method_1).with(kind_of(Integer)) object.method_1(99) # no error raised
@example Actual parameter is not a kind of Integer
.
object = mock() object.expects(:method_1).with(kind_of(Integer)) object.method_1('string') # error raised, because method_1 was not called with a kind of Integer
# File lib/mocha/parameter_matchers/kind_of.rb, line 24 def kind_of(klass) KindOf.new(klass) end
Matches optional parameters if available.
@param [*Array<Base>] matchers matchers for optional parameters. @return [Optionally] parameter matcher.
@see Expectation#with
@example Only the two required parameters are supplied and they both match their expected value.
object = mock() object.expects(:method_1).with(1, 2, optionally(3, 4)) object.method_1(1, 2) # no error raised
@example Both required parameters and one of the optional parameters are supplied and they all match their expected value.
object = mock() object.expects(:method_1).with(1, 2, optionally(3, 4)) object.method_1(1, 2, 3) # no error raised
@example Both required parameters and both of the optional parameters are supplied and they all match their expected value.
object = mock() object.expects(:method_1).with(1, 2, optionally(3, 4)) object.method_1(1, 2, 3, 4) # no error raised
@example One of the actual optional parameters does not match the expected value.
object = mock() object.expects(:method_1).with(1, 2, optionally(3, 4)) object.method_1(1, 2, 3, 5) # error raised, because optional parameters did not match
# File lib/mocha/parameter_matchers/optionally.rb, line 33 def optionally(*matchers) Optionally.new(*matchers) end
Matches any object that matches regexp
.
@param [Regexp] regexp regular expression to match. @return [RegexpMatches] parameter matcher.
@see Expectation#with
@example Actual parameter is matched by specified regular expression.
object = mock() object.expects(:method_1).with(regexp_matches(/e/)) object.method_1('hello') # no error raised
@example Actual parameter is not matched by specified regular expression.
object = mock() object.expects(:method_1).with(regexp_matches(/a/)) object.method_1('hello') # error raised, because method_1 was not called with a parameter that matched the # regular expression
# File lib/mocha/parameter_matchers/regexp_matches.rb, line 24 def regexp_matches(regexp) RegexpMatches.new(regexp) end
Matches any object that responds to message
with result
. To put it another way, it tests the quack, not the duck.
@param [Symbol] message method to invoke. @param [Object] result expected result of sending message
. @return [RespondsWith] parameter matcher.
@see Expectation#with
@example Actual parameter responds with “FOO” when :upcase is invoked.
object = mock() object.expects(:method_1).with(responds_with(:upcase, "FOO")) object.method_1("foo") # no error raised, because "foo".upcase == "FOO"
@example Actual parameter does not respond with “FOO” when :upcase is invoked.
object = mock() object.expects(:method_1).with(responds_with(:upcase, "BAR")) object.method_1("foo") # error raised, because "foo".upcase != "BAR"
# File lib/mocha/parameter_matchers/responds_with.rb, line 25 def responds_with(message, result) RespondsWith.new(message, result) end
Matches any YAML that represents the specified object
@param [Object] object object whose YAML to compare. @return [YamlEquivalent] parameter matcher.
@see Expectation#with
@example Actual parameter is YAML equivalent of specified object
.
object = mock() object.expects(:method_1).with(yaml_equivalent(1, 2, 3)) object.method_1("--- \n- 1\n- 2\n- 3\n") # no error raised
@example Actual parameter is not YAML equivalent of specified object
.
object = mock() object.expects(:method_1).with(yaml_equivalent(1, 2, 3)) object.method_1("--- \n- 1\n- 2\n") # error raised, because method_1 was not called with YAML representing the specified Array
# File lib/mocha/parameter_matchers/yaml_equivalent.rb, line 24 def yaml_equivalent(object) YamlEquivalent.new(object) end
Private Instance Methods
@private
# File lib/mocha/parameter_matchers/has_entry.rb, line 82 def parse_option(option) case option when Hash case option.length when 0 raise ArgumentError, 'Argument has no entries.' when 1 option.first else raise ArgumentError, 'Argument has multiple entries. Use Mocha::ParameterMatchers#has_entries instead.' end else raise ArgumentError, 'Argument is not a Hash.' end end