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 Classes: RescueAndCatch

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 149

#clean_up ⇒ void

This method returns an undefined value.

Always gets called after decision is made.



218
219
 
# File 'lib/rspec/matcher.rb', line 218

def clean_up
end

#description ⇒ String

Note:

for composable matchers

Note:

raises by default

Note:

used for failure messages

Describes what this matcher does.

Examples:

be an string with X length

match X regex

Returns:

  • (String) 


177
178
179
 
# File 'lib/rspec/matcher.rb', line 177

def description
  raise "not implemented"
end

#diffable? ⇒ Boolean

Note:

false by default

Indicates if actual and expected should be diffed on failure.

Returns:

  • (Boolean) 


204
205
206
 
# File 'lib/rspec/matcher.rb', line 204

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 153

#failure_message ⇒ String

Note:

raises by default

Describe failure.

Examples:

"expected EXPECTED to be of length X"

"expected EXPECTED to match X"

Returns:

  • (String) 


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

def failure_message
  return "Expected #{expected} to #{description}" if _message == UNDEFINED

  "Expected #{expected} to #{description} but #{_message}"
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) 


197
198
199
 
# File 'lib/rspec/matcher.rb', line 197

def failure_message_when_negated
  failure_message.sub "to", "not to"
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 157

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



166
167
168
 
# File 'lib/rspec/matcher.rb', line 166

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) 


138
139
140
141
142
143
144
145
146
147
 
# File 'lib/rspec/matcher.rb', line 138

def matches? actual
  self.actual = actual
  RescueAndCatch.new self do
    catching(:resolution) do
      method(:match).arity == 0 ? match : match(actual)
    end

    ensuring(Exception) { clean_up }
  end.result
end

#reject_expectation(message = UNDEFINED) ⇒ void (private)

Note:

message is used in failure messages

This method returns an undefined value.

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

Parameters:

  • message (String) (defaults to: UNDEFINED) —

    reason expectation was rejected



237
238
239
240
 
# File 'lib/rspec/matcher.rb', line 237

def reject_expectation message = UNDEFINED
  self._message = message
  throw :resolution, false
end

#resolve_expectation ⇒ void (private)

This method returns an undefined value.

Stops evaluation and tells RSpec there was a match.



227
228
229
 
# File 'lib/rspec/matcher.rb', line 227

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) 


212
213
214
 
# File 'lib/rspec/matcher.rb', line 212

def supports_block_expectations?
  false
end

#undefined? ⇒ Boolean (private)

Indicates if expected was passed or not

Returns:

  • (Boolean) 


244
245
246
 
# File 'lib/rspec/matcher.rb', line 244

def undefined?
  expected == UNDEFINED
end