Class: Grift::MockMethod

Inherits:
Object
  • Object
show all
Defined in:
lib/grift/mock_method.rb,
lib/grift/mock_method/mock_executions.rb,
lib/grift/mock_method/mock_executions/mock_arguments.rb

Overview

A mock for a given class and method. This is the core of Grift. Mocking or spying usually returns a MockMethod.

Defined Under Namespace

Classes: MockExecutions

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(klass, method_name, watch: true, instance: false) ⇒ Grift::MockMethod

A new instance of MockMethod. Should be initialized via Grift.mock or Grift.spy_on

Examples:

Grift.spy_on(MyClass, :my_method)
#=> MockMethod instance with the method being watched

Parameters:

  • klass (Class) —

    the class to be mocked

  • method_name (Symbol) —

    the method to be mocked

  • watch (Boolean) (defaults to: true) —

    whether to start watching the method

  • instance (Boolean) (defaults to: false) —

    whether to mock the instance method even if the class responds to the method itself

Raises:

See Also:



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/grift/mock_method.rb', line 47

def initialize(klass, method_name, watch: true, instance: false)
  if Grift.restricted_method?(klass, method_name)
    raise(Grift::Error, "Cannot mock restricted method #{method_name} for class #{klass}")
  end

  @klass = klass
  @method_name = method_name
  @true_method_cached = false
  @mock_executions = MockExecutions.new
  @cache_method_name = :"#{CACHE_METHOD_PREFIX}_#{method_name}"

  # class methods are really instance methods of the singleton class
  @class_method = !instance && defined_on?(klass.singleton_class, method_name)

  @method_access, @inherited = method_access_definition
  raise(Grift::Error, "Cannot mock unknown method #{method_name} for class #{klass}") unless @method_access
  raise(Grift::Error, "Cannot mock already mocked method #{method_name} for class #{klass}") if already_mocked?

  watch_method if watch
end

Instance Attribute Details

#klass ⇒ Object (readonly)

Returns the value of attribute klass.



9
10
11
 
# File 'lib/grift/mock_method.rb', line 9

def klass
  @klass
end

#method_access ⇒ Object (readonly)

Returns the value of attribute method_access.



9
10
11
 
# File 'lib/grift/mock_method.rb', line 9

def method_access
  @method_access
end

#method_name ⇒ Object (readonly)

Returns the value of attribute method_name.



9
10
11
 
# File 'lib/grift/mock_method.rb', line 9

def method_name
  @method_name
end

#true_method_cached ⇒ Object (readonly)

Returns the value of attribute true_method_cached.



9
10
11
 
# File 'lib/grift/mock_method.rb', line 9

def true_method_cached
  @true_method_cached
end

Class Method Details

.hash_key(klass, method_name) ⇒ String

Hashes the class and method for tracking mocks.

Examples:

Grift::MockMethod.hash_key(String, :upcase)
#=> 'String#upcase'

Parameters:

  • klass (Class)
  • method_name (Symbol)

Returns:

  • (String) —

    the hash of the class and method



26
27
28
 
# File 'lib/grift/mock_method.rb', line 26

def self.hash_key(klass, method_name)
  "#{klass}##{method_name}"
end

Instance Method Details

#calls ⇒ Array<Grift::MockMethod::MockExecutions::MockArguments>

Returns an array of the args used in each call to the mocked method This is syntactical sugar equivalent to calling mock and then calls.

Examples:

my_mock = Grift.spy_on(Number, :+)
x = (3 + 4) + 5
my_mock.calls.map(&:values)
#=> [[4], [5]]

Returns:

See Also:



469
470
471
 
# File 'lib/grift/mock_method.rb', line 469

def calls
  @mock_executions.calls
end

#count ⇒ Number

Returns the count of mock executions. This is syntactical sugar equivalent to calling mock and then count.

Examples:

my_mock = Grift.mock(String, :upcase)
my_mock.mock.count
#=> 0
"apple".upcase
#=> "APPLE"
my_mock.count
#=> 1

Returns:

  • (Number) —

    the number of executions

See Also:



511
512
513
 
# File 'lib/grift/mock_method.rb', line 511

def count
  @mock_executions.count
end

#empty? ⇒ Boolean

Returns true if there have been no calls to the mock. This is syntactical sugar equivalent to calling mock and then empty?.

