Class: Cuprum::RSpec::BeAResultMatcher

Inherits:
Object
  • Object
show all
Defined in:
lib/cuprum/rspec/be_a_result_matcher.rb

Overview

Asserts the actual object is a result object with the specified properties.

If initialized with a class, the matcher will assert that the actual object is an instance of that class. This can be useful for asserting that the result is an instance of a result subclass. If no class is given, the matcher asserts that the result is an object responding to #to_cuprum_result.

The matcher also defines fluent methods for asserting on the result’s properties:

  • The #with_value method asserts that the result has the specified value. Also aliased as #and_value.

  • The #with_error method asserts that the result has the specified error. Also aliased as #and_error.

  • The #with_status method asserts that the result has the specified status. Also aliased as #and_status.

Generally speaking, you should use the #be_a_result, #be_a_passing_result, and #be_a_failing_result macros, rather than instantiating a BeAResultMatcher directly.

Examples:

Matching Any Result

# Or use expect().to be_a_result
matcher = Cuprum::RSpec::BeAResultMatcher.new

matcher.matches?(nil)                #=> false
matcher.matches?(Cuprum::Result.new) #=> true

Matching A Result Status

# Or use expect().to be_a_passing_result
matcher = Cuprum::RSpec::BeAResultMatcher.new.with_status(:success)

matcher.matches?(Cuprum::Result.new(status: :failure)) #=> false
matcher.matches?(Cuprum::Result.new(status: :success)) #=> false

Matching A Result Value

matcher = Cuprum::RSpec::BeAResultMatcher.new.with_value({ ok: true })

matcher.matches?(Cuprum::Result.new(value: { ok: false })) #=> false
matcher.matches?(Cuprum::Result.new(value: { ok: true }))  #=> true

Matching A Result Error

error   = Cuprum::Error.new(message: 'Something went wrong')
matcher = Cuprum::RSpec::BeAResultMatcher.new.with_error(error)

other_error = Cuprum::Error.new(message: 'Oh no')
matcher.matches?(Cuprum::Result.new(error: other_error) #=> false
matcher.matches?(Cuprum::Result.new(error: error)       #=> true

Matching A Result Class

matcher = Cuprum::RSpec::BeAResultMatcher.new(CustomResult)

matcher.matches?(Cuprum::Result.new) #=> false
matcher.matches?(CustomResult.new)   #=> true

Matching Multiple Properties

matcher =
  Cuprum::RSpec::BeAResultMatcher
  .with_status(:failure)
  .and_value({ ok: false })
  .and_error(Cuprum::Error.new(message: 'Something went wrong'))

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(expected_class = nil) ⇒ BeAResultMatcher

Returns a new instance of BeAResultMatcher.

Parameters:

  • expected_class (Class) (defaults to: nil) —

    the expected class of result. Defaults to Cuprum::Result.



78
79
80
81
82
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 78

def initialize(expected_class = nil)
  @expected_class = expected_class
  @expected_error = DEFAULT_VALUE
  @expected_value = DEFAULT_VALUE
end

Instance Attribute Details

#expected_class ⇒ Class (readonly)

Returns the expected class of result.

Returns:

  • (Class) —

    the expected class of result.



85
86
87
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 85

def expected_class
  @expected_class
end

Instance Method Details

#description ⇒ String

Returns a short description of the matcher and expected properties.

Returns:

  • (String) —

    a short description of the matcher and expected properties.



89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 89

def description
  message =
    if expected_class
      "be an instance of #{expected_class}"
    else
      'be a Cuprum result'
    end

  return message unless expected_properties?

  "#{message} #{properties_description}"
end

#does_not_match?(actual) ⇒ Boolean

Checks that the given actual object is not a Cuprum result.

Parameters:

  • actual (Object) —

    the actual object to match.

Returns:

  • (Boolean) —

    false if the actual object is a result; otherwise true.

Raises:

  • (ArgumentError) 


107
108
109
110
111
112
113
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 107

def does_not_match?(actual)
  @actual = actual

  raise ArgumentError, negated_matcher_warning if expected_properties?

  !actual_is_result?
end

#failure_message ⇒ String

Returns a summary message describing a failed expectation.

Returns:

  • (String) —

    a summary message describing a failed expectation.



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 116

def failure_message # rubocop:disable Metrics/MethodLength
  message = "expected #{actual.inspect} to #{description}"

  if !actual_is_result? && expected_class
    "#{message}, but the object is not an instance of #{expected_class}"
  elsif !actual_is_result?
    "#{message}, but the object is not a result"
  elsif actual_is_uncalled_operation?
    "#{message}, but the object is an uncalled operation"
  elsif !properties_match?
    message + properties_failure_message
  else
    # :nocov:
    message
    # :nocov:
  end
end

#failure_message_when_negated ⇒ String

Returns a summary message describing a failed negated expectation.

Returns:

  • (String) —

    a summary message describing a failed negated expectation.



136
137
138
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 136

def failure_message_when_negated
  "expected #{actual.inspect} not to #{description}"
end

#matches?(actual) ⇒ Boolean

Checks that the given actual object is a Cuprum result or compatible object and has the specified properties.

Parameters:

  • actual (Object) —

    The actual object to match.

Returns:

  • (Boolean) —

    true if the actual object is a result with the expected properties; otherwise false.



147
148
149
150
151
152
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 147

def matches?(actual)
  @actual                  = actual
  @non_matching_properties = nil

  actual_is_result? && !actual_is_uncalled_operation? && properties_match?
end

#with_error(error) ⇒ BeAResultMatcher Also known as: and_error

Sets an error expectation on the matcher. Calls to #matches? will fail unless the actual object has the specified error.

Parameters:

Returns:



160
161
162
163
164
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 160

def with_error(error)
  @expected_error = error

  self
end

#with_status(status) ⇒ BeAResultMatcher Also known as: and_status

Sets a status expectation on the matcher. Calls to #matches? will fail unless the actual object has the specified status.

Parameters:

  • status (Symbol) —

    The expected status.

Returns:



173
174
175
176
177
 
# File 'lib/cuprum/rspec/be_a_result_matcher.rb', line 173

def with_status(status)
  @expected_status = status

  self
end

#with_value(value) ⇒ BeAResultMatcher Also known as: and_value

Sets a value expectation on the matcher. Calls to #matches? will fail unless the actual object has the specified value.

Parameters:

  • value (Object) —

    The expected value.

Returns:



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

def with_value(value)
  @expected_value = value

  self
end