rspec-expectations 3.8.6
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- checksums.yaml.gz.sig +0 -0
- data.tar.gz.sig +5 -0
- data/.document +5 -0
- data/.yardopts +6 -0
- data/Changelog.md +1156 -0
- data/LICENSE.md +25 -0
- data/README.md +305 -0
- data/lib/rspec/expectations.rb +82 -0
- data/lib/rspec/expectations/block_snippet_extractor.rb +253 -0
- data/lib/rspec/expectations/configuration.rb +215 -0
- data/lib/rspec/expectations/expectation_target.rb +127 -0
- data/lib/rspec/expectations/fail_with.rb +39 -0
- data/lib/rspec/expectations/failure_aggregator.rb +194 -0
- data/lib/rspec/expectations/handler.rb +170 -0
- data/lib/rspec/expectations/minitest_integration.rb +58 -0
- data/lib/rspec/expectations/syntax.rb +132 -0
- data/lib/rspec/expectations/version.rb +8 -0
- data/lib/rspec/matchers.rb +1034 -0
- data/lib/rspec/matchers/aliased_matcher.rb +116 -0
- data/lib/rspec/matchers/built_in.rb +52 -0
- data/lib/rspec/matchers/built_in/all.rb +86 -0
- data/lib/rspec/matchers/built_in/base_matcher.rb +193 -0
- data/lib/rspec/matchers/built_in/be.rb +288 -0
- data/lib/rspec/matchers/built_in/be_between.rb +77 -0
- data/lib/rspec/matchers/built_in/be_instance_of.rb +26 -0
- data/lib/rspec/matchers/built_in/be_kind_of.rb +20 -0
- data/lib/rspec/matchers/built_in/be_within.rb +72 -0
- data/lib/rspec/matchers/built_in/change.rb +428 -0
- data/lib/rspec/matchers/built_in/compound.rb +271 -0
- data/lib/rspec/matchers/built_in/contain_exactly.rb +302 -0
- data/lib/rspec/matchers/built_in/cover.rb +24 -0
- data/lib/rspec/matchers/built_in/eq.rb +40 -0
- data/lib/rspec/matchers/built_in/eql.rb +34 -0
- data/lib/rspec/matchers/built_in/equal.rb +81 -0
- data/lib/rspec/matchers/built_in/exist.rb +90 -0
- data/lib/rspec/matchers/built_in/has.rb +103 -0
- data/lib/rspec/matchers/built_in/have_attributes.rb +114 -0
- data/lib/rspec/matchers/built_in/include.rb +149 -0
- data/lib/rspec/matchers/built_in/match.rb +106 -0
- data/lib/rspec/matchers/built_in/operators.rb +128 -0
- data/lib/rspec/matchers/built_in/output.rb +200 -0
- data/lib/rspec/matchers/built_in/raise_error.rb +230 -0
- data/lib/rspec/matchers/built_in/respond_to.rb +165 -0
- data/lib/rspec/matchers/built_in/satisfy.rb +60 -0
- data/lib/rspec/matchers/built_in/start_or_end_with.rb +94 -0
- data/lib/rspec/matchers/built_in/throw_symbol.rb +132 -0
- data/lib/rspec/matchers/built_in/yield.rb +432 -0
- data/lib/rspec/matchers/composable.rb +171 -0
- data/lib/rspec/matchers/dsl.rb +527 -0
- data/lib/rspec/matchers/english_phrasing.rb +58 -0
- data/lib/rspec/matchers/expecteds_for_multiple_diffs.rb +73 -0
- data/lib/rspec/matchers/fail_matchers.rb +42 -0
- data/lib/rspec/matchers/generated_descriptions.rb +41 -0
- data/lib/rspec/matchers/matcher_delegator.rb +35 -0
- data/lib/rspec/matchers/matcher_protocol.rb +99 -0
- metadata +215 -0
- metadata.gz.sig +0 -0
@@ -0,0 +1,170 @@
|
|
1
|
+
module RSpec
|
2
|
+
module Expectations
|
3
|
+
# @private
|
4
|
+
module ExpectationHelper
|
5
|
+
def self.check_message(msg)
|
6
|
+
unless msg.nil? || msg.respond_to?(:to_str) || msg.respond_to?(:call)
|
7
|
+
::Kernel.warn [
|
8
|
+
"WARNING: ignoring the provided expectation message argument (",
|
9
|
+
msg.inspect,
|
10
|
+
") since it is not a string or a proc."
|
11
|
+
].join
|
12
|
+
end
|
13
|
+
end
|
14
|
+
|
15
|
+
# Returns an RSpec-3+ compatible matcher, wrapping a legacy one
|
16
|
+
# in an adapter if necessary.
|
17
|
+
#
|
18
|
+
# @private
|
19
|
+
def self.modern_matcher_from(matcher)
|
20
|
+
LegacyMatcherAdapter::RSpec2.wrap(matcher) ||
|
21
|
+
LegacyMatcherAdapter::RSpec1.wrap(matcher) || matcher
|
22
|
+
end
|
23
|
+
|
24
|
+
def self.with_matcher(handler, matcher, message)
|
25
|
+
check_message(message)
|
26
|
+
matcher = modern_matcher_from(matcher)
|
27
|
+
yield matcher
|
28
|
+
ensure
|
29
|
+
::RSpec::Matchers.last_expectation_handler = handler
|
30
|
+
::RSpec::Matchers.last_matcher = matcher
|
31
|
+
end
|
32
|
+
|
33
|
+
def self.handle_failure(matcher, message, failure_message_method)
|
34
|
+
message = message.call if message.respond_to?(:call)
|
35
|
+
message ||= matcher.__send__(failure_message_method)
|
36
|
+
|
37
|
+
if matcher.respond_to?(:diffable?) && matcher.diffable?
|
38
|
+
::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
|
39
|
+
else
|
40
|
+
::RSpec::Expectations.fail_with message
|
41
|
+
end
|
42
|
+
end
|
43
|
+
end
|
44
|
+
|
45
|
+
# @private
|
46
|
+
class PositiveExpectationHandler
|
47
|
+
def self.handle_matcher(actual, initial_matcher, message=nil, &block)
|
48
|
+
ExpectationHelper.with_matcher(self, initial_matcher, message) do |matcher|
|
49
|
+
return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
|
50
|
+
matcher.matches?(actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message)
|
51
|
+
end
|
52
|
+
end
|
53
|
+
|
54
|
+
def self.verb
|
55
|
+
"should"
|
56
|
+
end
|
57
|
+
|
58
|
+
def self.should_method
|
59
|
+
:should
|
60
|
+
end
|
61
|
+
|
62
|
+
def self.opposite_should_method
|
63
|
+
:should_not
|
64
|
+
end
|
65
|
+
end
|
66
|
+
|
67
|
+
# @private
|
68
|
+
class NegativeExpectationHandler
|
69
|
+
def self.handle_matcher(actual, initial_matcher, message=nil, &block)
|
70
|
+
ExpectationHelper.with_matcher(self, initial_matcher, message) do |matcher|
|
71
|
+
return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
|
72
|
+
does_not_match?(matcher, actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message_when_negated)
|
73
|
+
end
|
74
|
+
end
|
75
|
+
|
76
|
+
def self.does_not_match?(matcher, actual, &block)
|
77
|
+
if matcher.respond_to?(:does_not_match?)
|
78
|
+
matcher.does_not_match?(actual, &block)
|
79
|
+
else
|
80
|
+
!matcher.matches?(actual, &block)
|
81
|
+
end
|
82
|
+
end
|
83
|
+
|
84
|
+
def self.verb
|
85
|
+
"should not"
|
86
|
+
end
|
87
|
+
|
88
|
+
def self.should_method
|
89
|
+
:should_not
|
90
|
+
end
|
91
|
+
|
92
|
+
def self.opposite_should_method
|
93
|
+
:should
|
94
|
+
end
|
95
|
+
end
|
96
|
+
|
97
|
+
# Wraps a matcher written against one of the legacy protocols in
|
98
|
+
# order to present the current protocol.
|
99
|
+
#
|
100
|
+
# @private
|
101
|
+
class LegacyMatcherAdapter < Matchers::MatcherDelegator
|
102
|
+
def initialize(matcher)
|
103
|
+
super
|
104
|
+
::RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''), :type => "legacy_matcher")
|
105
|
+
|#{matcher.class.name || matcher.inspect} implements a legacy RSpec matcher
|
106
|
+
|protocol. For the current protocol you should expose the failure messages
|
107
|
+
|via the `failure_message` and `failure_message_when_negated` methods.
|
108
|
+
|(Used from #{CallerFilter.first_non_rspec_line})
|
109
|
+
EOS
|
110
|
+
end
|
111
|
+
|
112
|
+
def self.wrap(matcher)
|
113
|
+
new(matcher) if interface_matches?(matcher)
|
114
|
+
end
|
115
|
+
|
116
|
+
# Starting in RSpec 1.2 (and continuing through all 2.x releases),
|
117
|
+
# the failure message protocol was:
|
118
|
+
# * `failure_message_for_should`
|
119
|
+
# * `failure_message_for_should_not`
|
120
|
+
# @private
|
121
|
+
class RSpec2 < self
|
122
|
+
def failure_message
|
123
|
+
base_matcher.failure_message_for_should
|
124
|
+
end
|
125
|
+
|
126
|
+
def failure_message_when_negated
|
127
|
+
base_matcher.failure_message_for_should_not
|
128
|
+
end
|
129
|
+
|
130
|
+
def self.interface_matches?(matcher)
|
131
|
+
(
|
132
|
+
!matcher.respond_to?(:failure_message) &&
|
133
|
+
matcher.respond_to?(:failure_message_for_should)
|
134
|
+
) || (
|
135
|
+
!matcher.respond_to?(:failure_message_when_negated) &&
|
136
|
+
matcher.respond_to?(:failure_message_for_should_not)
|
137
|
+
)
|
138
|
+
end
|
139
|
+
end
|
140
|
+
|
141
|
+
# Before RSpec 1.2, the failure message protocol was:
|
142
|
+
# * `failure_message`
|
143
|
+
# * `negative_failure_message`
|
144
|
+
# @private
|
145
|
+
class RSpec1 < self
|
146
|
+
def failure_message
|
147
|
+
base_matcher.failure_message
|
148
|
+
end
|
149
|
+
|
150
|
+
def failure_message_when_negated
|
151
|
+
base_matcher.negative_failure_message
|
152
|
+
end
|
153
|
+
|
154
|
+
# Note: `failure_message` is part of the RSpec 3 protocol
|
155
|
+
# (paired with `failure_message_when_negated`), so we don't check
|
156
|
+
# for `failure_message` here.
|
157
|
+
def self.interface_matches?(matcher)
|
158
|
+
!matcher.respond_to?(:failure_message_when_negated) &&
|
159
|
+
matcher.respond_to?(:negative_failure_message)
|
160
|
+
end
|
161
|
+
end
|
162
|
+
end
|
163
|
+
|
164
|
+
# RSpec 3.0 was released with the class name misspelled. For SemVer compatibility,
|
165
|
+
# we will provide this misspelled alias until 4.0.
|
166
|
+
# @deprecated Use LegacyMatcherAdapter instead.
|
167
|
+
# @private
|
168
|
+
LegacyMacherAdapter = LegacyMatcherAdapter
|
169
|
+
end
|
170
|
+
end
|
@@ -0,0 +1,58 @@
|
|
1
|
+
require 'rspec/expectations'
|
2
|
+
|
3
|
+
Minitest::Test.class_eval do
|
4
|
+
include ::RSpec::Matchers
|
5
|
+
|
6
|
+
# This `expect` will only be called if the user is using Minitest < 5.6
|
7
|
+
# or if they are _not_ using Minitest::Spec on 5.6+. Minitest::Spec on 5.6+
|
8
|
+
# defines its own `expect` and will have the assertions incremented via our
|
9
|
+
# definitions of `to`/`not_to`/`to_not` below.
|
10
|
+
def expect(*a, &b)
|
11
|
+
self.assertions += 1
|
12
|
+
super
|
13
|
+
end
|
14
|
+
|
15
|
+
# Convert a `MultipleExpectationsNotMetError` to a `Minitest::Assertion` error so
|
16
|
+
# it gets counted in minitest's summary stats as a failure rather than an error.
|
17
|
+
# It would be nice to make `MultipleExpectationsNotMetError` subclass
|
18
|
+
# `Minitest::Assertion`, but Minitest's implementation does not treat subclasses
|
19
|
+
# the same, so this is the best we can do.
|
20
|
+
def aggregate_failures(*args, &block)
|
21
|
+
super
|
22
|
+
rescue RSpec::Expectations::MultipleExpectationsNotMetError => e
|
23
|
+
assertion_failed = Minitest::Assertion.new(e.message)
|
24
|
+
assertion_failed.set_backtrace e.backtrace
|
25
|
+
raise assertion_failed
|
26
|
+
end
|
27
|
+
end
|
28
|
+
|
29
|
+
# Older versions of Minitest (e.g. before 5.6) do not define
|
30
|
+
# `Minitest::Expectation`.
|
31
|
+
if defined?(::Minitest::Expectation)
|
32
|
+
Minitest::Expectation.class_eval do
|
33
|
+
include RSpec::Expectations::ExpectationTarget::InstanceMethods
|
34
|
+
|
35
|
+
def to(*args)
|
36
|
+
ctx.assertions += 1
|
37
|
+
super
|
38
|
+
end
|
39
|
+
|
40
|
+
def not_to(*args)
|
41
|
+
ctx.assertions += 1
|
42
|
+
super
|
43
|
+
end
|
44
|
+
|
45
|
+
def to_not(*args)
|
46
|
+
ctx.assertions += 1
|
47
|
+
super
|
48
|
+
end
|
49
|
+
end
|
50
|
+
end
|
51
|
+
|
52
|
+
module RSpec
|
53
|
+
module Expectations
|
54
|
+
remove_const :ExpectationNotMetError
|
55
|
+
# Exception raised when an expectation fails.
|
56
|
+
const_set :ExpectationNotMetError, ::Minitest::Assertion
|
57
|
+
end
|
58
|
+
end
|
@@ -0,0 +1,132 @@
|
|
1
|
+
module RSpec
|
2
|
+
module Expectations
|
3
|
+
# @api private
|
4
|
+
# Provides methods for enabling and disabling the available
|
5
|
+
# syntaxes provided by rspec-expectations.
|
6
|
+
module Syntax
|
7
|
+
module_function
|
8
|
+
|
9
|
+
# @api private
|
10
|
+
# Determines where we add `should` and `should_not`.
|
11
|
+
def default_should_host
|
12
|
+
@default_should_host ||= ::Object.ancestors.last
|
13
|
+
end
|
14
|
+
|
15
|
+
# @api private
|
16
|
+
# Instructs rspec-expectations to warn on first usage of `should` or `should_not`.
|
17
|
+
# Enabled by default. This is largely here to facilitate testing.
|
18
|
+
def warn_about_should!
|
19
|
+
@warn_about_should = true
|
20
|
+
end
|
21
|
+
|
22
|
+
# @api private
|
23
|
+
# Generates a deprecation warning for the given method if no warning
|
24
|
+
# has already been issued.
|
25
|
+
def warn_about_should_unless_configured(method_name)
|
26
|
+
return unless @warn_about_should
|
27
|
+
|
28
|
+
RSpec.deprecate(
|
29
|
+
"Using `#{method_name}` from rspec-expectations' old `:should` syntax without explicitly enabling the syntax",
|
30
|
+
:replacement => "the new `:expect` syntax or explicitly enable `:should` with `config.expect_with(:rspec) { |c| c.syntax = :should }`"
|
31
|
+
)
|
32
|
+
|
33
|
+
@warn_about_should = false
|
34
|
+
end
|
35
|
+
|
36
|
+
# @api private
|
37
|
+
# Enables the `should` syntax.
|
38
|
+
def enable_should(syntax_host=default_should_host)
|
39
|
+
@warn_about_should = false if syntax_host == default_should_host
|
40
|
+
return if should_enabled?(syntax_host)
|
41
|
+
|
42
|
+
syntax_host.module_exec do
|
43
|
+
def should(matcher=nil, message=nil, &block)
|
44
|
+
::RSpec::Expectations::Syntax.warn_about_should_unless_configured(::Kernel.__method__)
|
45
|
+
::RSpec::Expectations::PositiveExpectationHandler.handle_matcher(self, matcher, message, &block)
|
46
|
+
end
|
47
|
+
|
48
|
+
def should_not(matcher=nil, message=nil, &block)
|
49
|
+
::RSpec::Expectations::Syntax.warn_about_should_unless_configured(::Kernel.__method__)
|
50
|
+
::RSpec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
|
51
|
+
end
|
52
|
+
end
|
53
|
+
end
|
54
|
+
|
55
|
+
# @api private
|
56
|
+
# Disables the `should` syntax.
|
57
|
+
def disable_should(syntax_host=default_should_host)
|
58
|
+
return unless should_enabled?(syntax_host)
|
59
|
+
|
60
|
+
syntax_host.module_exec do
|
61
|
+
undef should
|
62
|
+
undef should_not
|
63
|
+
end
|
64
|
+
end
|
65
|
+
|
66
|
+
# @api private
|
67
|
+
# Enables the `expect` syntax.
|
68
|
+
def enable_expect(syntax_host=::RSpec::Matchers)
|
69
|
+
return if expect_enabled?(syntax_host)
|
70
|
+
|
71
|
+
syntax_host.module_exec do
|
72
|
+
def expect(value=::RSpec::Expectations::ExpectationTarget::UndefinedValue, &block)
|
73
|
+
::RSpec::Expectations::ExpectationTarget.for(value, block)
|
74
|
+
end
|
75
|
+
end
|
76
|
+
end
|
77
|
+
|
78
|
+
# @api private
|
79
|
+
# Disables the `expect` syntax.
|
80
|
+
def disable_expect(syntax_host=::RSpec::Matchers)
|
81
|
+
return unless expect_enabled?(syntax_host)
|
82
|
+
|
83
|
+
syntax_host.module_exec do
|
84
|
+
undef expect
|
85
|
+
end
|
86
|
+
end
|
87
|
+
|
88
|
+
# @api private
|
89
|
+
# Indicates whether or not the `should` syntax is enabled.
|
90
|
+
def should_enabled?(syntax_host=default_should_host)
|
91
|
+
syntax_host.method_defined?(:should)
|
92
|
+
end
|
93
|
+
|
94
|
+
# @api private
|
95
|
+
# Indicates whether or not the `expect` syntax is enabled.
|
96
|
+
def expect_enabled?(syntax_host=::RSpec::Matchers)
|
97
|
+
syntax_host.method_defined?(:expect)
|
98
|
+
end
|
99
|
+
end
|
100
|
+
end
|
101
|
+
end
|
102
|
+
|
103
|
+
if defined?(BasicObject)
|
104
|
+
# The legacy `:should` syntax adds the following methods directly to
|
105
|
+
# `BasicObject` so that they are available off of any object. Note, however,
|
106
|
+
# that this syntax does not always play nice with delegate/proxy objects.
|
107
|
+
# We recommend you use the non-monkeypatching `:expect` syntax instead.
|
108
|
+
class BasicObject
|
109
|
+
# @method should(matcher, message)
|
110
|
+
# Passes if `matcher` returns true. Available on every `Object`.
|
111
|
+
# @example
|
112
|
+
# actual.should eq expected
|
113
|
+
# actual.should match /expression/
|
114
|
+
# @param [Matcher]
|
115
|
+
# matcher
|
116
|
+
# @param [String] message optional message to display when the expectation fails
|
117
|
+
# @return [Boolean] true if the expectation succeeds (else raises)
|
118
|
+
# @note This is only available when you have enabled the `:should` syntax.
|
119
|
+
# @see RSpec::Matchers
|
120
|
+
|
121
|
+
# @method should_not(matcher, message)
|
122
|
+
# Passes if `matcher` returns false. Available on every `Object`.
|
123
|
+
# @example
|
124
|
+
# actual.should_not eq expected
|
125
|
+
# @param [Matcher]
|
126
|
+
# matcher
|
127
|
+
# @param [String] message optional message to display when the expectation fails
|
128
|
+
# @return [Boolean] false if the negative expectation succeeds (else raises)
|
129
|
+
# @note This is only available when you have enabled the `:should` syntax.
|
130
|
+
# @see RSpec::Matchers
|
131
|
+
end
|
132
|
+
end
|
@@ -0,0 +1,1034 @@
|
|
1
|
+
require 'rspec/support'
|
2
|
+
RSpec::Support.require_rspec_support 'matcher_definition'
|
3
|
+
RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relative(f) }
|
4
|
+
|
5
|
+
%w[
|
6
|
+
english_phrasing
|
7
|
+
composable
|
8
|
+
built_in
|
9
|
+
generated_descriptions
|
10
|
+
dsl
|
11
|
+
matcher_delegator
|
12
|
+
aliased_matcher
|
13
|
+
expecteds_for_multiple_diffs
|
14
|
+
].each { |file| RSpec::Support.require_rspec_matchers(file) }
|
15
|
+
|
16
|
+
# RSpec's top level namespace. All of rspec-expectations is contained
|
17
|
+
# in the `RSpec::Expectations` and `RSpec::Matchers` namespaces.
|
18
|
+
module RSpec
|
19
|
+
# RSpec::Matchers provides a number of useful matchers we use to define
|
20
|
+
# expectations. Any object that implements the [matcher protocol](Matchers/MatcherProtocol)
|
21
|
+
# can be used as a matcher.
|
22
|
+
#
|
23
|
+
# ## Predicates
|
24
|
+
#
|
25
|
+
# In addition to matchers that are defined explicitly, RSpec will create
|
26
|
+
# custom matchers on the fly for any arbitrary predicate, giving your specs a
|
27
|
+
# much more natural language feel.
|
28
|
+
#
|
29
|
+
# A Ruby predicate is a method that ends with a "?" and returns true or false.
|
30
|
+
# Common examples are `empty?`, `nil?`, and `instance_of?`.
|
31
|
+
#
|
32
|
+
# All you need to do is write `expect(..).to be_` followed by the predicate
|
33
|
+
# without the question mark, and RSpec will figure it out from there.
|
34
|
+
# For example:
|
35
|
+
#
|
36
|
+
# expect([]).to be_empty # => [].empty?() | passes
|
37
|
+
# expect([]).not_to be_empty # => [].empty?() | fails
|
38
|
+
#
|
39
|
+
# In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
|
40
|
+
# and "be_an_", making your specs read much more naturally:
|
41
|
+
#
|
42
|
+
# expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes
|
43
|
+
#
|
44
|
+
# expect(3).to be_a_kind_of(Integer) # => 3.kind_of?(Numeric) | passes
|
45
|
+
# expect(3).to be_a_kind_of(Numeric) # => 3.kind_of?(Numeric) | passes
|
46
|
+
# expect(3).to be_an_instance_of(Integer) # => 3.instance_of?(Integer) | passes
|
47
|
+
# expect(3).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
|
48
|
+
#
|
49
|
+
# RSpec will also create custom matchers for predicates like `has_key?`. To
|
50
|
+
# use this feature, just state that the object should have_key(:key) and RSpec will
|
51
|
+
# call has_key?(:key) on the target. For example:
|
52
|
+
#
|
53
|
+
# expect(:a => "A").to have_key(:a)
|
54
|
+
# expect(:a => "A").to have_key(:b) # fails
|
55
|
+
#
|
56
|
+
# You can use this feature to invoke any predicate that begins with "has_", whether it is
|
57
|
+
# part of the Ruby libraries (like `Hash#has_key?`) or a method you wrote on your own class.
|
58
|
+
#
|
59
|
+
# Note that RSpec does not provide composable aliases for these dynamic predicate
|
60
|
+
# matchers. You can easily define your own aliases, though:
|
61
|
+
#
|
62
|
+
# RSpec::Matchers.alias_matcher :a_user_who_is_an_admin, :be_an_admin
|
63
|
+
# expect(user_list).to include(a_user_who_is_an_admin)
|
64
|
+
#
|
65
|
+
# ## Alias Matchers
|
66
|
+
#
|
67
|
+
# With {RSpec::Matchers.alias_matcher}, you can easily create an
|
68
|
+
# alternate name for a given matcher.
|
69
|
+
#
|
70
|
+
# The description will also change according to the new name:
|
71
|
+
#
|
72
|
+
# RSpec::Matchers.alias_matcher :a_list_that_sums_to, :sum_to
|
73
|
+
# sum_to(3).description # => "sum to 3"
|
74
|
+
# a_list_that_sums_to(3).description # => "a list that sums to 3"
|
75
|
+
#
|
76
|
+
# or you can specify a custom description like this:
|
77
|
+
#
|
78
|
+
# RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
|
79
|
+
# description.sub("be sorted by", "a list sorted by")
|
80
|
+
# end
|
81
|
+
#
|
82
|
+
# be_sorted_by(:age).description # => "be sorted by age"
|
83
|
+
# a_list_sorted_by(:age).description # => "a list sorted by age"
|
84
|
+
#
|
85
|
+
# ## Custom Matchers
|
86
|
+
#
|
87
|
+
# When you find that none of the stock matchers provide a natural feeling
|
88
|
+
# expectation, you can very easily write your own using RSpec's matcher DSL
|
89
|
+
# or writing one from scratch.
|
90
|
+
#
|
91
|
+
# ### Matcher DSL
|
92
|
+
#
|
93
|
+
# Imagine that you are writing a game in which players can be in various
|
94
|
+
# zones on a virtual board. To specify that bob should be in zone 4, you
|
95
|
+
# could say:
|
96
|
+
#
|
97
|
+
# expect(bob.current_zone).to eql(Zone.new("4"))
|
98
|
+
#
|
99
|
+
# But you might find it more expressive to say:
|
100
|
+
#
|
101
|
+
# expect(bob).to be_in_zone("4")
|
102
|
+
#
|
103
|
+
# and/or
|
104
|
+
#
|
105
|
+
# expect(bob).not_to be_in_zone("3")
|
106
|
+
#
|
107
|
+
# You can create such a matcher like so:
|
108
|
+
#
|
109
|
+
# RSpec::Matchers.define :be_in_zone do |zone|
|
110
|
+
# match do |player|
|
111
|
+
# player.in_zone?(zone)
|
112
|
+
# end
|
113
|
+
# end
|
114
|
+
#
|
115
|
+
# This will generate a <tt>be_in_zone</tt> method that returns a matcher
|
116
|
+
# with logical default messages for failures. You can override the failure
|
117
|
+
# messages and the generated description as follows:
|
118
|
+
#
|
119
|
+
# RSpec::Matchers.define :be_in_zone do |zone|
|
120
|
+
# match do |player|
|
121
|
+
# player.in_zone?(zone)
|
122
|
+
# end
|
123
|
+
#
|
124
|
+
# failure_message do |player|
|
125
|
+
# # generate and return the appropriate string.
|
126
|
+
# end
|
127
|
+
#
|
128
|
+
# failure_message_when_negated do |player|
|
129
|
+
# # generate and return the appropriate string.
|
130
|
+
# end
|
131
|
+
#
|
132
|
+
# description do
|
133
|
+
# # generate and return the appropriate string.
|
134
|
+
# end
|
135
|
+
# end
|
136
|
+
#
|
137
|
+
# Each of the message-generation methods has access to the block arguments
|
138
|
+
# passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
|
139
|
+
# failure message methods (<tt>failure_message</tt> and
|
140
|
+
# <tt>failure_message_when_negated</tt>) are passed the actual value (the
|
141
|
+
# receiver of <tt>expect(..)</tt> or <tt>expect(..).not_to</tt>).
|
142
|
+
#
|
143
|
+
# ### Custom Matcher from scratch
|
144
|
+
#
|
145
|
+
# You could also write a custom matcher from scratch, as follows:
|
146
|
+
#
|
147
|
+
# class BeInZone
|
148
|
+
# def initialize(expected)
|
149
|
+
# @expected = expected
|
150
|
+
# end
|
151
|
+
#
|
152
|
+
# def matches?(target)
|
153
|
+
# @target = target
|
154
|
+
# @target.current_zone.eql?(Zone.new(@expected))
|
155
|
+
# end
|
156
|
+
#
|
157
|
+
# def failure_message
|
158
|
+
# "expected #{@target.inspect} to be in Zone #{@expected}"
|
159
|
+
# end
|
160
|
+
#
|
161
|
+
# def failure_message_when_negated
|
162
|
+
# "expected #{@target.inspect} not to be in Zone #{@expected}"
|
163
|
+
# end
|
164
|
+
# end
|
165
|
+
#
|
166
|
+
# ... and a method like this:
|
167
|
+
#
|
168
|
+
# def be_in_zone(expected)
|
169
|
+
# BeInZone.new(expected)
|
170
|
+
# end
|
171
|
+
#
|
172
|
+
# And then expose the method to your specs. This is normally done
|
173
|
+
# by including the method and the class in a module, which is then
|
174
|
+
# included in your spec:
|
175
|
+
#
|
176
|
+
# module CustomGameMatchers
|
177
|
+
# class BeInZone
|
178
|
+
# # ...
|
179
|
+
# end
|
180
|
+
#
|
181
|
+
# def be_in_zone(expected)
|
182
|
+
# # ...
|
183
|
+
# end
|
184
|
+
# end
|
185
|
+
#
|
186
|
+
# describe "Player behaviour" do
|
187
|
+
# include CustomGameMatchers
|
188
|
+
# # ...
|
189
|
+
# end
|
190
|
+
#
|
191
|
+
# or you can include in globally in a spec_helper.rb file <tt>require</tt>d
|
192
|
+
# from your spec file(s):
|
193
|
+
#
|
194
|
+
# RSpec::configure do |config|
|
195
|
+
# config.include(CustomGameMatchers)
|
196
|
+
# end
|
197
|
+
#
|
198
|
+
# ### Making custom matchers composable
|
199
|
+
#
|
200
|
+
# RSpec's built-in matchers are designed to be composed, in expressions like:
|
201
|
+
#
|
202
|
+
# expect(["barn", 2.45]).to contain_exactly(
|
203
|
+
# a_value_within(0.1).of(2.5),
|
204
|
+
# a_string_starting_with("bar")
|
205
|
+
# )
|
206
|
+
#
|
207
|
+
# Custom matchers can easily participate in composed matcher expressions like these.
|
208
|
+
# Include {RSpec::Matchers::Composable} in your custom matcher to make it support
|
209
|
+
# being composed (matchers defined using the DSL have this included automatically).
|
210
|
+
# Within your matcher's `matches?` method (or the `match` block, if using the DSL),
|
211
|
+
# use `values_match?(expected, actual)` rather than `expected == actual`.
|
212
|
+
# Under the covers, `values_match?` is able to match arbitrary
|
213
|
+
# nested data structures containing a mix of both matchers and non-matcher objects.
|
214
|
+
# It uses `===` and `==` to perform the matching, considering the values to
|
215
|
+
# match if either returns `true`. The `Composable` mixin also provides some helper
|
216
|
+
# methods for surfacing the matcher descriptions within your matcher's description
|
217
|
+
# or failure messages.
|
218
|
+
#
|
219
|
+
# RSpec's built-in matchers each have a number of aliases that rephrase the matcher
|
220
|
+
# from a verb phrase (such as `be_within`) to a noun phrase (such as `a_value_within`),
|
221
|
+
# which reads better when the matcher is passed as an argument in a composed matcher
|
222
|
+
# expressions, and also uses the noun-phrase wording in the matcher's `description`,
|
223
|
+
# for readable failure messages. You can alias your custom matchers in similar fashion
|
224
|
+
# using {RSpec::Matchers.alias_matcher}.
|
225
|
+
#
|
226
|
+
# ## Negated Matchers
|
227
|
+
#
|
228
|
+
# Sometimes if you want to test for the opposite using a more descriptive name
|
229
|
+
# instead of using `not_to`, you can use {RSpec::Matchers.define_negated_matcher}:
|
230
|
+
#
|
231
|
+
# RSpec::Matchers.define_negated_matcher :exclude, :include
|
232
|
+
# include(1, 2).description # => "include 1 and 2"
|
233
|
+
# exclude(1, 2).description # => "exclude 1 and 2"
|
234
|
+
#
|
235
|
+
# While the most obvious negated form may be to add a `not_` prefix,
|
236
|
+
# the failure messages you get with that form can be confusing (e.g.
|
237
|
+
# "expected [actual] to not [verb], but did not"). We've found it works
|
238
|
+
# best to find a more positive name for the negated form, such as
|
239
|
+
# `avoid_changing` rather than `not_change`.
|
240
|
+
#
|
241
|
+
module Matchers
|
242
|
+
extend ::RSpec::Matchers::DSL
|
243
|
+
|
244
|
+
# @!macro [attach] alias_matcher
|
245
|
+
# @!parse
|
246
|
+
# alias $1 $2
|
247
|
+
# @!visibility private
|
248
|
+
# We define this override here so we can attach a YARD macro to it.
|
249
|
+
# It ensures that our docs list all the matcher aliases.
|
250
|
+
def self.alias_matcher(*args, &block)
|
251
|
+
super(*args, &block)
|
252
|
+
end
|
253
|
+
|
254
|
+
# @!method self.alias_matcher(new_name, old_name, options={}, &description_override)
|
255
|
+
# Extended from {RSpec::Matchers::DSL#alias_matcher}.
|
256
|
+
|
257
|
+
# @!method self.define(name, &declarations)
|
258
|
+
# Extended from {RSpec::Matchers::DSL#define}.
|
259
|
+
|
260
|
+
# @!method self.define_negated_matcher(negated_name, base_name, &description_override)
|
261
|
+
# Extended from {RSpec::Matchers::DSL#define_negated_matcher}.
|
262
|
+
|
263
|
+
# @method expect
|
264
|
+
# Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
|
265
|
+
# `ExpectationTarget`.
|
266
|
+
# @example
|
267
|
+
# expect(actual).to eq(expected)
|
268
|
+
# expect(actual).not_to eq(expected)
|
269
|
+
# @return [Expectations::ExpectationTarget]
|
270
|
+
# @see Expectations::ExpectationTarget#to
|
271
|
+
# @see Expectations::ExpectationTarget#not_to
|
272
|
+
|
273
|
+
# Allows multiple expectations in the provided block to fail, and then
|
274
|
+
# aggregates them into a single exception, rather than aborting on the
|
275
|
+
# first expectation failure like normal. This allows you to see all
|
276
|
+
# failures from an entire set of expectations without splitting each
|
277
|
+
# off into its own example (which may slow things down if the example
|
278
|
+
# setup is expensive).
|
279
|
+
#
|
280
|
+
# @param label [String] label for this aggregation block, which will be
|
281
|
+
# included in the aggregated exception message.
|
282
|
+
# @param metadata [Hash] additional metadata about this failure aggregation
|
283
|
+
# block. If multiple expectations fail, it will be exposed from the
|
284
|
+
# {Expectations::MultipleExpectationsNotMetError} exception. Mostly
|
285
|
+
# intended for internal RSpec use but you can use it as well.
|
286
|
+
# @yield Block containing as many expectation as you want. The block is
|
287
|
+
# simply yielded to, so you can trust that anything that works outside
|
288
|
+
# the block should work within it.
|
289
|
+
# @raise [Expectations::MultipleExpectationsNotMetError] raised when
|
290
|
+
# multiple expectations fail.
|
291
|
+
# @raise [Expectations::ExpectationNotMetError] raised when a single
|
292
|
+
# expectation fails.
|
293
|
+
# @raise [Exception] other sorts of exceptions will be raised as normal.
|
294
|
+
#
|
295
|
+
# @example
|
296
|
+
# aggregate_failures("verifying response") do
|
297
|
+
# expect(response.status).to eq(200)
|
298
|
+
# expect(response.headers).to include("Content-Type" => "text/plain")
|
299
|
+
# expect(response.body).to include("Success")
|
300
|
+
# end
|
301
|
+
#
|
302
|
+
# @note The implementation of this feature uses a thread-local variable,
|
303
|
+
# which means that if you have an expectation failure in another thread,
|
304
|
+
# it'll abort like normal.
|
305
|
+
def aggregate_failures(label=nil, metadata={}, &block)
|
306
|
+
Expectations::FailureAggregator.new(label, metadata).aggregate(&block)
|
307
|
+
end
|
308
|
+
|
309
|
+
# Passes if actual is truthy (anything but false or nil)
|
310
|
+
def be_truthy
|
311
|
+
BuiltIn::BeTruthy.new
|
312
|
+
end
|
313
|
+
alias_matcher :a_truthy_value, :be_truthy
|
314
|
+
|
315
|
+
# Passes if actual is falsey (false or nil)
|
316
|
+
def be_falsey
|
317
|
+
BuiltIn::BeFalsey.new
|
318
|
+
end
|
319
|
+
alias_matcher :be_falsy, :be_falsey
|
320
|
+
alias_matcher :a_falsey_value, :be_falsey
|
321
|
+
alias_matcher :a_falsy_value, :be_falsey
|
322
|
+
|
323
|
+
# Passes if actual is nil
|
324
|
+
def be_nil
|
325
|
+
BuiltIn::BeNil.new
|
326
|
+
end
|
327
|
+
alias_matcher :a_nil_value, :be_nil
|
328
|
+
|
329
|
+
# @example
|
330
|
+
# expect(actual).to be_truthy
|
331
|
+
# expect(actual).to be_falsey
|
332
|
+
# expect(actual).to be_nil
|
333
|
+
# expect(actual).to be_[arbitrary_predicate](*args)
|
334
|
+
# expect(actual).not_to be_nil
|
335
|
+
# expect(actual).not_to be_[arbitrary_predicate](*args)
|
336
|
+
#
|
337
|
+
# Given true, false, or nil, will pass if actual value is true, false or
|
338
|
+
# nil (respectively). Given no args means the caller should satisfy an if
|
339
|
+
# condition (to be or not to be).
|
340
|
+
#
|
341
|
+
# Predicates are any Ruby method that ends in a "?" and returns true or
|
342
|
+
# false. Given be_ followed by arbitrary_predicate (without the "?"),
|
343
|
+
# RSpec will match convert that into a query against the target object.
|
344
|
+
#
|
345
|
+
# The arbitrary_predicate feature will handle any predicate prefixed with
|
346
|
+
# "be_an_" (e.g. be_an_instance_of), "be_a_" (e.g. be_a_kind_of) or "be_"
|
347
|
+
# (e.g. be_empty), letting you choose the prefix that best suits the
|
348
|
+
# predicate.
|
349
|
+
def be(*args)
|
350
|
+
args.empty? ? Matchers::BuiltIn::Be.new : equal(*args)
|
351
|
+
end
|
352
|
+
alias_matcher :a_value, :be, :klass => AliasedMatcherWithOperatorSupport
|
353
|
+
|
354
|
+
# passes if target.kind_of?(klass)
|
355
|
+
def be_a(klass)
|
356
|
+
be_a_kind_of(klass)
|
357
|
+
end
|
358
|
+
alias_method :be_an, :be_a
|
359
|
+
|
360
|
+
# Passes if actual.instance_of?(expected)
|
361
|
+
#
|
362
|
+
# @example
|
363
|
+
# expect(5).to be_an_instance_of(Integer)
|
364
|
+
# expect(5).not_to be_an_instance_of(Numeric)
|
365
|
+
# expect(5).not_to be_an_instance_of(Float)
|
366
|
+
def be_an_instance_of(expected)
|
367
|
+
BuiltIn::BeAnInstanceOf.new(expected)
|
368
|
+
end
|
369
|
+
alias_method :be_instance_of, :be_an_instance_of
|
370
|
+
alias_matcher :an_instance_of, :be_an_instance_of
|
371
|
+
|
372
|
+
# Passes if actual.kind_of?(expected)
|
373
|
+
#
|
374
|
+
# @example
|
375
|
+
# expect(5).to be_a_kind_of(Integer)
|
376
|
+
# expect(5).to be_a_kind_of(Numeric)
|
377
|
+
# expect(5).not_to be_a_kind_of(Float)
|
378
|
+
def be_a_kind_of(expected)
|
379
|
+
BuiltIn::BeAKindOf.new(expected)
|
380
|
+
end
|
381
|
+
alias_method :be_kind_of, :be_a_kind_of
|
382
|
+
alias_matcher :a_kind_of, :be_a_kind_of
|
383
|
+
|
384
|
+
# Passes if actual.between?(min, max). Works with any Comparable object,
|
385
|
+
# including String, Symbol, Time, or Numeric (Fixnum, Bignum, Integer,
|
386
|
+
# Float, Complex, and Rational).
|
387
|
+
#
|
388
|
+
# By default, `be_between` is inclusive (i.e. passes when given either the max or min value),
|
389
|
+
# but you can make it `exclusive` by chaining that off the matcher.
|
390
|
+
#
|
391
|
+
# @example
|
392
|
+
# expect(5).to be_between(1, 10)
|
393
|
+
# expect(11).not_to be_between(1, 10)
|
394
|
+
# expect(10).not_to be_between(1, 10).exclusive
|
395
|
+
def be_between(min, max)
|
396
|
+
BuiltIn::BeBetween.new(min, max)
|
397
|
+
end
|
398
|
+
alias_matcher :a_value_between, :be_between
|
399
|
+
|
400
|
+
# Passes if actual == expected +/- delta
|
401
|
+
#
|
402
|
+
# @example
|
403
|
+
# expect(result).to be_within(0.5).of(3.0)
|
404
|
+
# expect(result).not_to be_within(0.5).of(3.0)
|
405
|
+
def be_within(delta)
|
406
|
+
BuiltIn::BeWithin.new(delta)
|
407
|
+
end
|
408
|
+
alias_matcher :a_value_within, :be_within
|
409
|
+
alias_matcher :within, :be_within
|
410
|
+
|
411
|
+
# Applied to a proc, specifies that its execution will cause some value to
|
412
|
+
# change.
|
413
|
+
#
|
414
|
+
# @param [Object] receiver
|
415
|
+
# @param [Symbol] message the message to send the receiver
|
416
|
+
#
|
417
|
+
# You can either pass <tt>receiver</tt> and <tt>message</tt>, or a block,
|
418
|
+
# but not both.
|
419
|
+
#
|
420
|
+
# When passing a block, it must use the `{ ... }` format, not
|
421
|
+
# do/end, as `{ ... }` binds to the `change` method, whereas do/end
|
422
|
+
# would errantly bind to the `expect(..).to` or `expect(...).not_to` method.
|
423
|
+
#
|
424
|
+
# You can chain any of the following off of the end to specify details
|
425
|
+
# about the change:
|
426
|
+
#
|
427
|
+
# * `from`
|
428
|
+
# * `to`
|
429
|
+
#
|
430
|
+
# or any one of:
|
431
|
+
#
|
432
|
+
# * `by`
|
433
|
+
# * `by_at_least`
|
434
|
+
# * `by_at_most`
|
435
|
+
#
|
436
|
+
# @example
|
437
|
+
# expect {
|
438
|
+
# team.add_player(player)
|
439
|
+
# }.to change(roster, :count)
|
440
|
+
#
|
441
|
+
# expect {
|
442
|
+
# team.add_player(player)
|
443
|
+
# }.to change(roster, :count).by(1)
|
444
|
+
#
|
445
|
+
# expect {
|
446
|
+
# team.add_player(player)
|
447
|
+
# }.to change(roster, :count).by_at_least(1)
|
448
|
+
#
|
449
|
+
# expect {
|
450
|
+
# team.add_player(player)
|
451
|
+
# }.to change(roster, :count).by_at_most(1)
|
452
|
+
#
|
453
|
+
# string = "string"
|
454
|
+
# expect {
|
455
|
+
# string.reverse!
|
456
|
+
# }.to change { string }.from("string").to("gnirts")
|
457
|
+
#
|
458
|
+
# string = "string"
|
459
|
+
# expect {
|
460
|
+
# string
|
461
|
+
# }.not_to change { string }.from("string")
|
462
|
+
#
|
463
|
+
# expect {
|
464
|
+
# person.happy_birthday
|
465
|
+
# }.to change(person, :birthday).from(32).to(33)
|
466
|
+
#
|
467
|
+
# expect {
|
468
|
+
# employee.develop_great_new_social_networking_app
|
469
|
+
# }.to change(employee, :title).from("Mail Clerk").to("CEO")
|
470
|
+
#
|
471
|
+
# expect {
|
472
|
+
# doctor.leave_office
|
473
|
+
# }.to change(doctor, :sign).from(/is in/).to(/is out/)
|
474
|
+
#
|
475
|
+
# user = User.new(:type => "admin")
|
476
|
+
# expect {
|
477
|
+
# user.symbolize_type
|
478
|
+
# }.to change(user, :type).from(String).to(Symbol)
|
479
|
+
#
|
480
|
+
# == Notes
|
481
|
+
#
|
482
|
+
# Evaluates `receiver.message` or `block` before and after it
|
483
|
+
# evaluates the block passed to `expect`. If the value is the same
|
484
|
+
# object, its before/after `hash` value is used to see if it has changed.
|
485
|
+
# Therefore, your object needs to properly implement `hash` to work correctly
|
486
|
+
# with this matcher.
|
487
|
+
#
|
488
|
+
# `expect( ... ).not_to change` supports the form that specifies `from`
|
489
|
+
# (which specifies what you expect the starting, unchanged value to be)
|
490
|
+
# but does not support forms with subsequent calls to `by`, `by_at_least`,
|
491
|
+
# `by_at_most` or `to`.
|
492
|
+
def change(receiver=nil, message=nil, &block)
|
493
|
+
BuiltIn::Change.new(receiver, message, &block)
|
494
|
+
end
|
495
|
+
alias_matcher :a_block_changing, :change
|
496
|
+
alias_matcher :changing, :change
|
497
|
+
|
498
|
+
# Passes if actual contains all of the expected regardless of order.
|
499
|
+
# This works for collections. Pass in multiple args and it will only
|
500
|
+
# pass if all args are found in collection.
|
501
|
+
#
|
502
|
+
# @note This is also available using the `=~` operator with `should`,
|
503
|
+
# but `=~` is not supported with `expect`.
|
504
|
+
#
|
505
|
+
# @example
|
506
|
+
# expect([1, 2, 3]).to contain_exactly(1, 2, 3)
|
507
|
+
# expect([1, 2, 3]).to contain_exactly(1, 3, 2)
|
508
|
+
#
|
509
|
+
# @see #match_array
|
510
|
+
def contain_exactly(*items)
|
511
|
+
BuiltIn::ContainExactly.new(items)
|
512
|
+
end
|
513
|
+
alias_matcher :a_collection_containing_exactly, :contain_exactly
|
514
|
+
alias_matcher :containing_exactly, :contain_exactly
|
515
|
+
|
516
|
+
# Passes if actual covers expected. This works for
|
517
|
+
# Ranges. You can also pass in multiple args
|
518
|
+
# and it will only pass if all args are found in Range.
|
519
|
+
#
|
520
|
+
# @example
|
521
|
+
# expect(1..10).to cover(5)
|
522
|
+
# expect(1..10).to cover(4, 6)
|
523
|
+
# expect(1..10).to cover(4, 6, 11) # fails
|
524
|
+
# expect(1..10).not_to cover(11)
|
525
|
+
# expect(1..10).not_to cover(5) # fails
|
526
|
+
#
|
527
|
+
# ### Warning:: Ruby >= 1.9 only
|
528
|
+
def cover(*values)
|
529
|
+
BuiltIn::Cover.new(*values)
|
530
|
+
end
|
531
|
+
alias_matcher :a_range_covering, :cover
|
532
|
+
alias_matcher :covering, :cover
|
533
|
+
|
534
|
+
# Matches if the actual value ends with the expected value(s). In the case
|
535
|
+
# of a string, matches against the last `expected.length` characters of the
|
536
|
+
# actual string. In the case of an array, matches against the last
|
537
|
+
# `expected.length` elements of the actual array.
|
538
|
+
#
|
539
|
+
# @example
|
540
|
+
# expect("this string").to end_with "string"
|
541
|
+
# expect([0, 1, 2, 3, 4]).to end_with 4
|
542
|
+
# expect([0, 2, 3, 4, 4]).to end_with 3, 4
|
543
|
+
def end_with(*expected)
|
544
|
+
BuiltIn::EndWith.new(*expected)
|
545
|
+
end
|
546
|
+
alias_matcher :a_collection_ending_with, :end_with
|
547
|
+
alias_matcher :a_string_ending_with, :end_with
|
548
|
+
alias_matcher :ending_with, :end_with
|
549
|
+
|
550
|
+
# Passes if <tt>actual == expected</tt>.
|
551
|
+
#
|
552
|
+
# See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
|
553
|
+
# information about equality in Ruby.
|
554
|
+
#
|
555
|
+
# @example
|
556
|
+
# expect(5).to eq(5)
|
557
|
+
# expect(5).not_to eq(3)
|
558
|
+
def eq(expected)
|
559
|
+
BuiltIn::Eq.new(expected)
|
560
|
+
end
|
561
|
+
alias_matcher :an_object_eq_to, :eq
|
562
|
+
alias_matcher :eq_to, :eq
|
563
|
+
|
564
|
+
# Passes if `actual.eql?(expected)`
|
565
|
+
#
|
566
|
+
# See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
|
567
|
+
# information about equality in Ruby.
|
568
|
+
#
|
569
|
+
# @example
|
570
|
+
# expect(5).to eql(5)
|
571
|
+
# expect(5).not_to eql(3)
|
572
|
+
def eql(expected)
|
573
|
+
BuiltIn::Eql.new(expected)
|
574
|
+
end
|
575
|
+
alias_matcher :an_object_eql_to, :eql
|
576
|
+
alias_matcher :eql_to, :eql
|
577
|
+
|
578
|
+
# Passes if <tt>actual.equal?(expected)</tt> (object identity).
|
579
|
+
#
|
580
|
+
# See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
|
581
|
+
# information about equality in Ruby.
|
582
|
+
#
|
583
|
+
# @example
|
584
|
+
# expect(5).to equal(5) # Integers are equal
|
585
|
+
# expect("5").not_to equal("5") # Strings that look the same are not the same object
|
586
|
+
def equal(expected)
|
587
|
+
BuiltIn::Equal.new(expected)
|
588
|
+
end
|
589
|
+
alias_matcher :an_object_equal_to, :equal
|
590
|
+
alias_matcher :equal_to, :equal
|
591
|
+
|
592
|
+
# Passes if `actual.exist?` or `actual.exists?`
|
593
|
+
#
|
594
|
+
# @example
|
595
|
+
# expect(File).to exist("path/to/file")
|
596
|
+
def exist(*args)
|
597
|
+
BuiltIn::Exist.new(*args)
|
598
|
+
end
|
599
|
+
alias_matcher :an_object_existing, :exist
|
600
|
+
alias_matcher :existing, :exist
|
601
|
+
|
602
|
+
# Passes if actual's attribute values match the expected attributes hash.
|
603
|
+
# This works no matter how you define your attribute readers.
|
604
|
+
#
|
605
|
+
# @example
|
606
|
+
# Person = Struct.new(:name, :age)
|
607
|
+
# person = Person.new("Bob", 32)
|
608
|
+
#
|
609
|
+
# expect(person).to have_attributes(:name => "Bob", :age => 32)
|
610
|
+
# expect(person).to have_attributes(:name => a_string_starting_with("B"), :age => (a_value > 30) )
|
611
|
+
#
|
612
|
+
# @note It will fail if actual doesn't respond to any of the expected attributes.
|
613
|
+
#
|
614
|
+
# @example
|
615
|
+
# expect(person).to have_attributes(:color => "red")
|
616
|
+
def have_attributes(expected)
|
617
|
+
BuiltIn::HaveAttributes.new(expected)
|
618
|
+
end
|
619
|
+
alias_matcher :an_object_having_attributes, :have_attributes
|
620
|
+
alias_matcher :having_attributes, :have_attributes
|
621
|
+
|
622
|
+
# Passes if actual includes expected. This works for
|
623
|
+
# collections and Strings. You can also pass in multiple args
|
624
|
+
# and it will only pass if all args are found in collection.
|
625
|
+
#
|
626
|
+
# @example
|
627
|
+
# expect([1,2,3]).to include(3)
|
628
|
+
# expect([1,2,3]).to include(2,3)
|
629
|
+
# expect([1,2,3]).to include(2,3,4) # fails
|
630
|
+
# expect([1,2,3]).not_to include(4)
|
631
|
+
# expect("spread").to include("read")
|
632
|
+
# expect("spread").not_to include("red")
|
633
|
+
# expect(:a => 1, :b => 2).to include(:a)
|
634
|
+
# expect(:a => 1, :b => 2).to include(:a, :b)
|
635
|
+
# expect(:a => 1, :b => 2).to include(:a => 1)
|
636
|
+
# expect(:a => 1, :b => 2).to include(:b => 2, :a => 1)
|
637
|
+
# expect(:a => 1, :b => 2).to include(:c) # fails
|
638
|
+
# expect(:a => 1, :b => 2).not_to include(:a => 2)
|
639
|
+
def include(*expected)
|
640
|
+
BuiltIn::Include.new(*expected)
|
641
|
+
end
|
642
|
+
alias_matcher :a_collection_including, :include
|
643
|
+
alias_matcher :a_string_including, :include
|
644
|
+
alias_matcher :a_hash_including, :include
|
645
|
+
alias_matcher :including, :include
|
646
|
+
|
647
|
+
# Passes if the provided matcher passes when checked against all
|
648
|
+
# elements of the collection.
|
649
|
+
#
|
650
|
+
# @example
|
651
|
+
# expect([1, 3, 5]).to all be_odd
|
652
|
+
# expect([1, 3, 6]).to all be_odd # fails
|
653
|
+
#
|
654
|
+
# @note The negative form `not_to all` is not supported. Instead
|
655
|
+
# use `not_to include` or pass a negative form of a matcher
|
656
|
+
# as the argument (e.g. `all exclude(:foo)`).
|
657
|
+
#
|
658
|
+
# @note You can also use this with compound matchers as well.
|
659
|
+
#
|
660
|
+
# @example
|
661
|
+
# expect([1, 3, 5]).to all( be_odd.and be_an(Integer) )
|
662
|
+
def all(expected)
|
663
|
+
BuiltIn::All.new(expected)
|
664
|
+
end
|
665
|
+
|
666
|
+
# Given a `Regexp` or `String`, passes if `actual.match(pattern)`
|
667
|
+
# Given an arbitrary nested data structure (e.g. arrays and hashes),
|
668
|
+
# matches if `expected === actual` || `actual == expected` for each
|
669
|
+
# pair of elements.
|
670
|
+
#
|
671
|
+
# @example
|
672
|
+
# expect(email).to match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
|
673
|
+
# expect(email).to match("@example.com")
|
674
|
+
#
|
675
|
+
# @example
|
676
|
+
# hash = {
|
677
|
+
# :a => {
|
678
|
+
# :b => ["foo", 5],
|
679
|
+
# :c => { :d => 2.05 }
|
680
|
+
# }
|
681
|
+
# }
|
682
|
+
#
|
683
|
+
# expect(hash).to match(
|
684
|
+
# :a => {
|
685
|
+
# :b => a_collection_containing_exactly(
|
686
|
+
# a_string_starting_with("f"),
|
687
|
+
# an_instance_of(Integer)
|
688
|
+
# ),
|
689
|
+
# :c => { :d => (a_value < 3) }
|
690
|
+
# }
|
691
|
+
# )
|
692
|
+
#
|
693
|
+
# @note The `match_regex` alias is deprecated and is not recommended for use.
|
694
|
+
# It was added in 2.12.1 to facilitate its use from within custom
|
695
|
+
# matchers (due to how the custom matcher DSL was evaluated in 2.x,
|
696
|
+
# `match` could not be used there), but is no longer needed in 3.x.
|
697
|
+
def match(expected)
|
698
|
+
BuiltIn::Match.new(expected)
|
699
|
+
end
|
700
|
+
alias_matcher :match_regex, :match
|
701
|
+
alias_matcher :an_object_matching, :match
|
702
|
+
alias_matcher :a_string_matching, :match
|
703
|
+
alias_matcher :matching, :match
|
704
|
+
|
705
|
+
# An alternate form of `contain_exactly` that accepts
|
706
|
+
# the expected contents as a single array arg rather
|
707
|
+
# that splatted out as individual items.
|
708
|
+
#
|
709
|
+
# @example
|
710
|
+
# expect(results).to contain_exactly(1, 2)
|
711
|
+
# # is identical to:
|
712
|
+
# expect(results).to match_array([1, 2])
|
713
|
+
#
|
714
|
+
# @see #contain_exactly
|
715
|
+
def match_array(items)
|
716
|
+
contain_exactly(*items)
|
717
|
+
end
|
718
|
+
|
719
|
+
# With no arg, passes if the block outputs `to_stdout` or `to_stderr`.
|
720
|
+
# With a string, passes if the block outputs that specific string `to_stdout` or `to_stderr`.
|
721
|
+
# With a regexp or matcher, passes if the block outputs a string `to_stdout` or `to_stderr` that matches.
|
722
|
+
#
|
723
|
+
# To capture output from any spawned subprocess as well, use `to_stdout_from_any_process` or
|
724
|
+
# `to_stderr_from_any_process`. Output from any process that inherits the main process's corresponding
|
725
|
+
# standard stream will be captured.
|
726
|
+
#
|
727
|
+
# @example
|
728
|
+
# expect { print 'foo' }.to output.to_stdout
|
729
|
+
# expect { print 'foo' }.to output('foo').to_stdout
|
730
|
+
# expect { print 'foo' }.to output(/foo/).to_stdout
|
731
|
+
#
|
732
|
+
# expect { do_something }.to_not output.to_stdout
|
733
|
+
#
|
734
|
+
# expect { warn('foo') }.to output.to_stderr
|
735
|
+
# expect { warn('foo') }.to output('foo').to_stderr
|
736
|
+
# expect { warn('foo') }.to output(/foo/).to_stderr
|
737
|
+
#
|
738
|
+
# expect { do_something }.to_not output.to_stderr
|
739
|
+
#
|
740
|
+
# expect { system('echo foo') }.to output("foo\n").to_stdout_from_any_process
|
741
|
+
# expect { system('echo foo', out: :err) }.to output("foo\n").to_stderr_from_any_process
|
742
|
+
#
|
743
|
+
# @note `to_stdout` and `to_stderr` work by temporarily replacing `$stdout` or `$stderr`,
|
744
|
+
# so they're not able to intercept stream output that explicitly uses `STDOUT`/`STDERR`
|
745
|
+
# or that uses a reference to `$stdout`/`$stderr` that was stored before the
|
746
|
+
# matcher was used.
|
747
|
+
# @note `to_stdout_from_any_process` and `to_stderr_from_any_process` use Tempfiles, and
|
748
|
+
# are thus significantly (~30x) slower than `to_stdout` and `to_stderr`.
|
749
|
+
def output(expected=nil)
|
750
|
+
BuiltIn::Output.new(expected)
|
751
|
+
end
|
752
|
+
alias_matcher :a_block_outputting, :output
|
753
|
+
|
754
|
+
# With no args, matches if any error is raised.
|
755
|
+
# With a named error, matches only if that specific error is raised.
|
756
|
+
# With a named error and messsage specified as a String, matches only if both match.
|
757
|
+
# With a named error and messsage specified as a Regexp, matches only if both match.
|
758
|
+
# Pass an optional block to perform extra verifications on the exception matched
|
759
|
+
#
|
760
|
+
# @example
|
761
|
+
# expect { do_something_risky }.to raise_error
|
762
|
+
# expect { do_something_risky }.to raise_error(PoorRiskDecisionError)
|
763
|
+
# expect { do_something_risky }.to raise_error(PoorRiskDecisionError) { |error| expect(error.data).to eq 42 }
|
764
|
+
# expect { do_something_risky }.to raise_error(PoorRiskDecisionError, "that was too risky")
|
765
|
+
# expect { do_something_risky }.to raise_error(PoorRiskDecisionError, /oo ri/)
|
766
|
+
#
|
767
|
+
# expect { do_something_risky }.not_to raise_error
|
768
|
+
def raise_error(error=nil, message=nil, &block)
|
769
|
+
BuiltIn::RaiseError.new(error, message, &block)
|
770
|
+
end
|
771
|
+
alias_method :raise_exception, :raise_error
|
772
|
+
|
773
|
+
alias_matcher :a_block_raising, :raise_error do |desc|
|
774
|
+
desc.sub("raise", "a block raising")
|
775
|
+
end
|
776
|
+
|
777
|
+
alias_matcher :raising, :raise_error do |desc|
|
778
|
+
desc.sub("raise", "raising")
|
779
|
+
end
|
780
|
+
|
781
|
+
# Matches if the target object responds to all of the names
|
782
|
+
# provided. Names can be Strings or Symbols.
|
783
|
+
#
|
784
|
+
# @example
|
785
|
+
# expect("string").to respond_to(:length)
|
786
|
+
#
|
787
|
+
def respond_to(*names)
|
788
|
+
BuiltIn::RespondTo.new(*names)
|
789
|
+
end
|
790
|
+
alias_matcher :an_object_responding_to, :respond_to
|
791
|
+
alias_matcher :responding_to, :respond_to
|
792
|
+
|
793
|
+
# Passes if the submitted block returns true. Yields target to the
|
794
|
+
# block.
|
795
|
+
#
|
796
|
+
# Generally speaking, this should be thought of as a last resort when
|
797
|
+
# you can't find any other way to specify the behaviour you wish to
|
798
|
+
# specify.
|
799
|
+
#
|
800
|
+
# If you do find yourself in such a situation, you could always write
|
801
|
+
# a custom matcher, which would likely make your specs more expressive.
|
802
|
+
#
|
803
|
+
# @param description [String] optional description to be used for this matcher.
|
804
|
+
#
|
805
|
+
# @example
|
806
|
+
# expect(5).to satisfy { |n| n > 3 }
|
807
|
+
# expect(5).to satisfy("be greater than 3") { |n| n > 3 }
|
808
|
+
def satisfy(description=nil, &block)
|
809
|
+
BuiltIn::Satisfy.new(description, &block)
|
810
|
+
end
|
811
|
+
alias_matcher :an_object_satisfying, :satisfy
|
812
|
+
alias_matcher :satisfying, :satisfy
|
813
|
+
|
814
|
+
# Matches if the actual value starts with the expected value(s). In the
|
815
|
+
# case of a string, matches against the first `expected.length` characters
|
816
|
+
# of the actual string. In the case of an array, matches against the first
|
817
|
+
# `expected.length` elements of the actual array.
|
818
|
+
#
|
819
|
+
# @example
|
820
|
+
# expect("this string").to start_with "this s"
|
821
|
+
# expect([0, 1, 2, 3, 4]).to start_with 0
|
822
|
+
# expect([0, 2, 3, 4, 4]).to start_with 0, 1
|
823
|
+
def start_with(*expected)
|
824
|
+
BuiltIn::StartWith.new(*expected)
|
825
|
+
end
|
826
|
+
alias_matcher :a_collection_starting_with, :start_with
|
827
|
+
alias_matcher :a_string_starting_with, :start_with
|
828
|
+
alias_matcher :starting_with, :start_with
|
829
|
+
|
830
|
+
# Given no argument, matches if a proc throws any Symbol.
|
831
|
+
#
|
832
|
+
# Given a Symbol, matches if the given proc throws the specified Symbol.
|
833
|
+
#
|
834
|
+
# Given a Symbol and an arg, matches if the given proc throws the
|
835
|
+
# specified Symbol with the specified arg.
|
836
|
+
#
|
837
|
+
# @example
|
838
|
+
# expect { do_something_risky }.to throw_symbol
|
839
|
+
# expect { do_something_risky }.to throw_symbol(:that_was_risky)
|
840
|
+
# expect { do_something_risky }.to throw_symbol(:that_was_risky, 'culprit')
|
841
|
+
#
|
842
|
+
# expect { do_something_risky }.not_to throw_symbol
|
843
|
+
# expect { do_something_risky }.not_to throw_symbol(:that_was_risky)
|
844
|
+
# expect { do_something_risky }.not_to throw_symbol(:that_was_risky, 'culprit')
|
845
|
+
def throw_symbol(expected_symbol=nil, expected_arg=nil)
|
846
|
+
BuiltIn::ThrowSymbol.new(expected_symbol, expected_arg)
|
847
|
+
end
|
848
|
+
|
849
|
+
alias_matcher :a_block_throwing, :throw_symbol do |desc|
|
850
|
+
desc.sub("throw", "a block throwing")
|
851
|
+
end
|
852
|
+
|
853
|
+
alias_matcher :throwing, :throw_symbol do |desc|
|
854
|
+
desc.sub("throw", "throwing")
|
855
|
+
end
|
856
|
+
|
857
|
+
# Passes if the method called in the expect block yields, regardless
|
858
|
+
# of whether or not arguments are yielded.
|
859
|
+
#
|
860
|
+
# @example
|
861
|
+
# expect { |b| 5.tap(&b) }.to yield_control
|
862
|
+
# expect { |b| "a".to_sym(&b) }.not_to yield_control
|
863
|
+
#
|
864
|
+
# @note Your expect block must accept a parameter and pass it on to
|
865
|
+
# the method-under-test as a block.
|
866
|
+
def yield_control
|
867
|
+
BuiltIn::YieldControl.new
|
868
|
+
end
|
869
|
+
alias_matcher :a_block_yielding_control, :yield_control
|
870
|
+
alias_matcher :yielding_control, :yield_control
|
871
|
+
|
872
|
+
# Passes if the method called in the expect block yields with
|
873
|
+
# no arguments. Fails if it does not yield, or yields with arguments.
|
874
|
+
#
|
875
|
+
# @example
|
876
|
+
# expect { |b| User.transaction(&b) }.to yield_with_no_args
|
877
|
+
# expect { |b| 5.tap(&b) }.not_to yield_with_no_args # because it yields with `5`
|
878
|
+
# expect { |b| "a".to_sym(&b) }.not_to yield_with_no_args # because it does not yield
|
879
|
+
#
|
880
|
+
# @note Your expect block must accept a parameter and pass it on to
|
881
|
+
# the method-under-test as a block.
|
882
|
+
# @note This matcher is not designed for use with methods that yield
|
883
|
+
# multiple times.
|
884
|
+
def yield_with_no_args
|
885
|
+
BuiltIn::YieldWithNoArgs.new
|
886
|
+
end
|
887
|
+
alias_matcher :a_block_yielding_with_no_args, :yield_with_no_args
|
888
|
+
alias_matcher :yielding_with_no_args, :yield_with_no_args
|
889
|
+
|
890
|
+
# Given no arguments, matches if the method called in the expect
|
891
|
+
# block yields with arguments (regardless of what they are or how
|
892
|
+
# many there are).
|
893
|
+
#
|
894
|
+
# Given arguments, matches if the method called in the expect block
|
895
|
+
# yields with arguments that match the given arguments.
|
896
|
+
#
|
897
|
+
# Argument matching is done using `===` (the case match operator)
|
898
|
+
# and `==`. If the expected and actual arguments match with either
|
899
|
+
# operator, the matcher will pass.
|
900
|
+
#
|
901
|
+
# @example
|
902
|
+
# expect { |b| 5.tap(&b) }.to yield_with_args # because #tap yields an arg
|
903
|
+
# expect { |b| 5.tap(&b) }.to yield_with_args(5) # because 5 == 5
|
904
|
+
# expect { |b| 5.tap(&b) }.to yield_with_args(Integer) # because Integer === 5
|
905
|
+
# expect { |b| File.open("f.txt", &b) }.to yield_with_args(/txt/) # because /txt/ === "f.txt"
|
906
|
+
#
|
907
|
+
# expect { |b| User.transaction(&b) }.not_to yield_with_args # because it yields no args
|
908
|
+
# expect { |b| 5.tap(&b) }.not_to yield_with_args(1, 2, 3)
|
909
|
+
#
|
910
|
+
# @note Your expect block must accept a parameter and pass it on to
|
911
|
+
# the method-under-test as a block.
|
912
|
+
# @note This matcher is not designed for use with methods that yield
|
913
|
+
# multiple times.
|
914
|
+
def yield_with_args(*args)
|
915
|
+
BuiltIn::YieldWithArgs.new(*args)
|
916
|
+
end
|
917
|
+
alias_matcher :a_block_yielding_with_args, :yield_with_args
|
918
|
+
alias_matcher :yielding_with_args, :yield_with_args
|
919
|
+
|
920
|
+
# Designed for use with methods that repeatedly yield (such as
|
921
|
+
# iterators). Passes if the method called in the expect block yields
|
922
|
+
# multiple times with arguments matching those given.
|
923
|
+
#
|
924
|
+
# Argument matching is done using `===` (the case match operator)
|
925
|
+
# and `==`. If the expected and actual arguments match with either
|
926
|
+
# operator, the matcher will pass.
|
927
|
+
#
|
928
|
+
# @example
|
929
|
+
# expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3)
|
930
|
+
# expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [:b, 2])
|
931
|
+
# expect { |b| [1, 2, 3].each(&b) }.not_to yield_successive_args(1, 2)
|
932
|
+
#
|
933
|
+
# @note Your expect block must accept a parameter and pass it on to
|
934
|
+
# the method-under-test as a block.
|
935
|
+
def yield_successive_args(*args)
|
936
|
+
BuiltIn::YieldSuccessiveArgs.new(*args)
|
937
|
+
end
|
938
|
+
alias_matcher :a_block_yielding_successive_args, :yield_successive_args
|
939
|
+
alias_matcher :yielding_successive_args, :yield_successive_args
|
940
|
+
|
941
|
+
# Delegates to {RSpec::Expectations.configuration}.
|
942
|
+
# This is here because rspec-core's `expect_with` option
|
943
|
+
# looks for a `configuration` method on the mixin
|
944
|
+
# (`RSpec::Matchers`) to yield to a block.
|
945
|
+
# @return [RSpec::Expectations::Configuration] the configuration object
|
946
|
+
def self.configuration
|
947
|
+
Expectations.configuration
|
948
|
+
end
|
949
|
+
|
950
|
+
private
|
951
|
+
|
952
|
+
BE_PREDICATE_REGEX = /^(be_(?:an?_)?)(.*)/
|
953
|
+
HAS_REGEX = /^(?:have_)(.*)/
|
954
|
+
DYNAMIC_MATCHER_REGEX = Regexp.union(BE_PREDICATE_REGEX, HAS_REGEX)
|
955
|
+
|
956
|
+
def method_missing(method, *args, &block)
|
957
|
+
case method.to_s
|
958
|
+
when BE_PREDICATE_REGEX
|
959
|
+
BuiltIn::BePredicate.new(method, *args, &block)
|
960
|
+
when HAS_REGEX
|
961
|
+
BuiltIn::Has.new(method, *args, &block)
|
962
|
+
else
|
963
|
+
super
|
964
|
+
end
|
965
|
+
end
|
966
|
+
|
967
|
+
if RUBY_VERSION.to_f >= 1.9
|
968
|
+
def respond_to_missing?(method, *)
|
969
|
+
method =~ DYNAMIC_MATCHER_REGEX || super
|
970
|
+
end
|
971
|
+
else # for 1.8.7
|
972
|
+
# :nocov:
|
973
|
+
def respond_to?(method, *)
|
974
|
+
method = method.to_s
|
975
|
+
method =~ DYNAMIC_MATCHER_REGEX || super
|
976
|
+
end
|
977
|
+
public :respond_to?
|
978
|
+
# :nocov:
|
979
|
+
end
|
980
|
+
|
981
|
+
# @api private
|
982
|
+
def self.is_a_matcher?(obj)
|
983
|
+
return true if ::RSpec::Matchers::BuiltIn::BaseMatcher === obj
|
984
|
+
begin
|
985
|
+
return false if obj.respond_to?(:i_respond_to_everything_so_im_not_really_a_matcher)
|
986
|
+
rescue NoMethodError
|
987
|
+
# Some objects, like BasicObject, don't implemented standard
|
988
|
+
# reflection methods.
|
989
|
+
return false
|
990
|
+
end
|
991
|
+
return false unless obj.respond_to?(:matches?)
|
992
|
+
|
993
|
+
obj.respond_to?(:failure_message) ||
|
994
|
+
obj.respond_to?(:failure_message_for_should) # support legacy matchers
|
995
|
+
end
|
996
|
+
|
997
|
+
::RSpec::Support.register_matcher_definition do |obj|
|
998
|
+
is_a_matcher?(obj)
|
999
|
+
end
|
1000
|
+
|
1001
|
+
# @api private
|
1002
|
+
def self.is_a_describable_matcher?(obj)
|
1003
|
+
is_a_matcher?(obj) && obj.respond_to?(:description)
|
1004
|
+
end
|
1005
|
+
|
1006
|
+
if RSpec::Support::Ruby.mri? && RUBY_VERSION[0, 3] == '1.9'
|
1007
|
+
# @api private
|
1008
|
+
# Note that `included` doesn't work for this because it is triggered
|
1009
|
+
# _after_ `RSpec::Matchers` is an ancestor of the inclusion host, rather
|
1010
|
+
# than _before_, like `append_features`. It's important we check this before
|
1011
|
+
# in order to find the cases where it was already previously included.
|
1012
|
+
def self.append_features(mod)
|
1013
|
+
return super if mod < self # `mod < self` indicates a re-inclusion.
|
1014
|
+
|
1015
|
+
subclasses = ObjectSpace.each_object(Class).select { |c| c < mod && c < self }
|
1016
|
+
return super unless subclasses.any?
|
1017
|
+
|
1018
|
+
subclasses.reject! { |s| subclasses.any? { |s2| s < s2 } } # Filter to the root ancestor.
|
1019
|
+
subclasses = subclasses.map { |s| "`#{s}`" }.join(", ")
|
1020
|
+
|
1021
|
+
RSpec.warning "`#{self}` has been included in a superclass (`#{mod}`) " \
|
1022
|
+
"after previously being included in subclasses (#{subclasses}), " \
|
1023
|
+
"which can trigger infinite recursion from `super` due to an MRI 1.9 bug " \
|
1024
|
+
"(https://redmine.ruby-lang.org/issues/3351). To work around this, " \
|
1025
|
+
"either upgrade to MRI 2.0+, include a dup of the module (e.g. " \
|
1026
|
+
"`include #{self}.dup`), or find a way to include `#{self}` in `#{mod}` " \
|
1027
|
+
"before it is included in subclasses (#{subclasses}). See " \
|
1028
|
+
"https://github.com/rspec/rspec-expectations/issues/814 for more info"
|
1029
|
+
|
1030
|
+
super
|
1031
|
+
end
|
1032
|
+
end
|
1033
|
+
end
|
1034
|
+
end
|