Module: Mocha::ParameterMatchers

Included in:
API
Defined in:
lib/mocha/parameter_matchers.rb,
lib/mocha/parameter_matchers/not.rb,
lib/mocha/parameter_matchers/base.rb,
lib/mocha/parameter_matchers/is_a.rb,
lib/mocha/parameter_matchers/all_of.rb,
lib/mocha/parameter_matchers/any_of.rb,
lib/mocha/parameter_matchers/equals.rb,
lib/mocha/parameter_matchers/has_key.rb,
lib/mocha/parameter_matchers/kind_of.rb,
lib/mocha/parameter_matchers/anything.rb,
lib/mocha/parameter_matchers/has_keys.rb,
lib/mocha/parameter_matchers/includes.rb,
lib/mocha/parameter_matchers/has_entry.rb,
lib/mocha/parameter_matchers/has_value.rb,
lib/mocha/parameter_matchers/optionally.rb,
lib/mocha/parameter_matchers/has_entries.rb,
lib/mocha/parameter_matchers/instance_of.rb,
lib/mocha/parameter_matchers/responds_with.rb,
lib/mocha/parameter_matchers/any_parameters.rb,
lib/mocha/parameter_matchers/equivalent_uri.rb,
lib/mocha/parameter_matchers/regexp_matches.rb,
lib/mocha/parameter_matchers/yaml_equivalent.rb,
lib/mocha/parameter_matchers/instance_methods.rb,
lib/mocha/parameter_matchers/positional_or_keyword_hash.rb

Overview

Used as parameters for Expectation#with to restrict the parameter values which will match the expectation. Can be nested.

Defined Under Namespace

Classes: AllOf, AnyOf, AnyParameters, Anything, Base, Equals, EquivalentUri, HasEntries, HasEntry, HasKey, HasKeys, HasValue, Includes, InstanceOf, IsA, KindOf, Not, Optionally, RegexpMatches, RespondsWith, YamlEquivalent

Instance Method Summary collapse

Instance Method Details

#all_of(*matchers) ⇒ AllOf

Matches if all matchers match.

Examples:

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

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

Parameters:

  • matchers (*Array<Base>) —

    parameter matchers.

Returns:

  • (AllOf) —

    parameter matcher.

See Also:



23
24
25
 
# File 'lib/mocha/parameter_matchers/all_of.rb', line 23

def all_of(*matchers)
  AllOf.new(*matchers)
end

#any_of(*matchers) ⇒ AnyOf

Matches if any matchers match.

Examples:

One parameter matcher matches.

object = mock()
object.expects(:method_1).with(any_of(1, 3))
object.method_1(1)
# no error raised

The other parameter matcher matches.

object = mock()
object.expects(:method_1).with(any_of(1, 3))
object.method_1(3)
# no error raised

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

Parameters:

  • matchers (*Array<Base>) —

    parameter matchers.

Returns:

  • (AnyOf) —

    parameter matcher.

See Also:



29
30
31
 
# File 'lib/mocha/parameter_matchers/any_of.rb', line 29

def any_of(*matchers)
  AnyOf.new(*matchers)
end

#any_parameters ⇒ AnyParameters

Matches any parameters. This is used as the default for a newly built expectation.

Examples:

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

Returns:

See Also:



21
22
23
 
# File 'lib/mocha/parameter_matchers/any_parameters.rb', line 21

def any_parameters
  AnyParameters.new
end

#anything ⇒ Anything

Matches any object.

Examples:

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

Returns:

See Also:



18
19
20
 
# File 'lib/mocha/parameter_matchers/anything.rb', line 18

def anything
  Anything.new
end

#equals(value) ⇒ Equals

Matches any Object equalling value.

Examples:

Actual parameter equals expected parameter.

object = mock()
object.expects(:method_1).with(equals(2))
object.method_1(2)
# no error raised

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

Parameters:

  • value (Object) —

    expected value.

Returns:

  • (Equals) —

    parameter matcher.

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/equals.rb', line 24

def equals(value)
  Equals.new(value)
end

#equivalent_uri(uri) ⇒ EquivalentUri

