/usr/lib/ruby/vendor_ruby/rspec/matchers/dsl.rb is in ruby-rspec-expectations 3.4.0c3e0m1s1-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 | module RSpec
module Matchers
# Defines the custom matcher DSL.
module DSL
# Defines a custom matcher.
# @see RSpec::Matchers
def define(name, &declarations)
warn_about_block_args(name, declarations)
define_method name do |*expected, &block_arg|
RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected, &block_arg)
end
end
alias_method :matcher, :define
private
if Proc.method_defined?(:parameters)
def warn_about_block_args(name, declarations)
declarations.parameters.each do |type, arg_name|
next unless type == :block
RSpec.warning("Your `#{name}` custom matcher receives a block argument (`#{arg_name}`), " \
"but due to limitations in ruby, RSpec cannot provide the block. Instead, " \
"use the `block_arg` method to access the block")
end
end
else
# :nocov:
def warn_about_block_args(*)
# There's no way to detect block params on 1.8 since the method reflection APIs don't expose it
end
# :nocov:
end
RSpec.configure { |c| c.extend self } if RSpec.respond_to?(:configure)
# Contains the methods that are available from within the
# `RSpec::Matchers.define` DSL for creating custom matchers.
module Macros
# Stores the block that is used to determine whether this matcher passes
# or fails. The block should return a boolean value. When the matcher is
# passed to `expect(...).to` and the block returns `true`, then the expectation
# passes. Similarly, when the matcher is passed to `expect(...).not_to` and the
# block returns `false`, then the expectation passes.
#
# @example
#
# RSpec::Matchers.define :be_even do
# match do |actual|
# actual.even?
# end
# end
#
# expect(4).to be_even # passes
# expect(3).not_to be_even # passes
# expect(3).to be_even # fails
# expect(4).not_to be_even # fails
#
# @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
def match(&match_block)
define_user_override(:matches?, match_block) do |actual|
begin
@actual = actual
RSpec::Support.with_failure_notifier(RAISE_NOTIFIER) do
super(*actual_arg_for(match_block))
end
rescue RSpec::Expectations::ExpectationNotMetError
false
end
end
end
# @private
RAISE_NOTIFIER = Proc.new { |err, _opts| raise err }
# Use this to define the block for a negative expectation (`expect(...).not_to`)
# when the positive and negative forms require different handling. This
# is rarely necessary, but can be helpful, for example, when specifying
# asynchronous processes that require different timeouts.
#
# @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
def match_when_negated(&match_block)
define_user_override(:does_not_match?, match_block) do |actual|
@actual = actual
super(*actual_arg_for(match_block))
end
end
# Use this instead of `match` when the block will raise an exception
# rather than returning false to indicate a failure.
#
# @example
#
# RSpec::Matchers.define :accept_as_valid do |candidate_address|
# match_unless_raises ValidationException do |validator|
# validator.validate(candidate_address)
# end
# end
#
# expect(email_validator).to accept_as_valid("person@company.com")
#
# @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
def match_unless_raises(expected_exception=Exception, &match_block)
define_user_override(:matches?, match_block) do |actual|
@actual = actual
begin
super(*actual_arg_for(match_block))
rescue expected_exception => @rescued_exception
false
else
true
end
end
end
# Customizes the failure messsage to use when this matcher is
# asked to positively match. Only use this when the message
# generated by default doesn't suit your needs.
#
# @example
#
# RSpec::Matchers.define :have_strength do |expected|
# match { your_match_logic }
#
# failure_message do |actual|
# "Expected strength of #{expected}, but had #{actual.strength}"
# end
# end
#
# @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
def failure_message(&definition)
define_user_override(__method__, definition)
end
# Customize the failure messsage to use when this matcher is asked
# to negatively match. Only use this when the message generated by
# default doesn't suit your needs.
#
# @example
#
# RSpec::Matchers.define :have_strength do |expected|
# match { your_match_logic }
#
# failure_message_when_negated do |actual|
# "Expected not to have strength of #{expected}, but did"
# end
# end
#
# @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
def failure_message_when_negated(&definition)
define_user_override(__method__, definition)
end
# Customize the description to use for one-liners. Only use this when
# the description generated by default doesn't suit your needs.
#
# @example
#
# RSpec::Matchers.define :qualify_for do |expected|
# match { your_match_logic }
#
# description do
# "qualify for #{expected}"
# end
# end
#
# @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
def description(&definition)
define_user_override(__method__, definition)
end
# Tells the matcher to diff the actual and expected values in the failure
# message.
def diffable
define_method(:diffable?) { true }
end
# Declares that the matcher can be used in a block expectation.
# Users will not be able to use your matcher in a block
# expectation without declaring this.
# (e.g. `expect { do_something }.to matcher`).
def supports_block_expectations
define_method(:supports_block_expectations?) { true }
end
# Convenience for defining methods on this matcher to create a fluent
# interface. The trick about fluent interfaces is that each method must
# return self in order to chain methods together. `chain` handles that
# for you. If the method is invoked and the
# `include_chain_clauses_in_custom_matcher_descriptions` config option
# hash been enabled, the chained method name and args will be added to the
# default description and failure message.
#
# In the common case where you just want the chained method to store some
# value(s) for later use (e.g. in `match`), you can provide one or more
# attribute names instead of a block; the chained method will store its
# arguments in instance variables with those names, and the values will
# be exposed via getters.
#
# @example
#
# RSpec::Matchers.define :have_errors_on do |key|
# chain :with do |message|
# @message = message
# end
#
# match do |actual|
# actual.errors[key] == @message
# end
# end
#
# expect(minor).to have_errors_on(:age).with("Not old enough to participate")
def chain(method_name, *attr_names, &definition)
unless block_given? ^ attr_names.any?
raise ArgumentError, "You must pass either a block or some attribute names (but not both) to `chain`."
end
definition = assign_attributes(attr_names) if attr_names.any?
define_user_override(method_name, definition) do |*args, &block|
super(*args, &block)
@chained_method_clauses.push([method_name, args])
self
end
end
def assign_attributes(attr_names)
attr_reader(*attr_names)
private(*attr_names)
lambda do |*attr_values|
attr_names.zip(attr_values) do |attr_name, attr_value|
instance_variable_set(:"@#{attr_name}", attr_value)
end
end
end
# assign_attributes isn't defined in the private section below because
# that makes MRI 1.9.2 emit a warning about private attributes.
private :assign_attributes
private
# Does the following:
#
# - Defines the named method using a user-provided block
# in @user_method_defs, which is included as an ancestor
# in the singleton class in which we eval the `define` block.
# - Defines an overriden definition for the same method
# usign the provided `our_def` block.
# - Provides a default `our_def` block for the common case
# of needing to call the user's definition with `@actual`
# as an arg, but only if their block's arity can handle it.
#
# This compiles the user block into an actual method, allowing
# them to use normal method constructs like `return`
# (e.g. for a early guard statement), while allowing us to define
# an override that can provide the wrapped handling
# (e.g. assigning `@actual`, rescueing errors, etc) and
# can `super` to the user's definition.
def define_user_override(method_name, user_def, &our_def)
@user_method_defs.__send__(:define_method, method_name, &user_def)
our_def ||= lambda { super(*actual_arg_for(user_def)) }
define_method(method_name, &our_def)
end
# Defines deprecated macro methods from RSpec 2 for backwards compatibility.
# @deprecated Use the methods from {Macros} instead.
module Deprecated
# @deprecated Use {Macros#match} instead.
def match_for_should(&definition)
RSpec.deprecate("`match_for_should`", :replacement => "`match`")
match(&definition)
end
# @deprecated Use {Macros#match_when_negated} instead.
def match_for_should_not(&definition)
RSpec.deprecate("`match_for_should_not`", :replacement => "`match_when_negated`")
match_when_negated(&definition)
end
# @deprecated Use {Macros#failure_message} instead.
def failure_message_for_should(&definition)
RSpec.deprecate("`failure_message_for_should`", :replacement => "`failure_message`")
failure_message(&definition)
end
# @deprecated Use {Macros#failure_message_when_negated} instead.
def failure_message_for_should_not(&definition)
RSpec.deprecate("`failure_message_for_should_not`", :replacement => "`failure_message_when_negated`")
failure_message_when_negated(&definition)
end
end
end
# Defines default implementations of the matcher
# protocol methods for custom matchers. You can
# override any of these using the {RSpec::Matchers::DSL::Macros Macros} methods
# from within an `RSpec::Matchers.define` block.
module DefaultImplementations
include BuiltIn::BaseMatcher::DefaultFailureMessages
# @api private
# Used internally by objects returns by `should` and `should_not`.
def diffable?
false
end
# The default description.
def description
english_name = EnglishPhrasing.split_words(name)
expected_list = EnglishPhrasing.list(expected)
"#{english_name}#{expected_list}#{chained_method_clause_sentences}"
end
# Matchers do not support block expectations by default. You
# must opt-in.
def supports_block_expectations?
false
end
# Most matchers do not expect call stack jumps.
def expects_call_stack_jump?
false
end
private
def chained_method_clause_sentences
return '' unless Expectations.configuration.include_chain_clauses_in_custom_matcher_descriptions?
@chained_method_clauses.map do |(method_name, method_args)|
english_name = EnglishPhrasing.split_words(method_name)
arg_list = EnglishPhrasing.list(method_args)
" #{english_name}#{arg_list}"
end.join
end
end
# The class used for custom matchers. The block passed to
# `RSpec::Matchers.define` will be evaluated in the context
# of the singleton class of an instance, and will have the
# {RSpec::Matchers::DSL::Macros Macros} methods available.
class Matcher
# Provides default implementations for the matcher protocol methods.
include DefaultImplementations
# Allows expectation expressions to be used in the match block.
include RSpec::Matchers
# Supports the matcher composability features of RSpec 3+.
include Composable
# Makes the macro methods available to an `RSpec::Matchers.define` block.
extend Macros
extend Macros::Deprecated
# Exposes the value being matched against -- generally the object
# object wrapped by `expect`.
attr_reader :actual
# Exposes the exception raised during the matching by `match_unless_raises`.
# Could be useful to extract details for a failure message.
attr_reader :rescued_exception
# The block parameter used in the expectation
attr_reader :block_arg
# The name of the matcher.
attr_reader :name
# @api private
def initialize(name, declarations, matcher_execution_context, *expected, &block_arg)
@name = name
@actual = nil
@expected_as_array = expected
@matcher_execution_context = matcher_execution_context
@chained_method_clauses = []
@block_arg = block_arg
class << self
# See `Macros#define_user_override` above, for an explanation.
include(@user_method_defs = Module.new)
self
end.class_exec(*expected, &declarations)
end
# Provides the expected value. This will return an array if
# multiple arguments were passed to the matcher; otherwise it
# will return a single value.
# @see #expected_as_array
def expected
if expected_as_array.size == 1
expected_as_array[0]
else
expected_as_array
end
end
# Returns the expected value as an an array. This exists primarily
# to aid in upgrading from RSpec 2.x, since in RSpec 2, `expected`
# always returned an array.
# @see #expected
attr_reader :expected_as_array
# Adds the name (rather than a cryptic hex number)
# so we can identify an instance of
# the matcher in error messages (e.g. for `NoMethodError`)
def inspect
"#<#{self.class.name} #{name}>"
end
if RUBY_VERSION.to_f >= 1.9
# Indicates that this matcher responds to messages
# from the `@matcher_execution_context` as well.
# Also, supports getting a method object for such methods.
def respond_to_missing?(method, include_private=false)
super || @matcher_execution_context.respond_to?(method, include_private)
end
else # for 1.8.7
# :nocov:
# Indicates that this matcher responds to messages
# from the `@matcher_execution_context` as well.
def respond_to?(method, include_private=false)
super || @matcher_execution_context.respond_to?(method, include_private)
end
# :nocov:
end
private
def actual_arg_for(block)
block.arity.zero? ? [] : [@actual]
end
# Takes care of forwarding unhandled messages to the
# `@matcher_execution_context` (typically the current
# running `RSpec::Core::Example`). This is needed by
# rspec-rails so that it can define matchers that wrap
# Rails' test helper methods, but it's also a useful
# feature in its own right.
def method_missing(method, *args, &block)
if @matcher_execution_context.respond_to?(method)
@matcher_execution_context.__send__ method, *args, &block
else
super(method, *args, &block)
end
end
end
end
end
end
RSpec::Matchers.extend RSpec::Matchers::DSL
|