# 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/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

## 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, HasValue, Includes, InstanceOf, IsA, KindOf, Not, Optionally, RegexpMatches, RespondsWith, YamlEquivalent

## Instance Method Summary collapse

- #all_of(*matchers) ⇒ AllOf

  Matches if all `matchers` match.

- #any_of(*matchers) ⇒ AnyOf

  Matches if any `matchers` match.

- #any_parameters ⇒ AnyParameters

  Matches any parameters.

- #anything ⇒ Anything

  Matches any object.

- #equals(value) ⇒ Equals

  Matches any `Object` equalling `value`.

- #equivalent_uri(uri) ⇒ EquivalentUri

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

- #has_entries(entries) ⇒ HasEntries

  Matches `Hash` containing all `entries`.

- #has_entry(*options) ⇒ HasEntry

  Matches `Hash` containing entry with `key` and `value`.

- #has_equivalent_query_string(uri) ⇒ Object deprecated Deprecated.

  Use #equivalent_uri instead.

- #has_key(key) ⇒ HasKey

  Matches `Hash` containing `key`.

- #has_value(value) ⇒ HasValue

  Matches `Hash` containing `value`.

- #includes(*items) ⇒ Includes

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

- #instance_of(klass) ⇒ InstanceOf

  Matches any object that is an instance of `klass`.

- #is_a(klass) ⇒ IsA

  Matches any object that is a `klass`.

- #kind_of(klass) ⇒ KindOf

  Matches any `Object` that is a kind of `klass`.

- #Not(matcher) ⇒ Not

  Matches if `matcher` does not match.

- #optionally(*matchers) ⇒ Optionally

  Matches optional parameters if available.

- #regexp_matches(regexp) ⇒ RegexpMatches

  Matches any object that matches `regexp`.

- #responds_with(message, result) ⇒ RespondsWith

  Matches any object that responds to `message` with `result`.

- #yaml_equivalent(object) ⇒ YamlEquivalent

  Matches any YAML that represents the specified `object`.

## 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:

- parameter_matchers (`*Array<Base>`) —

  parameter matchers.

Returns:

- (`AllOf`) —

  parameter matcher.

See Also:

- Expectation#with

    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:

- parameter_matchers (`*Array<Base>`) —

  parameter matchers.

Returns:

- (`AnyOf`) —

  parameter matcher.

See Also:

- Expectation#with

    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:

- (`AnyParameters`) —

  parameter matcher.

See Also:

- Expectation#with

    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:

- (`Anything`) —

  parameter matcher.

See Also:

- Expectation#with

    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:

- Expectation#with
- Object#==

    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:

- (`EquivalentUri`) —

  parameter matcher.

See Also:

- Expectation#with

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

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

### #has_entries(entries) ⇒ `HasEntries`

Matches `Hash` containing all `entries`.

rubocop:disable Naming/PredicateName

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:

- (`HasEntries`) —

  parameter matcher.

See Also:

- Expectation#with

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

    def has_entries(entries)
      HasEntries.new(entries)
    end

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

Matches `Hash` containing entry with `key` and `value`.

rubocop:disable Naming/PredicateName

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:

- (`HasEntry`) —

  parameter matcher.

See Also:

- Expectation#with

    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    # File 'lib/mocha/parameter_matchers/has_entry.rb', line 43

    def has_entry(*options)
      case options.length
      when 1
        case options[0]
        when Hash
          case options[0].length
          when 0
            raise ArgumentError, 'Argument has no entries.'
          when 1
            key, value = options[0].first
          else
            raise ArgumentError, 'Argument has multiple entries. Use Mocha::ParameterMatchers#has_entries instead.'
          end
        else
          raise ArgumentError, 'Argument is not a Hash.'
        end
      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_equivalent_query_string(uri) ⇒ `Object`

Deprecated.

Use #equivalent_uri instead.

rubocop:disable Naming/PredicateName

    32
    33
    34
    35
    36
    # File 'lib/mocha/parameter_matchers/equivalent_uri.rb', line 32

    def has_equivalent_query_string(uri)
      Mocha::Deprecation.warning('`has_equivalent_query_string` is deprecated. Please use `equivalent_uri` instead.')

      equivalent_uri(uri)
    end

### #has_key(key) ⇒ `HasKey`

Matches `Hash` containing `key`.

rubocop:disable Naming/PredicateName

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:

- Expectation#with

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

    def has_key(key)
      HasKey.new(key)
    end

### #has_value(value) ⇒ `HasValue`

Matches `Hash` containing `value`.

rubocop:disable Naming/PredicateName

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:

- (`HasValue`) —

  parameter matcher.

See Also:

- Expectation#with

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

    def has_value(value)
      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:

- (`Includes`) —

  parameter matcher.

See Also:

- Expectation#with

    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:

- (`InstanceOf`) —

  parameter matcher.

See Also:

- Expectation#with
- Kernel#instance_of?

    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`.

rubocop:disable Naming/PredicateName

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:

- Expectation#with
- Kernel#is_a?

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

    def is_a(klass)
      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:

- Expectation#with
- Kernel#kind_of?

    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.

rubocop:disable Naming/MethodName

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:

- Expectation#with

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

    def Not(matcher)
      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:

- (`Optionally`) —

  parameter matcher.

See Also:

- Expectation#with

    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:

- (`RegexpMatches`) —

  parameter matcher.

See Also:

- Expectation#with

    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`

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

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"

Parameters:

- message (`Symbol`) —

  method to invoke.

- result (`Object`) —

  expected result of sending `message`.

Returns:

- (`RespondsWith`) —

  parameter matcher.

See Also:

- Expectation#with

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

    def responds_with(message, result)
      RespondsWith.new(message, result)
    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:

- (`YamlEquivalent`) —

  parameter matcher.

See Also:

- Expectation#with

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

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