Matches a URI without regard to the ordering of parameters in the query string.

Examples:

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

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

Parameters:

  • uri (String) —

    URI to match.

Returns:

See Also:



25
26
27
 
# File 'lib/mocha/parameter_matchers/equivalent_uri.rb', line 25

def equivalent_uri(uri)
  EquivalentUri.new(uri)
end

#has_entries(entries) ⇒ HasEntries

Matches Hash containing all entries.

Examples:

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

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

Parameters:

  • entries (Hash) —

    expected Hash entries.

Returns:

See Also:



26
27
28
 
# File 'lib/mocha/parameter_matchers/has_entries.rb', line 26

def has_entries(entries) # rubocop:disable Naming/PredicateName
  HasEntries.new(entries)
end

#has_entry(key, value) ⇒ HasEntry #has_entry(single_entry_hash) ⇒ HasEntry

Matches Hash containing entry with key and value.

Examples:

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

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

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

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

Overloads:

  • #has_entry(key, value) ⇒ HasEntry

    Parameters:

    • key (Object) —

      key for entry.

    • value (Object) —

      value for entry.

  • #has_entry(single_entry_hash) ⇒ HasEntry

    Parameters:

    • single_entry_hash (Hash) —

      Hash with single entry.

    Raises:

    • (ArgumentError) —

      if single_entry_hash does not contain exactly one entry.

Returns:

See Also:



43
44
45
46
47
48
49
50
51
52
53
54
55
 
# 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

#has_key(key) ⇒ HasKey

Matches Hash containing key.

Examples:

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

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'

Parameters:

  • key (Object) —

    expected key.

Returns:

  • (HasKey) —

    parameter matcher.

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/has_key.rb', line 24

def has_key(key) # rubocop:disable Naming/PredicateName
  HasKey.new(key)
end

#has_keys(*keys) ⇒ HasKeys

Matches Hash containing keys.

Examples:

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

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

Parameters:

  • keys (*Array<Object>) —

    expected keys.

Returns:

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/has_keys.rb', line 24

def has_keys(*keys) # rubocop:disable Naming/PredicateName
  HasKeys.new(*keys)
end

#has_value(value) ⇒ HasValue

Matches Hash containing value.

Examples:

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

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

Parameters:

  • value (Object) —

    expected value.

Returns:

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/has_value.rb', line 24

def has_value(value) # rubocop:disable Naming/PredicateName
  HasValue.new(value)
end

#includes(*items) ⇒ Includes

Matches any object that responds with true to include?(item) for all items.

Examples:

Actual parameter includes all items.

object = mock()
object.expects(:method_1).with(includes('foo', 'bar'))
object.method_1(['foo', 'bar', 'baz'])
# no error raised

Actual parameter does not include all items.

object.method_1(['foo', 'baz'])
# error raised, because ['foo', 'baz'] does not include 'bar'.

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

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

Actual parameter is a String including substring.

object = mock()
object.expects(:method_1).with(includes('bar'))
object.method_1('foobarbaz')
# no error raised

Actual parameter is a String not including substring.

object.method_1('foobaz')
# error raised, because 'foobaz' does not include 'bar'

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

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'

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

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/

Parameters:

  • items (*Array) —

    expected items.

Returns:

See Also:



63
64
65
 
# File 'lib/mocha/parameter_matchers/includes.rb', line 63

def includes(*items)
  Includes.new(*items)
end

#instance_of(klass) ⇒ InstanceOf

Matches any object that is an instance of klass

Examples:

Actual parameter is an instance of String.

object = mock()
object.expects(:method_1).with(instance_of(String))
object.method_1('string')
# no error raised

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

Parameters:

  • klass (Class) —

    expected class.

Returns:

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/instance_of.rb', line 24

def instance_of(klass)
  InstanceOf.new(klass)
end

#is_a(klass) ⇒ IsA

Matches any object that is a klass.

Examples:

Actual parameter is a Integer.

object = mock()
object.expects(:method_1).with(is_a(Integer))
object.method_1(99)
# no error raised

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

