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
|
module RSpec
module Mocks
# Provides recursive constant lookup methods useful for
# constant stubbing.
# @api private
module RecursiveConstMethods
# We only want to consider constants that are defined directly on a
# particular module, and not include top-level/inherited constants.
# Unfortunately, the constant API changed between 1.8 and 1.9, so
# we need to conditionally define methods to ignore the top-level/inherited
# constants.
#
# Given:
# class A; B = 1; end
# class C < A; end
#
# On 1.8:
# - C.const_get("Hash") # => ::Hash
# - C.const_defined?("Hash") # => false
# - C.constants # => ["B"]
# - None of these methods accept the extra `inherit` argument
# On 1.9:
# - C.const_get("Hash") # => ::Hash
# - C.const_defined?("Hash") # => true
# - C.const_get("Hash", false) # => raises NameError
# - C.const_defined?("Hash", false) # => false
# - C.constants # => [:B]
# - C.constants(false) #=> []
if Module.method(:const_defined?).arity == 1
def const_defined_on?(mod, const_name)
mod.const_defined?(const_name)
end
def get_const_defined_on(mod, const_name)
if const_defined_on?(mod, const_name)
return mod.const_get(const_name)
end
raise NameError, "uninitialized constant #{mod.name}::#{const_name}"
end
def constants_defined_on(mod)
mod.constants.select { |c| const_defined_on?(mod, c) }
end
else
def const_defined_on?(mod, const_name)
mod.const_defined?(const_name, false)
end
def get_const_defined_on(mod, const_name)
mod.const_get(const_name, false)
end
def constants_defined_on(mod)
mod.constants(false)
end
end
def recursive_const_get(const_name)
normalize_const_name(const_name).split('::').inject(Object) do |mod, name|
get_const_defined_on(mod, name)
end
end
def recursive_const_defined?(const_name)
normalize_const_name(const_name).split('::').inject([Object, '']) do |(mod, full_name), name|
yield(full_name, name) if block_given? && !mod.is_a?(Module)
return false unless const_defined_on?(mod, name)
[get_const_defined_on(mod, name), [mod, name].join('::')]
end
end
def normalize_const_name(const_name)
const_name.sub(/\A::/, '')
end
end
# Provides information about constants that may (or may not)
# have been mutated by rspec-mocks.
class Constant
extend RecursiveConstMethods
# @api private
def initialize(name)
@name = name
@previously_defined = false
@stubbed = false
@hidden = false
end
# @return [String] The fully qualified name of the constant.
attr_reader :name
# @return [Object, nil] The original value (e.g. before it
# was mutated by rspec-mocks) of the constant, or
# nil if the constant was not previously defined.
attr_accessor :original_value
# @api private
attr_writer :previously_defined, :stubbed, :hidden
# @return [Boolean] Whether or not the constant was defined
# before the current example.
def previously_defined?
@previously_defined
end
# @return [Boolean] Whether or not rspec-mocks has mutated
# (stubbed or hidden) this constant.
def mutated?
@stubbed || @hidden
end
# @return [Boolean] Whether or not rspec-mocks has stubbed
# this constant.
def stubbed?
@stubbed
end
# @return [Boolean] Whether or not rspec-mocks has hidden
# this constant.
def hidden?
@hidden
end
def to_s
"#<#{self.class.name} #{name}>"
end
alias inspect to_s
# @api private
def self.unmutated(name)
const = new(name)
const.previously_defined = recursive_const_defined?(name)
const.stubbed = false
const.hidden = false
const.original_value = recursive_const_get(name) if const.previously_defined?
const
end
private_class_method :unmutated
# Queries rspec-mocks to find out information about the named constant.
#
# @param [String] name the name of the constant
# @return [Constant] an object contaning information about the named
# constant.
def self.original(name)
mutator = ConstantMutator.find(name)
mutator ? mutator.to_constant : unmutated(name)
end
end
# Provides a means to stub constants.
class ConstantMutator
extend RecursiveConstMethods
# Stubs a constant.
#
# @param (see ExampleMethods#stub_const)
# @option (see ExampleMethods#stub_const)
# @return (see ExampleMethods#stub_const)
#
# @see ExampleMethods#stub_const
# @note It's recommended that you use `stub_const` in your
# examples. This is an alternate public API that is provided
# so you can stub constants in other contexts (e.g. helper
# classes).
def self.stub(constant_name, value, options = {})
mutator = if recursive_const_defined?(constant_name, &raise_on_invalid_const)
DefinedConstantReplacer
else
UndefinedConstantSetter
end
mutate(mutator.new(constant_name, value, options[:transfer_nested_constants]))
value
end
# Hides a constant.
#
# @param (see ExampleMethods#hide_const)
#
# @see ExampleMethods#hide_const
# @note It's recommended that you use `hide_const` in your
# examples. This is an alternate public API that is provided
# so you can hide constants in other contexts (e.g. helper
# classes).
def self.hide(constant_name)
return unless recursive_const_defined?(constant_name)
mutate(ConstantHider.new(constant_name, nil, { }))
nil
end
# Contains common functionality used by all of the constant mutators.
#
# @api private
class BaseMutator
include RecursiveConstMethods
attr_reader :original_value, :full_constant_name
def initialize(full_constant_name, mutated_value, transfer_nested_constants)
@full_constant_name = normalize_const_name(full_constant_name)
@mutated_value = mutated_value
@transfer_nested_constants = transfer_nested_constants
@context_parts = @full_constant_name.split('::')
@const_name = @context_parts.pop
end
def to_constant
const = Constant.new(full_constant_name)
const.original_value = original_value
const
end
end
# Hides a defined constant for the duration of an example.
#
# @api private
class ConstantHider < BaseMutator
def mutate
@context = recursive_const_get(@context_parts.join('::'))
@original_value = get_const_defined_on(@context, @const_name)
@context.__send__(:remove_const, @const_name)
end
def to_constant
const = super
const.hidden = true
const.previously_defined = true
const
end
def rspec_reset
@context.const_set(@const_name, @original_value)
end
end
# Replaces a defined constant for the duration of an example.
#
# @api private
class DefinedConstantReplacer < BaseMutator
def mutate
@context = recursive_const_get(@context_parts.join('::'))
@original_value = get_const_defined_on(@context, @const_name)
constants_to_transfer = verify_constants_to_transfer!
@context.__send__(:remove_const, @const_name)
@context.const_set(@const_name, @mutated_value)
transfer_nested_constants(constants_to_transfer)
end
def to_constant
const = super
const.stubbed = true
const.previously_defined = true
const
end
def rspec_reset
@context.__send__(:remove_const, @const_name)
@context.const_set(@const_name, @original_value)
end
def transfer_nested_constants(constants)
constants.each do |const|
@mutated_value.const_set(const, get_const_defined_on(original_value, const))
end
end
def verify_constants_to_transfer!
return [] unless @transfer_nested_constants
{ @original_value => "the original value", @mutated_value => "the stubbed value" }.each do |value, description|
unless value.respond_to?(:constants)
raise ArgumentError,
"Cannot transfer nested constants for #{@full_constant_name} " +
"since #{description} is not a class or module and only classes " +
"and modules support nested constants."
end
end
if @transfer_nested_constants.is_a?(Array)
@transfer_nested_constants = @transfer_nested_constants.map(&:to_s) if RUBY_VERSION == '1.8.7'
undefined_constants = @transfer_nested_constants - constants_defined_on(@original_value)
if undefined_constants.any?
available_constants = constants_defined_on(@original_value) - @transfer_nested_constants
raise ArgumentError,
"Cannot transfer nested constant(s) #{undefined_constants.join(' and ')} " +
"for #{@full_constant_name} since they are not defined. Did you mean " +
"#{available_constants.join(' or ')}?"
end
@transfer_nested_constants
else
constants_defined_on(@original_value)
end
end
end
# Sets an undefined constant for the duration of an example.
#
# @api private
class UndefinedConstantSetter < BaseMutator
def mutate
remaining_parts = @context_parts.dup
@deepest_defined_const = @context_parts.inject(Object) do |klass, name|
break klass unless const_defined_on?(klass, name)
remaining_parts.shift
get_const_defined_on(klass, name)
end
context = remaining_parts.inject(@deepest_defined_const) do |klass, name|
klass.const_set(name, Module.new)
end
@const_to_remove = remaining_parts.first || @const_name
context.const_set(@const_name, @mutated_value)
end
def to_constant
const = super
const.stubbed = true
const.previously_defined = false
const
end
def rspec_reset
@deepest_defined_const.__send__(:remove_const, @const_to_remove)
end
end
# Uses the mutator to mutate (stub or hide) a constant. Ensures that
# the mutator is correctly registered so it can be backed out at the end
# of the test.
#
# @api private
def self.mutate(mutator)
register_mutator(mutator)
mutator.mutate
end
# Resets all stubbed constants. This is called automatically
# by rspec-mocks when an example finishes.
#
# @api private
def self.reset_all
# We use reverse order so that if the same constant
# was stubbed multiple times, the original value gets
# properly restored.
mutators.reverse.each { |s| s.rspec_reset }
mutators.clear
end
# The list of constant mutators that have been used for
# the current example.
#
# @api private
def self.mutators
@mutators ||= []
end
# @api private
def self.register_mutator(mutator)
mutators << mutator
end
def self.find(name)
mutators.find { |s| s.full_constant_name == name }
end
# Used internally by the constant stubbing to raise a helpful
# error when a constant like "A::B::C" is stubbed and A::B is
# not a module (and thus, it's impossible to define "A::B::C"
# since only modules can have nested constants).
#
# @api private
def self.raise_on_invalid_const
lambda do |const_name, failed_name|
raise "Cannot stub constant #{failed_name} on #{const_name} " +
"since #{const_name} is not a module."
end
end
end
# Keeps backwards compatibility since we had released an rspec-mocks that
# only supported stubbing. Later, we released the hide_const feature and
# decided that the term "mutator" was a better term to wrap up the concept
# of both stubbing and hiding.
ConstantStubber = ConstantMutator
end
end
|