Examples:

my_mock = Grift.mock(String, :upcase)
my_mock.mock.empty?
#=> true
"apple".upcase
#=> "APPLE"
my_mock.empty?
#=> false

Returns:

  • (Boolean) —

    if the executions are empty

See Also:



490
491
492
 
# File 'lib/grift/mock_method.rb', line 490

def empty?
  @mock_executions.empty?
end

#mock ⇒ Grift::MockMethod::MockExecutions

Gets the data for the mock results and calls for this mock.

Examples:

my_mock = Grift.spy_on(String, :upcase)
"banana".upcase
#=> 'BANANA'
my_mock.mock.calls
#=> [[]]
my_mock.mock.results
#=> [['BANANA']]

Returns:

See Also:



85
86
87
 
# File 'lib/grift/mock_method.rb', line 85

def mock
  @mock_executions
end

#mock_clear ⇒ Grift::MockMethod::MockExecutions

Clears the mock execution and calls data for this mock, but keep the method mocked as before.

Returns:



95
96
97
 
# File 'lib/grift/mock_method.rb', line 95

def mock_clear
  @mock_executions = MockExecutions.new
end

#mock_implementation ⇒ self

Accepts a block and mocks the method to execute that block instead of the original behavior whenever called while mocked.

Examples:

my_mock = Grift.spy_on(String, :downcase).mock_implementation do
    x = 3 + 4
    x.to_s
end
"Banana".downcase
#=> '7'
my_mock = Grift.spy_on(MyClass, :my_method).mock_implementation do |first, second, **kwargs|
    [second, kwargs[:third], first]
end
MyClass.my_method(1, 2, third: 3)
#=> [2, 3, 1]

Returns:

  • (self) —

    the mock itself

Raises:



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/grift/mock_method.rb', line 149

def mock_implementation(*)
  raise(Grift::Error, 'Must provide a block for the new implementation') unless block_given?

  premock_setup
  mock_executions = @mock_executions # required to access inside class instance block

  class_instance.remove_method(@method_name) if !@inherited && method_defined?
  class_instance.define_method @method_name do |*args, **kwargs|
    return_value = yield(*args, **kwargs)

    # record the args passed in the call to the method and the result
    mock_executions.store(args: args, kwargs: kwargs, result: return_value)
    return_value
  end
  class_instance.send(@method_access, @method_name)

  self
end

#mock_implementation_n_times(n) ⇒ self

Accepts a number n and a block and mocks the method to execute that block instaead of the original behavior the next n times the method is called while mocked. After the method has been called once, it will return to its original behavior. The method will continue to be watched.

IMPORANT: Calling #mock_clear clears the method call history. If it is called before the nth execution of the mocked method, the method will remain mocked for an additonal n calls.

Examples:

my_mock = Grift.spy_on(String, :downcase).mock_implementation_n_times(3) do
    x = 3 + 4
    x.to_s
end
["Banana", "Apple", "Orange", "Guava"].map(&:downcase)
#=> ["7", "7", "7", "guava"]
my_mock = Grift.spy_on(String, :downcase).mock_implementation_n_times(5) do
    x = 3 + 4
    x.to_s
end
["Banana", "Apple", "Orange", "Guava"].map(&:downcase)
#=> ["7", "7", "7", "7"]
my_mock.mock_clear # clear mock history before 5th (nth) method call
["Banana", "Apple", "Orange", "Guava"].map(&:downcase)
#=> ["7", "7", "7", "7"]

Parameters:

  • n (Number) —

    the number of times to mock the implementation

Returns:

  • (self) —

    the mock itself

Raises:

See Also:



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
 
# File 'lib/grift/mock_method.rb', line 249

def mock_implementation_n_times(n, *)
  raise(Grift::Error, 'Must provide a block for the new implementation') unless block_given?

  premock_setup

  # required to access inside class instance block
  mock_executions = @mock_executions
  clean_mock = lambda do
    unmock_method
    watch_method
  end

  class_instance.remove_method(@method_name) if !@inherited && method_defined?
  class_instance.define_method @method_name do |*args, **kwargs|
    return_value = yield(*args, **kwargs)

    # record the args passed in the call to the method and the result
    mock_executions.store(args: args, kwargs: kwargs, result: return_value)

    clean_mock.call if mock_executions.count == n

    return_value
  end
  class_instance.send(@method_access, @method_name)

  self