Parameters:

  • klass (Class) —

    expected class.

Returns:

  • (IsA) —

    parameter matcher.

See Also:



25
26
27
 
# File 'lib/mocha/parameter_matchers/is_a.rb', line 25

def is_a(klass) # rubocop:disable Naming/PredicateName
  IsA.new(klass)
end

#kind_of(klass) ⇒ KindOf

Matches any Object that is a kind of klass.

Examples:

Actual parameter is a kind of Integer.

object = mock()
object.expects(:method_1).with(kind_of(Integer))
object.method_1(99)
# no error raised

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

Parameters:

  • klass (Class) —

    expected class.

Returns:

  • (KindOf) —

    parameter matcher.

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/kind_of.rb', line 24

def kind_of(klass)
  KindOf.new(klass)
end

#Not(matcher) ⇒ Not

Matches if matcher does not match.

Examples:

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

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

Parameters:

  • matcher (Base) —

    matcher whose logic to invert.

Returns:

  • (Not) —

    parameter matcher.

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/not.rb', line 24

def Not(matcher) # rubocop:disable Naming/MethodName
  Not.new(matcher)
end

#optionally(*matchers) ⇒ Optionally

Matches optional parameters if available.

Examples:

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

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

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

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

Parameters:

  • matchers (*Array<Base>) —

    matchers for optional parameters.

Returns:

See Also:



33
34
35
 
# File 'lib/mocha/parameter_matchers/optionally.rb', line 33

def optionally(*matchers)
  Optionally.new(*matchers)
end

#regexp_matches(regexp) ⇒ RegexpMatches

Matches any object that matches regexp.

Examples:

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

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

Parameters:

  • regexp (Regexp) —

    regular expression to match.

Returns:

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/regexp_matches.rb', line 24

def regexp_matches(regexp)
  RegexpMatches.new(regexp)
end

#responds_with(message, result) ⇒ RespondsWith #responds_with(messages_vs_results) ⇒ RespondsWith

Returns parameter matcher.

Examples:

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"

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"

Actual parameter responds with “FOO” when :upcase is invoked and “oof” when :reverse is invoked.

object = mock()
object.expects(:method_1).with(responds_with(upcase: "FOO", reverse: "oof"))
object.method_1("foo")
# no error raised, because "foo".upcase == "FOO" and "foo".reverse == "oof"

Overloads:

  • #responds_with(message, result) ⇒ RespondsWith

    Matches any object that responds to message with result. To put it another way, it tests the quack, not the duck.

    Parameters:

    • message (Symbol) —

      method to invoke.

    • result (Object) —

      expected result of sending message.

  • #responds_with(messages_vs_results) ⇒ RespondsWith

    Matches any object that responds to all the messages with the corresponding results as specified by messages_vs_results.

    Parameters:

    • messages_vs_results (Hash<Symbol,Object>) —

      Hash of messages vs results.

    Raises:

    • (ArgumentError) —

      if messages_vs_results does not contain at least one entry.

Returns:

See Also:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/mocha/parameter_matchers/responds_with.rb', line 37

def responds_with(*options)
  case options.length
  when 0
    raise ArgumentError, 'No arguments. Expecting at least one.'
  when 1
    option = options.first
    raise ArgumentError, 'Argument is not a Hash.' unless option.is_a?(Hash)
    raise ArgumentError, 'Argument has no entries.' if option.empty?

    matchers = option.map { |message, result| RespondsWith.new(message, result) }
    AllOf.new(*matchers)
  when 2
    message, result = options
    RespondsWith.new(message, result)
  else
    raise ArgumentError, 'Too many arguments; use either a single argument (must be a Hash) or two arguments (a message and a result).'
  end
end

#yaml_equivalent(object) ⇒ YamlEquivalent

Matches any YAML that represents the specified object

Examples:

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

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

Parameters:

  • object (Object) —

    object whose YAML to compare.

Returns:

See Also:



24
25
26
 
# File 'lib/mocha/parameter_matchers/yaml_equivalent.rb', line 24

def yaml_equivalent(object)
  YamlEquivalent.new(object)
end