Module: RSpec::Matchers
- Extended by:
- DSL
- Included in:
- DSL::Matcher
- Defined in:
- lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/dsl.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/composable.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/be.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/eq.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/all.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/eql.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/has.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/fail_matchers.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/cover.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/equal.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/exist.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/match.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/yield.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/aliased_matcher.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/change.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/output.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/include.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/satisfy.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/english_phrasing.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/matcher_protocol.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/compound.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/matcher_delegator.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/be_within.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/operators.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/be_between.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/be_kind_of.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/respond_to.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/raise_error.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/base_matcher.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/throw_symbol.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/generated_descriptions.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/be_instance_of.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/contain_exactly.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/have_attributes.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/count_expectation.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/built_in/start_or_end_with.rb,
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/expecteds_for_multiple_diffs.rb
Overview
RSpec::Matchers provides a number of useful matchers we use to define expectations. Any object that implements the [matcher protocol](Matchers/MatcherProtocol) can be used as a matcher.
## Predicates
In addition to matchers that are defined explicitly, RSpec will create custom matchers on the fly for any arbitrary predicate, giving your specs a much more natural language feel.
A Ruby predicate is a method that ends with a “?” and returns true or false. Common examples are ‘empty?`, `nil?`, and `instance_of?`.
All you need to do is write ‘expect(..).to be_` followed by the predicate without the question mark, and RSpec will figure it out from there. For example:
expect([]).to be_empty # => [].empty?() | passes
expect([]).not_to be_empty # => [].empty?() | fails
In addition to prefixing the predicate matchers with “be_”, you can also use “be_a_” and “be_an_”, making your specs read much more naturally:
expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes
expect(3).to be_a_kind_of(Integer) # => 3.kind_of?(Numeric) | passes
expect(3).to be_a_kind_of(Numeric) # => 3.kind_of?(Numeric) | passes
expect(3).to be_an_instance_of(Integer) # => 3.instance_of?(Integer) | passes
expect(3).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
RSpec will also create custom matchers for predicates like ‘has_key?`. To use this feature, just state that the object should have_key(:key) and RSpec will call has_key?(:key) on the target. For example:
expect(:a => "A").to have_key(:a)
expect(:a => "A").to have_key(:b) # fails
You can use this feature to invoke any predicate that begins with “has_”, whether it is part of the Ruby libraries (like ‘Hash#has_key?`) or a method you wrote on your own class.
Note that RSpec does not provide composable aliases for these dynamic predicate matchers. You can easily define your own aliases, though:
RSpec::Matchers.alias_matcher :a_user_who_is_an_admin, :be_an_admin
expect(user_list).to include(a_user_who_is_an_admin)
## Alias Matchers
With Matchers.alias_matcher, you can easily create an alternate name for a given matcher.
The description will also change according to the new name:
RSpec::Matchers.alias_matcher :a_list_that_sums_to, :sum_to
sum_to(3).description # => "sum to 3"
a_list_that_sums_to(3).description # => "a list that sums to 3"
or you can specify a custom description like this:
RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
description.sub("be sorted by", "a list sorted by")
end
be_sorted_by(:age).description # => "be sorted by age"
a_list_sorted_by(:age).description # => "a list sorted by age"
## Custom Matchers
When you find that none of the stock matchers provide a natural feeling expectation, you can very easily write your own using RSpec’s matcher DSL or writing one from scratch.
### Matcher DSL
Imagine that you are writing a game in which players can be in various zones on a virtual board. To specify that bob should be in zone 4, you could say:
expect(bob.current_zone).to eql(Zone.new("4"))
But you might find it more expressive to say:
expect(bob).to be_in_zone("4")
and/or
expect(bob).not_to be_in_zone("3")
You can create such a matcher like so:
RSpec::Matchers.define :be_in_zone do |zone|
match do |player|
player.in_zone?(zone)
end
end
This will generate a be_in_zone
method that returns a matcher with logical default messages for failures. You can override the failure messages and the generated description as follows:
RSpec::Matchers.define :be_in_zone do |zone|
match do |player|
player.in_zone?(zone)
end
do |player|
# generate and return the appropriate string.
end
do |player|
# generate and return the appropriate string.
end
description do
# generate and return the appropriate string.
end
end
Each of the message-generation methods has access to the block arguments passed to the create
method (in this case, zone
). The failure message methods (failure_message
and failure_message_when_negated
) are passed the actual value (the receiver of expect(..)
or expect(..).not_to
).
### Custom Matcher from scratch
You could also write a custom matcher from scratch, as follows:
class BeInZone
def initialize(expected)
@expected = expected
end
def matches?(target)
@target = target
@target.current_zone.eql?(Zone.new(@expected))
end
def
"expected #{@target.inspect} to be in Zone #{@expected}"
end
def
"expected #{@target.inspect} not to be in Zone #{@expected}"
end
end
… and a method like this:
def be_in_zone(expected)
BeInZone.new(expected)
end
And then expose the method to your specs. This is normally done by including the method and the class in a module, which is then included in your spec:
module CustomGameMatchers
class BeInZone
# ...
end
def be_in_zone(expected)
# ...
end
end
describe "Player behaviour" do
include CustomGameMatchers
# ...
end
or you can include in globally in a spec_helper.rb file require
d from your spec file(s):
RSpec::configure do |config|
config.include(CustomGameMatchers)
end
### Making custom matchers composable
RSpec’s built-in matchers are designed to be composed, in expressions like:
expect(["barn", 2.45]).to contain_exactly(
a_value_within(0.1).of(2.5),
a_string_starting_with("bar")
)
Custom matchers can easily participate in composed matcher expressions like these. Include Composable in your custom matcher to make it support being composed (matchers defined using the DSL have this included automatically). Within your matcher’s ‘matches?` method (or the `match` block, if using the DSL), use `values_match?(expected, actual)` rather than `expected == actual`. Under the covers, `values_match?` is able to match arbitrary nested data structures containing a mix of both matchers and non-matcher objects. It uses `===` and `==` to perform the matching, considering the values to match if either returns `true`. The `Composable` mixin also provides some helper methods for surfacing the matcher descriptions within your matcher’s description or failure messages.
RSpec’s built-in matchers each have a number of aliases that rephrase the matcher from a verb phrase (such as ‘be_within`) to a noun phrase (such as `a_value_within`), which reads better when the matcher is passed as an argument in a composed matcher expressions, and also uses the noun-phrase wording in the matcher’s ‘description`, for readable failure messages. You can alias your custom matchers in similar fashion using Matchers.alias_matcher.
## Negated Matchers
Sometimes if you want to test for the opposite using a more descriptive name instead of using ‘not_to`, you can use Matchers.define_negated_matcher:
RSpec::Matchers.define_negated_matcher :exclude, :include
include(1, 2).description # => "include 1 and 2"
exclude(1, 2).description # => "exclude 1 and 2"
While the most obvious negated form may be to add a ‘not_` prefix, the failure messages you get with that form can be confusing (e.g. “expected [actual] to not [verb], but did not”). We’ve found it works best to find a more positive name for the negated form, such as ‘avoid_changing` rather than `not_change`.
Defined Under Namespace
Modules: BuiltIn, Composable, DSL, EnglishPhrasing, FailMatchers Classes: AliasedMatcher, AliasedMatcherWithOperatorSupport, AliasedNegatedMatcher, ExpectedsForMultipleDiffs, MatcherDelegator, MatcherProtocol
Class Attribute Summary collapse
Class Method Summary collapse
-
.alias_matcher(new_name, old_name, options = {}, &description_override) ⇒ Object
Extended from DSL#alias_matcher.
-
.clear_generated_description ⇒ Object
private
Used by rspec-core to clear the state used to generate descriptions after an example.
-
.configuration ⇒ RSpec::Expectations::Configuration
Delegates to Expectations.configuration.
-
.define(name, &declarations) ⇒ Object
Extended from DSL#define.
-
.define_negated_matcher(negated_name, base_name, &description_override) ⇒ Object
Extended from DSL#define_negated_matcher.
-
.generated_description ⇒ Object
private
Generates an an example description based on the last expectation.
- .last_description ⇒ Object
Instance Method Summary collapse
-
#aggregate_failures(label = nil, metadata = {}) { ... } ⇒ Object
Allows multiple expectations in the provided block to fail, and then aggregates them into a single exception, rather than aborting on the first expectation failure like normal.
-
#all(expected) ⇒ Object
Passes if the provided matcher passes when checked against all elements of the collection.
-
#be(*args) ⇒ Object
(also: #a_value)
Given true, false, or nil, will pass if actual value is true, false or nil (respectively).
-
#be_a(klass) ⇒ Object
(also: #be_an)
passes if target.kind_of?(klass).
-
#be_a_kind_of(expected) ⇒ Object
(also: #be_kind_of, #a_kind_of)
Passes if actual.kind_of?(expected).
-
#be_an_instance_of(expected) ⇒ Object
(also: #be_instance_of, #an_instance_of)
Passes if actual.instance_of?(expected).
-
#be_between(min, max) ⇒ Object
(also: #a_value_between)
Passes if actual.between?(min, max).
-
#be_falsey ⇒ Object
(also: #be_falsy, #a_falsey_value, #a_falsy_value)
Passes if actual is falsey (false or nil).
-
#be_nil ⇒ Object
(also: #a_nil_value)
Passes if actual is nil.
-
#be_truthy ⇒ Object
(also: #a_truthy_value)
Passes if actual is truthy (anything but false or nil).
-
#be_within(delta) ⇒ Object
(also: #a_value_within, #within)
Passes if actual == expected +/- delta.
-
#change(receiver = nil, message = nil, &block) ⇒ Object
(also: #a_block_changing, #changing)
Applied to a proc, specifies that its execution will cause some value to change.
-
#contain_exactly(*items) ⇒ Object
(also: #a_collection_containing_exactly, #containing_exactly)
Passes if actual contains all of the expected regardless of order.
-
#cover(*values) ⇒ Object
(also: #a_range_covering, #covering)
Passes if actual covers expected.
-
#end_with(*expected) ⇒ Object
(also: #a_collection_ending_with, #a_string_ending_with, #ending_with)
Matches if the actual value ends with the expected value(s).
-
#eq(expected) ⇒ Object
(also: #an_object_eq_to, #eq_to)
Passes if
actual == expected
. -
#eql(expected) ⇒ Object
(also: #an_object_eql_to, #eql_to)
Passes if ‘actual.eql?(expected)`.
-
#equal(expected) ⇒ Object
(also: #an_object_equal_to, #equal_to)
Passes if
actual.equal?(expected)
(object identity). -
#exist(*args) ⇒ Object
(also: #an_object_existing, #existing)
Passes if ‘actual.exist?` or `actual.exists?`.
-
#expect ⇒ Expectations::ExpectationTarget
Supports ‘expect(actual).to matcher` syntax by wrapping `actual` in an `ExpectationTarget`.
-
#have_attributes(expected) ⇒ Object
(also: #an_object_having_attributes, #having_attributes)
Passes if actual’s attribute values match the expected attributes hash.
-
#include(*expected) ⇒ Object
(also: #a_collection_including, #a_string_including, #a_hash_including, #including)
Passes if actual includes expected.
-
#match(expected) ⇒ Object
(also: #match_regex, #an_object_matching, #a_string_matching, #matching)
Given a ‘Regexp` or `String`, passes if `actual.match(pattern)` Given an arbitrary nested data structure (e.g. arrays and hashes), matches if `expected === actual` || `actual == expected` for each pair of elements.
-
#match_array(items) ⇒ Object
(also: #an_array_matching)
An alternate form of ‘contain_exactly` that accepts the expected contents as a single array arg rather than splatted out as individual items.
-
#output(expected = nil) ⇒ Object
(also: #a_block_outputting)
With no arg, passes if the block outputs ‘to_stdout` or `to_stderr`.
-
#raise_error(error = BuiltIn::RaiseError::UndefinedValue, message = nil, &block) ⇒ Object
(also: #raise_exception, #a_block_raising, #raising)
With no args, matches if any error is raised.
-
#respond_to(*names) ⇒ Object
(also: #an_object_responding_to, #responding_to)
Matches if the target object responds to all of the names provided.
-
#respond_to?(method) ⇒ Boolean
:nocov:.
-
#satisfy(description = nil, &block) ⇒ Object
(also: #an_object_satisfying, #satisfying)
Passes if the submitted block returns true.
-
#start_with(*expected) ⇒ Object
(also: #a_collection_starting_with, #a_string_starting_with, #starting_with)
Matches if the actual value starts with the expected value(s).
-
#throw_symbol(expected_symbol = nil, expected_arg = nil) ⇒ Object
(also: #a_block_throwing, #throwing)
Given no argument, matches if a proc throws any Symbol.
-
#yield_control ⇒ Object
(also: #a_block_yielding_control, #yielding_control)
Passes if the method called in the expect block yields, regardless of whether or not arguments are yielded.
-
#yield_successive_args(*args) ⇒ Object
(also: #a_block_yielding_successive_args, #yielding_successive_args)
Designed for use with methods that repeatedly yield (such as iterators).
-
#yield_with_args(*args) ⇒ Object
(also: #a_block_yielding_with_args, #yielding_with_args)
Given no arguments, matches if the method called in the expect block yields with arguments (regardless of what they are or how many there are).
-
#yield_with_no_args ⇒ Object
(also: #a_block_yielding_with_no_args, #yielding_with_no_args)
Passes if the method called in the expect block yields with no arguments.
Methods included from DSL
alias_matcher, define, define_negated_matcher
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *args, &block) ⇒ Object (private)
961 962 963 964 965 966 967 968 969 970 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 961 def method_missing(method, *args, &block) case method.to_s when BE_PREDICATE_REGEX BuiltIn::BePredicate.new(method, *args, &block) when HAS_REGEX BuiltIn::Has.new(method, *args, &block) else super end end |
Class Attribute Details
.last_expectation_handler ⇒ Object
5 6 7 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/generated_descriptions.rb', line 5 def last_expectation_handler @last_expectation_handler end |
.last_matcher ⇒ Object
5 6 7 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/generated_descriptions.rb', line 5 def last_matcher @last_matcher end |
Class Method Details
.alias_matcher(new_name, old_name, options = {}, &description_override) ⇒ Object
Extended from RSpec::Matchers::DSL#alias_matcher.
250 251 252 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 250 def self.alias_matcher(*args, &block) super(*args, &block) end |
.clear_generated_description ⇒ Object
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.
Used by rspec-core to clear the state used to generate descriptions after an example.
11 12 13 14 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/generated_descriptions.rb', line 11 def self.clear_generated_description self.last_matcher = nil self.last_expectation_handler = nil end |
.configuration ⇒ RSpec::Expectations::Configuration
Delegates to Expectations.configuration. This is here because rspec-core’s ‘expect_with` option looks for a `configuration` method on the mixin (`RSpec::Matchers`) to yield to a block.
951 952 953 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 951 def self.configuration Expectations.configuration end |
.define(name, &declarations) ⇒ Object
Extended from RSpec::Matchers::DSL#define.
|
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 257
|
.define_negated_matcher(negated_name, base_name, &description_override) ⇒ Object
Extended from RSpec::Matchers::DSL#define_negated_matcher.
|
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 260
|
.generated_description ⇒ Object
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.
Generates an an example description based on the last expectation. Used by rspec-core’s one-liner syntax.
19 20 21 22 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/generated_descriptions.rb', line 19 def self.generated_description return nil if last_expectation_handler.nil? "#{last_expectation_handler.verb} #{last_description}" end |
.last_description ⇒ Object
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers/generated_descriptions.rb', line 25 def self.last_description last_matcher.respond_to?(:description) ? last_matcher.description : <<-MESSAGE When you call a matcher in an example without a String, like this: specify { expect(object).to matcher } or this: it { is_expected.to matcher } RSpec expects the matcher to have a #description method. You should either add a String to the example this matcher is being used in, or give it a description method. Then you won't have to suffer this lengthy warning again. MESSAGE end |
Instance Method Details
#aggregate_failures(label = nil, metadata = {}) { ... } ⇒ Object
The implementation of this feature uses a thread-local variable, which means that if you have an expectation failure in another thread, it’ll abort like normal.
Allows multiple expectations in the provided block to fail, and then aggregates them into a single exception, rather than aborting on the first expectation failure like normal. This allows you to see all failures from an entire set of expectations without splitting each off into its own example (which may slow things down if the example setup is expensive).
305 306 307 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 305 def aggregate_failures(label=nil, ={}, &block) Expectations::FailureAggregator.new(label, ).aggregate(&block) end |
#all(expected) ⇒ Object
The negative form ‘not_to all` is not supported. Instead use `not_to include` or pass a negative form of a matcher as the argument (e.g. `all exclude(:foo)`).
You can also use this with compound matchers as well.
Passes if the provided matcher passes when checked against all elements of the collection.
662 663 664 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 662 def all(expected) BuiltIn::All.new(expected) end |
#be(*args) ⇒ Object Also known as: a_value
Given true, false, or nil, will pass if actual value is true, false or nil (respectively). Given no args means the caller should satisfy an if condition (to be or not to be).
Predicates are any Ruby method that ends in a “?” and returns true or false. Given be_ followed by arbitrary_predicate (without the “?”), RSpec will match convert that into a query against the target object.
The arbitrary_predicate feature will handle any predicate prefixed with “be_an_” (e.g. be_an_instance_of), “be_a_” (e.g. be_a_kind_of) or “be_” (e.g. be_empty), letting you choose the prefix that best suits the predicate.
349 350 351 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 349 def be(*args) args.empty? ? Matchers::BuiltIn::Be.new : equal(*args) end |
#be_a(klass) ⇒ Object Also known as: be_an
passes if target.kind_of?(klass)
355 356 357 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 355 def be_a(klass) be_a_kind_of(klass) end |
#be_a_kind_of(expected) ⇒ Object Also known as: be_kind_of, a_kind_of
Passes if actual.kind_of?(expected)
378 379 380 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 378 def be_a_kind_of(expected) BuiltIn::BeAKindOf.new(expected) end |
#be_an_instance_of(expected) ⇒ Object Also known as: be_instance_of, an_instance_of
Passes if actual.instance_of?(expected)
366 367 368 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 366 def be_an_instance_of(expected) BuiltIn::BeAnInstanceOf.new(expected) end |
#be_between(min, max) ⇒ Object Also known as: a_value_between
Passes if actual.between?(min, max). Works with any Comparable object, including String, Symbol, Time, or Numeric (Fixnum, Bignum, Integer, Float, Complex, and Rational).
By default, ‘be_between` is inclusive (i.e. passes when given either the max or min value), but you can make it `exclusive` by chaining that off the matcher.
395 396 397 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 395 def be_between(min, max) BuiltIn::BeBetween.new(min, max) end |
#be_falsey ⇒ Object Also known as: be_falsy, a_falsey_value, a_falsy_value
Passes if actual is falsey (false or nil)
316 317 318 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 316 def be_falsey BuiltIn::BeFalsey.new end |
#be_nil ⇒ Object Also known as: a_nil_value
Passes if actual is nil
324 325 326 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 324 def be_nil BuiltIn::BeNil.new end |
#be_truthy ⇒ Object Also known as: a_truthy_value
Passes if actual is truthy (anything but false or nil)
310 311 312 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 310 def be_truthy BuiltIn::BeTruthy.new end |
#be_within(delta) ⇒ Object Also known as: a_value_within, within
Passes if actual == expected +/- delta
405 406 407 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 405 def be_within(delta) BuiltIn::BeWithin.new(delta) end |
#change(receiver = nil, message = nil, &block) ⇒ Object Also known as: a_block_changing, changing
Applied to a proc, specifies that its execution will cause some value to change.
You can either pass receiver
and message
, or a block, but not both.
When passing a block, it must use the ‘{ … }` format, not do/end, as `{ … }` binds to the `change` method, whereas do/end would errantly bind to the `expect(..).to` or `expect(…).not_to` method.
You can chain any of the following off of the end to specify details about the change:
-
‘from`
-
‘to`
or any one of:
-
‘by`
-
‘by_at_least`
-
‘by_at_most`
Notes
Evaluates ‘receiver.message` or `block` before and after it evaluates the block passed to `expect`. If the value is the same object, its before/after `hash` value is used to see if it has changed. Therefore, your object needs to properly implement `hash` to work correctly with this matcher.
‘expect( … ).not_to change` supports the form that specifies `from` (which specifies what you expect the starting, unchanged value to be) but does not support forms with subsequent calls to `by`, `by_at_least`, `by_at_most` or `to`.
492 493 494 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 492 def change(receiver=nil, =nil, &block) BuiltIn::Change.new(receiver, , &block) end |
#contain_exactly(*items) ⇒ Object Also known as: a_collection_containing_exactly, containing_exactly
This is also available using the ‘=~` operator with `should`, but `=~` is not supported with `expect`.
Passes if actual contains all of the expected regardless of order. This works for collections. Pass in multiple args and it will only pass if all args are found in collection.
510 511 512 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 510 def contain_exactly(*items) BuiltIn::ContainExactly.new(items) end |
#cover(*values) ⇒ Object Also known as: a_range_covering, covering
Passes if actual covers expected. This works for Ranges. You can also pass in multiple args and it will only pass if all args are found in Range.
- ### Warning
-
Ruby >= 1.9 only
528 529 530 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 528 def cover(*values) BuiltIn::Cover.new(*values) end |
#end_with(*expected) ⇒ Object Also known as: a_collection_ending_with, a_string_ending_with, ending_with
Matches if the actual value ends with the expected value(s). In the case of a string, matches against the last ‘expected.length` characters of the actual string. In the case of an array, matches against the last `expected.length` elements of the actual array.
543 544 545 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 543 def end_with(*expected) BuiltIn::EndWith.new(*expected) end |
#eq(expected) ⇒ Object Also known as: an_object_eq_to, eq_to
Passes if actual == expected
.
See www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
558 559 560 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 558 def eq(expected) BuiltIn::Eq.new(expected) end |
#eql(expected) ⇒ Object Also known as: an_object_eql_to, eql_to
Passes if ‘actual.eql?(expected)`
See www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
572 573 574 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 572 def eql(expected) BuiltIn::Eql.new(expected) end |
#equal(expected) ⇒ Object Also known as: an_object_equal_to, equal_to
Passes if actual.equal?(expected)
(object identity).
See www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
586 587 588 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 586 def equal(expected) BuiltIn::Equal.new(expected) end |
#exist(*args) ⇒ Object Also known as: an_object_existing, existing
Passes if ‘actual.exist?` or `actual.exists?`
596 597 598 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 596 def exist(*args) BuiltIn::Exist.new(*args) end |
#expect ⇒ Expectations::ExpectationTarget
Supports ‘expect(actual).to matcher` syntax by wrapping `actual` in an `ExpectationTarget`.
|
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 263
|
#have_attributes(expected) ⇒ Object Also known as: an_object_having_attributes, having_attributes
It will fail if actual doesn’t respond to any of the expected attributes.
Passes if actual’s attribute values match the expected attributes hash. This works no matter how you define your attribute readers.
616 617 618 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 616 def have_attributes(expected) BuiltIn::HaveAttributes.new(expected) end |
#include(*expected) ⇒ Object Also known as: a_collection_including, a_string_including, a_hash_including, including
Passes if actual includes expected. This works for collections and Strings. You can also pass in multiple args and it will only pass if all args are found in collection.
639 640 641 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 639 def include(*expected) BuiltIn::Include.new(*expected) end |
#match(expected) ⇒ Object Also known as: match_regex, an_object_matching, a_string_matching, matching
The ‘match_regex` alias is deprecated and is not recommended for use. It was added in 2.12.1 to facilitate its use from within custom matchers (due to how the custom matcher DSL was evaluated in 2.x, `match` could not be used there), but is no longer needed in 3.x.
Given a ‘Regexp` or `String`, passes if `actual.match(pattern)` Given an arbitrary nested data structure (e.g. arrays and hashes), matches if `expected === actual` || `actual == expected` for each pair of elements.
697 698 699 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 697 def match(expected) BuiltIn::Match.new(expected) end |
#match_array(items) ⇒ Object Also known as: an_array_matching
An alternate form of ‘contain_exactly` that accepts the expected contents as a single array arg rather than splatted out as individual items.
715 716 717 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 715 def match_array(items) contain_exactly(*items) end |
#output(expected = nil) ⇒ Object Also known as: a_block_outputting
‘to_stdout` and `to_stderr` work by temporarily replacing `$stdout` or `$stderr`, so they’re not able to intercept stream output that explicitly uses ‘STDOUT`/`STDERR` or that uses a reference to `$stdout`/`$stderr` that was stored before the matcher was used.
‘to_stdout_from_any_process` and `to_stderr_from_any_process` use Tempfiles, and are thus significantly (~30x) slower than `to_stdout` and `to_stderr`.
With no arg, passes if the block outputs ‘to_stdout` or `to_stderr`. With a string, passes if the block outputs that specific string `to_stdout` or `to_stderr`. With a regexp or matcher, passes if the block outputs a string `to_stdout` or `to_stderr` that matches.
To capture output from any spawned subprocess as well, use ‘to_stdout_from_any_process` or `to_stderr_from_any_process`. Output from any process that inherits the main process’s corresponding standard stream will be captured.
752 753 754 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 752 def output(expected=nil) BuiltIn::Output.new(expected) end |
#raise_error(error = BuiltIn::RaiseError::UndefinedValue, message = nil, &block) ⇒ Object Also known as: raise_exception, a_block_raising, raising
With no args, matches if any error is raised. With a named error, matches only if that specific error is raised. With a named error and message specified as a String, matches only if both match. With a named error and message specified as a Regexp, matches only if both match. Pass an optional block to perform extra verifications on the exception matched
773 774 775 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 773 def raise_error(error=BuiltIn::RaiseError::UndefinedValue, =nil, &block) BuiltIn::RaiseError.new(error, , &block) end |
#respond_to(*names) ⇒ Object Also known as: an_object_responding_to, responding_to
Matches if the target object responds to all of the names provided. Names can be Strings or Symbols.
792 793 794 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 792 def respond_to(*names) BuiltIn::RespondTo.new(*names) end |
#respond_to?(method) ⇒ Boolean
:nocov:
979 980 981 982 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 979 def respond_to?(method, *) method = method.to_s method =~ DYNAMIC_MATCHER_REGEX || super end |
#satisfy(description = nil, &block) ⇒ Object Also known as: an_object_satisfying, satisfying
Passes if the submitted block returns true. Yields target to the block.
Generally speaking, this should be thought of as a last resort when you can’t find any other way to specify the behaviour you wish to specify.
If you do find yourself in such a situation, you could always write a custom matcher, which would likely make your specs more expressive.
813 814 815 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 813 def satisfy(description=nil, &block) BuiltIn::Satisfy.new(description, &block) end |
#start_with(*expected) ⇒ Object Also known as: a_collection_starting_with, a_string_starting_with, starting_with
Matches if the actual value starts with the expected value(s). In the case of a string, matches against the first ‘expected.length` characters of the actual string. In the case of an array, matches against the first `expected.length` elements of the actual array.
828 829 830 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 828 def start_with(*expected) BuiltIn::StartWith.new(*expected) end |
#throw_symbol(expected_symbol = nil, expected_arg = nil) ⇒ Object Also known as: a_block_throwing, throwing
Given no argument, matches if a proc throws any Symbol.
Given a Symbol, matches if the given proc throws the specified Symbol.
Given a Symbol and an arg, matches if the given proc throws the specified Symbol with the specified arg.
850 851 852 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 850 def throw_symbol(expected_symbol=nil, expected_arg=nil) BuiltIn::ThrowSymbol.new(expected_symbol, expected_arg) end |
#yield_control ⇒ Object Also known as: a_block_yielding_control, yielding_control
Your expect block must accept a parameter and pass it on to the method-under-test as a block.
Passes if the method called in the expect block yields, regardless of whether or not arguments are yielded.
871 872 873 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 871 def yield_control BuiltIn::YieldControl.new end |
#yield_successive_args(*args) ⇒ Object Also known as: a_block_yielding_successive_args, yielding_successive_args
Your expect block must accept a parameter and pass it on to the method-under-test as a block.
Designed for use with methods that repeatedly yield (such as iterators). Passes if the method called in the expect block yields multiple times with arguments matching those given.
Argument matching is done using ‘===` (the case match operator) and `==`. If the expected and actual arguments match with either operator, the matcher will pass.
940 941 942 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 940 def yield_successive_args(*args) BuiltIn::YieldSuccessiveArgs.new(*args) end |
#yield_with_args(*args) ⇒ Object Also known as: a_block_yielding_with_args, yielding_with_args
Your expect block must accept a parameter and pass it on to the method-under-test as a block.
This matcher is not designed for use with methods that yield multiple times.
Given no arguments, matches if the method called in the expect block yields with arguments (regardless of what they are or how many there are).
Given arguments, matches if the method called in the expect block yields with arguments that match the given arguments.
Argument matching is done using ‘===` (the case match operator) and `==`. If the expected and actual arguments match with either operator, the matcher will pass.
919 920 921 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 919 def yield_with_args(*args) BuiltIn::YieldWithArgs.new(*args) end |
#yield_with_no_args ⇒ Object Also known as: a_block_yielding_with_no_args, yielding_with_no_args
Your expect block must accept a parameter and pass it on to the method-under-test as a block.
This matcher is not designed for use with methods that yield multiple times.
Passes if the method called in the expect block yields with no arguments. Fails if it does not yield, or yields with arguments.
889 890 891 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-expectations-3.12.2/lib/rspec/matchers.rb', line 889 def yield_with_no_args BuiltIn::YieldWithNoArgs.new end |