end

#mock_implementation_once ⇒ self

Accepts a block and mocks the method to execute that block instead of the original behavior the next time the method is called while mocked. After the method has been called once, it will return to its original behavior. The method will continue to be watched.

Examples:

my_mock = Grift.spy_on(String, :downcase).mock_implementation_once do
    x = 3 + 4
    x.to_s
end
["Banana", "Apple"].map(&:downcase)
#=> ["7", "apple"]

Returns:

  • (self) —

    the mock itself

Raises:

See Also:



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
 
# File 'lib/grift/mock_method.rb', line 186

def mock_implementation_once(*)
  raise(Grift::Error, 'Must provide a block for the new implementation') unless block_given?

  premock_setup

  # required to access inside class instance block
  mock_executions = @mock_executions
  clean_mock = lambda do
    unmock_method
    watch_method
  end

  class_instance.remove_method(@method_name) if !@inherited && method_defined?
  class_instance.define_method @method_name do |*args, **kwargs|
    return_value = yield(*args, **kwargs)

    # record the args passed in the call to the method and the result
    mock_executions.store(args: args, kwargs: kwargs, result: return_value)

    clean_mock.call

    return_value
  end
  class_instance.send(@method_access, @method_name)

  self
end

#mock_reset ⇒ Grift::MockMethod::MockExecutions

Clears the mock execution and calls data for this mock, and mocks the method to return nil.

Returns:



105
106
107
108
109
 
# File 'lib/grift/mock_method.rb', line 105

def mock_reset
  executions = mock_clear
  mock_return_value(nil)
  executions
end

#mock_restore(watch: false) ⇒ Grift::MockMethod::MockExecutions

Clears the mock execution and calls data for this mock, and restores the method to its original behavior. By default it also stops watching the method. This cleans up the mocking and restores expected behavior.

Parameters:

  • watch (Boolean) (defaults to: false) —

    whether or not to keep watching the method

Returns:



121
122
123
124
125
126
 
# File 'lib/grift/mock_method.rb', line 121

def mock_restore(watch: false)
  executions = mock_clear
  unmock_method if @true_method_cached
  watch_method if watch
  executions
end

#mock_return_value(return_value = nil) ⇒ self

Accepts a value and mocks the method to return that value instead of executing its original behavior while mocked.

Examples:

my_mock = Grift.spy_on(String, :upcase).mock_return_value('BANANA')
"apple".upcase
#=> 'BANANA'

Parameters:

  • return_value (defaults to: nil) —

    the value to return from the method

Returns:

  • (self) —

    the mock itself

See Also:

  • Grift#mock


292
293
294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/grift/mock_method.rb', line 292

def mock_return_value(return_value = nil)
  premock_setup
  mock_executions = @mock_executions # required to access inside class instance block

  class_instance.remove_method(@method_name) if !@inherited && method_defined?
  class_instance.define_method @method_name do |*args, **kwargs|
    # record the args passed in the call to the method and the result
    mock_executions.store(args: args, kwargs: kwargs, result: return_value)
    return_value
  end
  class_instance.send(@method_access, @method_name)

  self
end

#mock_return_value_n_times(n, return_value = nil) ⇒ self

Accepts a value and mocks the method to return that value n times instead of executing its original behavior while mocked. After the method has been called n times, it will return to its original behavior. The method will continue to be watched.

IMPORANT: Calling #mock_clear clears the method call history. If it is called before the nth execution of the mocked method, the method will remain mocked for an additional n calls.

Examples:

my_mock = Grift.spy_on(String, :upcase).mock_return_value_n_times(2, "BANANA")
["apple", "apple", "apple"].map(&:upcase)
#=> ["BANANA", "BANANA", "APPLE"]
my_mock = Grift.spy_on(String, :upcase).mock_return_value_n_times(4, "BANANA")
["apple", "apple", "apple"].map(&:upcase)
#=> ["BANANA", "BANANA", "BANANA"]
my_mock.mock_clear # clear mock history before 4th (nth) method call
["apple", "apple", "apple"].map(&:upcase)
#=> ["BANANA", "BANANA", "BANANA"]

