Module: RSpec::Matcher

Extended by:
ActiveSupport::Concern
Defined in:
lib/rspec/matcher.rb,
lib/rspec/matcher/identity.rb

Overview

Provides minimal interface for creating RSpec Matchers.

Register matcher with RSpec via register_as.

Include RSpec::Matchers::Composable to support composable matchers.

Required Methods:

  • match

Optional Methods:

  • description
  • failure_message
  • failure_message_when_negated
  • diffable?
  • supports_block_expectations?

Examples:

class BeNil
  include RSpec::Matcher
  register_as "be_nil"

  def match
    return actual.nil?
  end
end

expect(actual).to be_nil

Defined Under Namespace

Modules: ClassMethods, Identity, PrependedMethods

Constant Summary collapse

UNDEFINED =

To indicate no value was passed to matcher

Object.new.freeze

Instance Method Summary collapse

Instance Method Details

#actual ⇒ any

Returns value passed to expect().

Examples:

expect(actual).to be(expected)

Returns:

  • (any) —

    value passed to expect()




# File 'lib/rspec/matcher.rb', line 110

#description ⇒ String

Note:

for composable matchers

Note:

raises by default

Describes what this matcher does.

Examples:

be an string with X length

match X regex

Returns:

  • (String) 


137
138
139
 
# File 'lib/rspec/matcher.rb', line 137

def description
  raise "not implemented"
end

#diffable? ⇒ Boolean

Note:

false by default

Indicates if actual and expected should be diffed on failure.

Returns:

  • (Boolean) 


162
163
164
 
# File 'lib/rspec/matcher.rb', line 162

def diffable?
  false
end

#expected ⇒ any

Returns value passed to matcher function.

Examples:

expect(actual).to be(expected)

Returns:

  • (any) —

    value passed to matcher function.




# File 'lib/rspec/matcher.rb', line 114

#failure_message ⇒ String

Note:

raises by default

Describe failure.

Examples:

"expected EXPECTED to be of length X"

"expected EXPECTED to match X"

Returns:

  • (String) 


146
147
148
 
# File 'lib/rspec/matcher.rb', line 146

def failure_message
  raise "not implemented"
end

#failure_message_when_negated ⇒ String

Note:

raises by default

Describe failure when not_to is used.

Examples:

"expected EXPECTED not to be of length X"

"expected EXPECTED not to match X"

Returns:

  • (String) 


155
156
157
 
# File 'lib/rspec/matcher.rb', line 155

def failure_message_when_negated
  raise "not implemented"
end

#initialize ⇒ Object

First argument passed to matcher is placed in expected and removed from arg list. Every argument beside that including a block is passed to initialize function.




# File 'lib/rspec/matcher.rb', line 118

#match(_ = nil) ⇒ Boolean

Note:

Must be implemented.

Determines if there is a match or not.

Parameters:

  • actual (any) —

    same as actual method.

Returns:

  • (Boolean) —

    true for success, false for failure.



127
128
129
 
# File 'lib/rspec/matcher.rb', line 127

def match _ = nil
  raise "not implemented"
end

#matches?(actual) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Hides RSpec internal api

Returns:

  • (Boolean) 


98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/rspec/matcher.rb', line 98

def matches? actual
  self.actual = actual

  catch(:resolution) do
    if method(:match).arity == 0
      match
    else
      match actual
    end
  end
end

#reject_expectation ⇒ void (private)

This method returns an undefined value.

Stops evaluation and tells RSpec there wasn't a match.



188
189
190
 
# File 'lib/rspec/matcher.rb', line 188

def reject_expectation
  throw :resolution, false
end

#resolve_expectation ⇒ void (private)

This method returns an undefined value.

Stops evaluation and tells RSpec there was a match.



180
181
182
 
# File 'lib/rspec/matcher.rb', line 180

def resolve_expectation
  throw :resolution, true
end

#supports_block_expectations? ⇒ Boolean

Note:

false by default

Indicates if actual can be a block.

Examples:

expect { something }.not_to raise_error

Returns:

  • (Boolean) 


170
171
172
 
# File 'lib/rspec/matcher.rb', line 170

def supports_block_expectations?
  false
end