Parameters:

  • n (Number) —

    the number of times to mock the return value

  • return_value (defaults to: nil) —

    the value to return from the method n times

Returns:

  • (self) —

    the mock itself



374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
 
# File 'lib/grift/mock_method.rb', line 374

def mock_return_value_n_times(n, return_value = nil)
  premock_setup

  # required to access mock inside class instance block
  mock_executions = @mock_executions
  clean_mock = lambda do
    unmock_method
    watch_method
  end

  class_instance.remove_method(@method_name) if !@inherited && method_defined?
  class_instance.define_method @method_name do |*args, **kwargs|
    # record the args passed in the call to the method and the result
    mock_executions.store(args: args, kwargs: kwargs, result: return_value)

    clean_mock.call if mock_executions.count == n

    return_value
  end
  class_instance.send(@method_access, @method_name)

  self
end

#mock_return_value_once(return_value = nil) ⇒ self

Accepts a value and mocks the method to return that value once instead of executing its original behavior while mocked. After the method has been called once, it will return to its original behavior. The method will continue to be watched.

Examples:

my_mock = Grift.spy_on(String, :upcase).mock_return_value_once("BANANA")
["apple", "apple"].map(&:upcase)
#=> ["BANANA", "APPLE"]

Parameters:

  • return_value (defaults to: nil) —

    the value to return from the method once

Returns:

  • (self) —

    the mock itself



322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/grift/mock_method.rb', line 322

def mock_return_value_once(return_value = nil)
  premock_setup

  # required to access mock inside class instance block
  mock_executions = @mock_executions
  clean_mock = lambda do
    unmock_method
    watch_method
  end

  class_instance.remove_method(@method_name) if !@inherited && method_defined?
  class_instance.define_method @method_name do |*args, **kwargs|
    # record the args passed in the call to the method and the result
    mock_executions.store(args: args, kwargs: kwargs, result: return_value)

    clean_mock.call

    return_value
  end
  class_instance.send(@method_access, @method_name)

  self
end

#mock_return_values_in_order(return_values) ⇒ self

Accepts an array of values and mocks the method to return those values in order instead of executing its original behavior while mocked. After the method has been called enough times to return each of the values, it will return to its original behavior. The method continue to be watched.

Examples:

mock_values = ["APPLE", "BANANA", "ORANGE"]
my_mock = Grift.spy_on(String, :upcase).mock_return_values_in_order(mock_values)
["pineapple", "orange", "guava", "mango", "watermelon"].map(&:upcase)
#=> ["APPLE", "BANANA", "ORANGE", "MANGO", "WATERMELON"]

Parameters:

  • return_values (Array) —

    the values to return from the method in order

Returns:

  • (self) —

    the mock itself



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
 
# File 'lib/grift/mock_method.rb', line 414

def mock_return_values_in_order(return_values)
  unless return_values.is_a?(Array) && !return_values.empty?
    raise(Grift::Error, 'Must provide a non-empty array for the return values')
  end

  premock_setup

  # required to access mock inside class instance block
  mock_executions = @mock_executions
  clean_mock = lambda do
    unmock_method
    watch_method
  end
  return_values_internal = return_values.dup

  class_instance.remove_method(@method_name) if !@inherited && method_defined?
  class_instance.define_method @method_name do |*args, **kwargs|
    # record the args passed in the call to the method and the result
    return_value = return_values_internal.shift
    mock_executions.store(args: args, kwargs: kwargs, result: return_value)

    clean_mock.call if return_values_internal.empty?

    return_value
  end
  class_instance.send(@method_access, @method_name)

  self
end

#results ⇒ Array

Returns an array of the results of each call to the mocked method This is syntactical sugar equivalent to calling mock and then results.

Examples:

my_mock = Grift.spy_on(Number, :+)
x = (3 + 4) + 5
my_mock.results
#=> [7, 12]

Returns:

  • (Array) —

    an array of results

See Also:



529
530
531
 
# File 'lib/grift/mock_method.rb', line 529

def results
  @mock_executions.results
end

#to_s ⇒ String

String representation of the MockMethod

Returns:

  • (String)

See Also:



451
452
453
 
# File 'lib/grift/mock_method.rb', line 451

def to_s
  Grift::MockMethod.hash_key(@klass, @method_name)
end