Forem: Juanito Fatas

Optimization Techniques by Benchmark Winners

Juanito Fatas — Wed, 26 Feb 2020 02:44:55 +0000

This post is based on Jeremy Evans‘s Optimization Techniques Used by the Benchmark Winners presentation. Slides | YouTube at Ruby Kaigi 2019. It‘s better to watch his fabulous presentation, but you can come back here for written references. These techniques coming from maintaining Sequel and Roda. These two gems have always been 0 issues. It‘s probably the best maintained gems. Sequel and Roda are the leaders for Ruby in TechEmpower benchmark results. Let‘s see what lessons can we learn to optimize Ruby.

These techniques may not be the best to write at application code level but good when building libraries, optimize critical path of your application. The ideas and principles are universally applicable.

Avoid processing

2:24

No code is faster than no code
-- Merb Motto

Fastest code does the least. Execute less code. Run code once instead of many times, once is better than many. In big-o terms: O(1) > O(n).

Take initialize model instance as example, the Sequel is definitely faster than Active Record because it does much less things.

Active Record:

# https://github.com/rails/rails/blob/8ae8e19a33f4749e529b1649f4f0ace1dbb37285/activerecord/lib/active_record/core.rb#L357-L369
def init_with_attributes(attributes, new_record = false) # :nodoc:
  @new_record = new_record
  @attributes = attributes

  init_internals

  yield self if block_given?

  _run_find_callbacks
  _run_initialize_callbacks

  self
end

Sequel:

# https://github.com/jeremyevans/sequel/blob/4a146796f273ce14e121954ad4e7f3134209386d/lib/sequel/model/base.rb#L221
def call(values)
  o = allocate
  o.instance_variable_set(:@values, values)
  o
end

Delay Computations

For web app, it means to do at initialization time is better than doing at Runtime. See Hound applies this for putting environment variables into constants.

Example: Active Record & Sequel Callbacks

Active Record runs find and initialize callbacks during initialization. Even when there are no callbacks defined on the model, so it slows down:

# lib/active_record/core.rb
def init_with_attributes(attributes, new_record = false)
  ...

  _run_find_callbacks
  _run_initialize_callbacks

  ...
end

Sequel does this by having a Plugin System¹. In Sequel, if you need callbacks, add plugin :after_initialize to your model. Nothing gets run if you‘re not using callbacks.

Inheritance gives every subclass things that they may not need. Prefer Composition over Inheritance. Plugins give all subclass a chance to only take what they need. Sequel and Roda use plugins for most features so they are faster.

Reduce Object Allocations

10:28

The init_internals in Active Record set few instance variables to nil:

def init_internals
  @primary_key              = self.class.primary_key
  @readonly                 = false
  @destroyed                = false
  @marked_for_destruction   = false
  @destroyed_by_association = nil
  @_start_transaction_state = nil
  @transaction_state        = nil

  self.class.define_attribute_methods
end

Jeremy found avoid @instance_variable = nil resulted in 150% faster in Sequel and Roda. This is controversial because only in verbose mode, using instance variable without define first will emit warnings. Emit warnings makes it slower. He made a patch to remove such warnings but got rejected for backward compatibility.

You can find another example of delay allocation of instance variables in this commit from rails/rails. Delay setting instance variable to hash by setting it to nil first.

Another common place to reduce object allocations is string. Before Ruby 2.3, we need to call freeze on strings. Since 2.3, we can add a frozen string literal in a file and by default all strings in that file are frozen.

Reduce String Allocations

Before frozen string literal (Ruby < 2.3), introduce a constant for common places of strings SELECT = 'SELECT'.freeze was okay:

SELECT = 'SELECT'.freeze
SPACE = ' '.freeze
FROM = 'FROM'.freeze

def select_sql
  sql = String.new
  sql ‌<< SELECT ‌<< SPACE
  sql ‌<< literal(columns)
  sql ‌<< SPACE <<‌ FROM <<‌ SPACE
  sql ‌<< literal(table)
end

Since Ruby 2.3:

# frozen-string-literal: true

def select_sql
  sql = String.new
  sql << "SELECT "
  sql << literal(columns)
  sql << " FROM "
  sql << literal(table)
end

It‘s simpler and easier to understand. Avoids string allocations in the meantime with less operations (<<), hence faster.

Reduce Hash allocations

Avoid default hash in method definition:

class Sequel::Dataset
  def union(dataset, opts={})
    compound_clone(:union, dataset, opts)
  end
end

Introduce an empty frozen hash constant:

class Sequel::Dataset
  OPTS = {}.freeze

  # 100% faster than `opts={}`.
  def union(dataset, opts=OPTS)
    compound_clone(:union, dataset, opts)
  end

  # Keyword argument is slower than Optimal hash constant.
  def union(dataset, **opts)
    compound_clone(:union, dataset, opts)
  end
end

Right now double splat keyword arguments are slower (2.7) than above empty frozen hash constant technique. Keyword arguments also have maintenance barriers the method caller and callee all need to change when keyword changes.

Reduce Proc Allocation

15:03

For proc does not depend on something else or any runtime state:

def indifferent_params
  Hash.new { |h, k| h[k.to_s] if k.is_a?(Symbol) }
end

can extract into a constant:

IND = proc { |h, k| h[k.to_s] if k.is_a?(Symbol) }
def indifferent_params2
  Hash.new(&IND)
end

About 300%+ faster.

Benchmark.ips do |x|
  x.report("inline proc") { indifferent_params }
  x.report("constant proc") { indifferent_params2 }
  x.compare!
end

Comparison:
       constant proc:  5645873.6 i/s
         inline proc:  1469374.7 i/s - 3.84x  slower

Reduce Array Allocation

This is not from the presentation but I think it‘s great to also include an example here.

Use transform_values when modifying hashes. See this commit from rails/rails:

    def escape(params)
-     Hash[params.map { |k, v| [k, Rack::Utils.escape(v)] }]
+     params.transform_values { |v| Rack::Utils.escape(v) }
    end

Minimize Indirection

Say a common operation in our app is to convert a string into Integer. We could have a lambda, a kernel method, a dedicated object with call to do so, or an object that aliased call to Integer():

string = "42"

using_lambda = lambda { |str| Integer(str) }
using_kernel = Kernel.method(:Integer)
using_object = Object.new
def using_object.call(str); Integer(str); end
no_indirection_object = Object.new
class << no_indirection_object
  alias call Integer
  public :call
end

Benchmark.ips do |x|
  x.report("lambda") { using_lambda.call(string) }
  x.report("Kernel") { using_kernel.call(string) }
  x.report("Object") { using_object.call(string) }
  x.report("Object v2") { no_indirection_object.call(string) }
  x.compare!
end

Comparison:
  Object v2:  6258404.2 i/s
  Object:     5674514.7 i/s - same-ish: difference falls within error
  lambda:     5199998.6 i/s - 1.20x  slower
  Kernel:     5130274.6 i/s - 1.22x  slower

We see using Kernel.method is slowest here. A lambda is slightly faster than that. Define a method on an object is faster than calling a lambda. Avoid indirection (by alias call to Integer) further makes it ~10% faster. The benchmark example above aligns with Jeremy‘s observations on benchmarking Sequel from the presentation. A similar observation is also found from graphql-ruby land that they‘re now in favor of method call instead of using procs.

Defining Methods

19:02

def foo
  1
end

# 50% slower than `def foo; 1; end`
define_method(:foo) do
  1
end

So we always want to define method with def. Sometimes we want to define at runtime. Take Sequel as example, it needs to dynamically define model columns‘s setters and getters, can achieve with class_eval + def.

# def_column
columns.each do |column|
  class_eval("def #{column}; @values[:#{column}]; end")
  class_eval("def #{column}=(v); @values[:#{column}] = v; end")
end

This works for column name without spaces "name", with space "employee name" it does not work. We need to use define_method:

columns.each do |column|
  column = column.to_sym
  define_method(column) do
    @values[column]
  end

  define_method(:"#{column}=") do |v|
    @values[column] = v
  end
end

which is slower than using class_eval + def.

These columns with "bad" names are not the majority of the case but changing the implementation to this hurts performance. Here comes another general optimization principle.

Separate Common from Uncommon

21:18

We usually have a fast approach for the simple cases but it fails in more complex cases. Assume the simple cases are more common, we can speed up by separating the two cases. Sequel separates the common from the uncommon, to have the best of both worlds. Below are simplified from Sequel‘s column definitions:

def def_column_accessor(*columns)
  columns, bad_columns = columns.partition { |x| /\A[A-Za-z_][A-Za-z0-9_]*\z/.match(x.to_s) }

  bad_columns.each{|x| def_bad_column_accessor(x)} # define_method
  columns.each do |column|
    # faster with `def`
  end
end

In general def > define_method, but there is one case where define_method is preferred for performance. Let‘s see an example:

class Def
  def self.def_numbers(first, last)
    class_eval("def numbers; (#{first}..#{last}).to_a.freeze; end")
  end

  def self.def_numbers2(first, last)
    array = (first..last).to_a.freeze
    define_method(:numbers2) do
      array
    end
  end
end

Benchmark.ips do |x|
  x.report("def") { Def.def_numbers(1, 10) }
  x.report("define_method") { Def.def_numbers2(1, 10) }
  x.compare!
end

Comparison:
       define_method:   542551.0 i/s
                 def:    62085.7 i/s - 8.74x  slower

So prefer def over define_method unless you can access local variables from surrounding scope to avoid computations, only then define_method > def.

Related to this. If we need to accept blocks and store blocks, and use instance_exec to execute these blocks. Let‘s implement a before hook to demonstrate this idea.

def self.before(&block)
  before_hooks << block
end

def before
  # execute all blocks passed to self.before
  self.class.before_hooks.each { |block| instance_exec(&block) }
end

This works but instance_exec creates singelton class for the instance, it‘s faster to use methods. We can define before hooks methods by naming them based on their position in the array, then we pass to define_method:

def self.before(&block)
  meth = :"_before_hook_#{before_hooks.length}"
  define_method(meth, &block)
  before_hooks << meth
end

def before
  self.class.before_hooks.each { |m| send(m) }
end

Execute these before hooks could be a send which is faster. This is good but we can do better. Since we know which methods will be executed, we can define the before to execute these before hook methods by:

def self.before(&block)
  # ...

  class_eval("def before; #{before_hooks.join(';')}; end")
end

This is faster because it avoids the need to call each on before hooks array and each method invoked directly instead of one indirection send. But we can still do better.

def self.before(&block)
  # ...

  if before_hooks.length > 1
    class_eval("def before; #{before_hooks.join(';')}; end")
  else
    class_eval("alias before #{before_hooks.first}")
  end
end

If there is only a single before hook, we can alias to that method hence minimized indirection.

This approach to implementing before hooks compare to using define_method, is about 200% faster because it avoids a lot of internal indirections. One caveat of this approach is that it does not work with before { |x| }. But we can fix this by:

unless block.arity == 0 || block.arity == -1
  b = block
  block = lambda { instance_exec(&b) }
end

Optimize Inner Loops

26:16

Another best place to start optimizing is inside any inner loops. Let‘s see an example from Sequel‘s Anywhere adapter:

# https://github.com/jeremyevans/sequel/blob/ae50b5e98efb3ad902fb37f370cbf237644a12d3/lib/sequel/adapters/sqlanywhere.rb#L157-L187
while db.api.sqlany_fetch_next(rs) == 1
  max_cols = db.api.sqlany_num_cols(rs)
  h2 = {}
  max_cols.times do |cols|
    h2[col_map[db.api.sqlany_get_column_info(rs, cols)[2]]||db.api.sqlany_get_column_info(rs, cols)[2]] =
      cps[db.api.sqlany_get_column_info(rs, cols)[4]].nil? ?
          db.api.sqlany_get_column(rs, cols)[1] :
            db.api.sqlany_get_column_info(rs, cols)[4] != 500 ?
              cps[db.api.sqlany_get_column_info(rs, cols)[4]].call(db.api.sqlany_get_column(rs, cols)[1]) :
                convert ? cps[db.api.sqlany_get_column_info(rs, cols)[4]].call(db.api.sqlany_get_column(rs, cols)[1]) :
                  db.api.sqlany_get_column(rs, cols)[1]
  end
  yield h2
end unless rs.nil?

And there are some hidden ternary operators without parentheses...So this is complex, but not the reason why it‘s slow. It‘s slow because:

db.api.sqlany_get_column_info(rs, cols) repeated 5 times with same arguments in the inner loop. Another one is db.api.sqlany_get_column(rs, cols)[1] repeated 4 times. After a serious refactoring, now we arrive at:

def fetch_rows(sql)
  db = @db
  cps = db.conversion_procs
  api = db.api
  execute(sql) do |rs|
    convert = convert_smallint_to_bool
    col_infos = []
    api.sqlany_num_cols(rs).times do |i|
      _, _, name, _, type = api.sqlany_get_column_info(rs, i)
      cp = if type == 500
        cps[500] if convert
      else
        cps[type]
      end
      col_infos << [output_identifier(name), cp]
    end

    self.columns = col_infos.map(&:first)
    max = col_infos.length

    if rs
      while api.sqlany_fetch_next(rs) == 1
        i = -1
        h = {}
        while (i+=1) < max
          name, cp = col_infos[i]
          v = api.sqlany_get_column(rs, i)[1]
          h[name] = cp && v ? cp.call(v) : v
        end
        yield h
      end
    end
  end
  self
end

The inner loop now becomes much simpler:

while (i+=1) < max
  name, cp = col_infos[i]
  v = api.sqlany_get_column(rs, i)[1]
  h[name] = cp && v ? cp.call(v) : v
end

All operations inside are stored on local variables. This seems not a big deal but if you are retrieving 100,000 rows with each row of 10 columns, this makes a big difference. By define local variables, this saves millions of method calls. This is another general optimization principle.

Prefer Local Variables

29:02

Prefer local variables whenever possible especially in inner loop as demostrated above.

Local variables > Instance variables
Local variables > Constant
Local variables > Method Calls

local variables are faster because it minimize the number of indirections.

while v.s. each

Let‘s go back to the above refactoring example. The deliberate use of while in the inner loop:

while (i+=1) < max
  name, cp = col_infos[i]
  v = api.sqlany_get_column(rs, i)[1]
  h[name] = cp && v ? cp.call(v) : v
end

Inner loop like this is one of the few places that make sense to use while instead of each because using each for inner loops can hurt performance, because it requires a seperate a stackframe to push and pop for each iteration.

Choose Faster Algorithms

31:07

Sinatra routes (by pattern) v.s. Roda‘s routing tree

Given thousands of routes. Sinatra will be busy matching against all routes. O(N) Roda‘s routing tree would take route segments. Filter out the segment to the right tree. O(log(N))

Roda.route do |r|
  r.on "foo" do
    # /foo ...
  end
  r.on "bar" do
    # /bar ...
  end
end

But the worst case is still O(N) and Jeremy does not accept the worst case being O(n)... Here comes multi route:

Roda.plugin :multi_route

Roda.route("foo") { |r| # /foo... }
Roda.route("bar") { |r| # /bar... }

Roda.route { |r| r.multi_route }

Multi route builds a regexp to match initialial segment (/foo, /bar, ...) then dispatch:

Roda.route { |r| r.multi_route }

which brings the performance back to O(log(n)). But he wants O(1)...

Roda.plugin :static_routing

Roda.static_get("foo") { |r| # /foo... }
Roda.static_get("bar") { |r| # /bar... }

Roda.route { |r| }

But O(1) gives up many advantages. In the end, he created hash_routes plugin to have the best of both worlds:

Roda.plugin :hash_routes

Roda.hash_routes do
  on("foo") do |r|
    r.hash_routes
  end
  is("foo/bar") do |r|

  end

Roda.route do |r|
  r.hash_routes
end

Cache when Possible

39:40

Introduce cache is the highest ratio of the following formula:

  % Increase in Performance
-----------------------------
    Lines of Code Changed

Maximum performance increase over minimum lines of code changed.

Use case: Sequel Symbol Literalization

40:00

:column_name
# => '"column_name"'

def self.split_symbol(sym)
  v = case s = sym.to_s
  when /\A((?:(?!__).)+)__((?:(?!___).)+)___(.+)\z/
    [$1.freeze, $2.freeze, $3.freeze].freeze
  when /\A((?:(?!___).)+)___(.+)\z/
    [nil, $1.freeze, $2.freeze].freeze
  when /\A((?:(?!__).)+)__(.+)\z/
    [$1.freeze, $2.freeze, nil].freeze
  else
    [nil, s.freeze, nil].freeze
  end

  v
end

Introduce symbol cache:

SPLIT_SYMBOL_CACHE = {}

def self.split_symbol(sym)
  unless v = Sequel.synchronize { SPLIT_SYMBOL_CACHE[sym] }
    v = case s = sym.to_s
    when /\A((?:(?!__).)+)__((?:(?!___).)+)___(.+)\z/
      [$1.freeze, $2.freeze, $3.freeze].freeze
    when /\A((?:(?!___).)+)___(.+)\z/
      [nil, $1.freeze, $2.freeze].freeze
    when /\A((?:(?!__).)+)__(.+)\z/
      [$1.freeze, $2.freeze, nil].freeze
    else
      [nil, s.freeze, nil].freeze
    end
    Sequel.synchronize { SPLIT_SYMBOL_CACHE[sym] = v }
  end
  v
end

This is over 1000% faster after introduced this cache.

Globally Frozen, Locally Mutable

41:50

Freeze global state like classes, objects that is accessed by multiple threads. Local objects instantiated per request remain mutable for ease of use (cache). This approach is mainly to improve reliability (thread safe). This also improves performance because frozen object means it is easy to cache them.

Note that Frozen is not the same as Immutable. Frozen means Immutable State + Mutable Cache.

# https://github.com/jeremyevans/sequel/blob/cc5c1612fb4c42e7cbf6db6b0572001fd5bf6b58/lib/sequel/dataset/misc.rb#L25-L30
OPTS = {}
def initialize(db)
  @db = db
  @opts = OPTS # state in frozen hash
  cache = {} # <-- mutable cache
  freeze # <-- freeze this object
end

Make sure access to mutable cache is protected by Mutex for thread safety.

Optimization Through Metaprogramming

46:11

class Album < Sequel::Model
  dataset_module do
    def by_name
      order(:name)
    end

    def released
      where(released: true)
    end
  end
end

# Album.where(released: true).order(:name).first
# => Album.released.by_name.first

This is good to DRY up code but does not improve performance. Jeremy introduced metaprogramming for users to define like following and speed up by introduced dataset cache to these metaprogramming generated methods:

class Album < Sequel::Model
  dataset_module do
    order :by_name, :name # def by_name
                          #   cache { order(:name) }
                          # end

    where :released, released: true
    # def released
    #   cache { where(released: true) }
    # end
  end
end

Example: Roda String Matching

48:41

Roda was forked from Cuba. The matching of routing segment was:

def match_string(str)
  consume(Regexp.escape(str))
end

# https://github.com/soveran/cuba/blob/1dce54d0926c5d6e5daab033a8e9685c6faa4227/lib/cuba.rb#L214-L226
def consume(pattern)
  matchdata = env[Rack::PATH_INFO].match(/\A\/(#{pattern})(\/|\z)/)

  return false unless matchdata

  path, *vars = matchdata.captures

  env[Rack::SCRIPT_NAME] += "/#{path}"
  env[Rack::PATH_INFO] = "#{vars.pop}#{matchdata.post_match}"

  captures.push(*vars)
end
private :consume

This code looks perfectly fine. But let‘s see how Jeremy optimized it. First is to avoid allocations. The first change was to include the proceeding slash in the first capture to avoid extra array allocation for the captures:

- /\A\/(#{pattern})(\/|\z)/
+ /\A(\/(#{pattern}))(\/|\z)/

...

- path, *vars = matchdata.captures
+ vars = matchdata.captures

- env[Rack::SCRIPT_NAME] += "/#{path}"
+ env[Rack::SCRIPT_NAME] += vars.shift

Next is to use a regular expression feature, positive lookahead assertion instead of a capture:

- /\A(\/(#{pattern}))(\/|\z)/
+ /\A(\/(#{pattern}))(?=\/|\z)/

So we no longer need to pop the last element of capture variables (vars):

- env[Rack::PATH_INFO] = "#{vars.pop}#{matchdata.post_match}"
+ env[Rack::PATH_INFO] = matchdata.post_match

Also avoid the allocation of additional string by using post match directly.

He then profile and found generating a new regular expression every time consume was called takes a large portion of time. Then he introduced cached matcher:

   def match_string(str)
-    consume(Regexp.escape(str))
+    consume(self.class.cached_matcher(str) { Regexp.escape(str) })
   end

This change is possible because consume was a private method. Another optimizations technique is to keep most methods private.

Keep Most Methods Private

Only makes a method public if it needs to be public. When method is private, you are free to change its API to improve performance. Public methods have limit options to optimize.

Prefer String operations over Regexp operations

In Roda 3.0, the matching of string segment changed to use string operations instead of regular expression matching:

def match_string(str)
  rp = @remaining_path
  if rp.start_with?("/#{str}") # <----
    last = str.length + 1
    case = rp[last] # <----
    when "/"
      @remaining_path = rp[last, rp.length] # <----
    when nil
      @remaining_path = ""
    end
  end
end

But still, there are two String allocations: rp.start_with?("/#{str}") and rp[last].

Prefer Integer operations over String operations

Iterating by index and checking if first character of string is 47 (47 is ascii code of /):

def _match_string(str)
  rp = @remaining_path
  length = str.length

  match = case rp.rindex(str, length) # <------
  when nil
    return
  when 1
    rp.getbyte(0) == 47 # <--- start_with?("/")
  else
    length == 0 && rp.getbyte(0) == 47 # <--- start_with?("/")
  end

  if match
    length += 1
    case rp.getbyte(length)
    when 47
      @remaining_path = rp[length, 100000000]
    when nil
      @remaining_path = ""
    end
  end
end

The most common failure case when nil also moved up because it happens more often. Another trick is to use a large number that is larger than any reasonable path length: rp[length, 100000000].

Finally...

Remember that optimizations come last.
First make it work, then make it correct.
After you make it fun, then you can make it fast.
—Jeremy Evans

Profile to find where to optimize. Then Benchmark your change.

That‘s all from Jeremy‘s presentation.

There is no silver bullet. It depends on the context. We must try ourselves. Verify it‘s faster than the other instead of directly quoting anything here.

The faults are probably mine. I‘m happy to fix if you would let me know. You can reach out to him on twitter for more questions: @jeremyevans0 or GitHub to see more of his work.

Thanks for reading!

Originally published on juanitofatas.com on January 27th, 2020.

Learn more about the plugin system of Sequel and Roda from Janko Marohnić. ↩

Building a Mocking Library in Ruby

Juanito Fatas — Mon, 27 Jan 2020 09:35:03 +0000

This tutorial is based on Andy Lindeman’s awesome talk — Building a Mocking Library presented at Ancient City Ruby 2013. This is not a direct transcript of the video, but the code presented is almost the same (with minimal changes).

In his talk, Andy showed us how we can build a Mocking library for Minitest with just basic knowledge of Ruby and I felt that it‘s actually a great way to learn Ruby! So I decided to document the talk in writing and share it up here on the blog so that we can all learn together.

Goal

We are going to implement a simple Mocking library for Minitest.

Given an object:

# Test double
object = Object.new

We should be able to stub a method on this object and it will return our stubbed value:

# Stub
allow(object).to receive(:full?).and_return(true)
object.full? # => true

We should be able to mock an object (mock will verify if removed was ever called, while stub does not do that check):

# Mock
item_id = 1234
assume(object).to receive(:remove).with(item_id)

Why don‘t we use expect(w).to receive(:remove).with(item_id) here, similar to RSpec? That‘s because Minitest has an #expect method, so let‘s avoid redefining it.

Design

We will have two main classes - StubTarget and ExpectationDefinition.

Remember our Goal? In order to be able to do this:

allow(w).to receive(:full?).and_return(true)

We‘ll break them up as follows using our two main classes:

allow(w).to      receive(:full?).and_return(true)
^^^^^^^^^^^      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#<StubTarget>    #<ExpectationDefinition>

Enough Ruby that You Need to Know

Method Dispatch

How does Ruby find methods? It climbs up the ancestors chain! When you invoke to_s on object object, Ruby asks object...

Ruby: Hey, do you have to_s method?
object: Yup. I do.
Ruby: Awesome! Call it!
object: (invoking to_s)

Then it returns the result of object.to_s which is "#<Object:0x007fc0223b8280>":

> object = Object.new
=> #<Object:0x007fc0223b8280>

> object.to_s
=> "#<Object:0x007fc0223b8280>"

Ancestors Chain

If Ruby can't find the method you want to call, it will climb up the ancestors chain, till it finds a class that responds to the message, otherwise it eventually throws a NoMethodError exception.

object.class.ancestors
=> [Object, Kernel, BasicObject] # (searching from left to right)

Define a Method for a Specific Object

Ruby has a singleton class for every object and you can define a method in the singleton class.

The singleton class might be not visible in the ancestors chain above, but it's there.

Singleton Class

The "Singleton Class" is easily confused with the Singleton design pattern.

In fact, singleton class is an anonymous class attached to a specific object. Best illustrated with an example:

object = Object.new

def object.hello_world
  "Hello, World!"
end

object.hello_world # => "Hello, World!"

another_object = Object.new

object.hello_world # => NoMethodError (2)

In the example above, we are adding a hello_world method to the object. But the hello_world method wasn't added to the Object class (See (2) above).

As you can see, Ruby insert the hello_world method into object's singleton class!

`define_singleton_method`

Another way to define a method for singleton class, is to use define_singleton_method(symbol, method_object).

The example above could be re-written as follows:

> object = Object.new
=> #<Object:0x007fc0223b8280>

> object.singleton_class
=> #<Class:#<Object:0x007fc0223b8280>>

> object.define_singleton_method(:hello_world) { "Hello, World!" }

The define_singleton_method accepts a method name and a Method object. Think of a Method object as similar to a proc or lambda.

That's enough Ruby that you need to know. Yup. That's all!

Building a Mock Object Library

Since this is a Mocking library, let's make it a gem!

Your Mocking Gem

Let's gemify our mocking library. You can name it using this pattern: yourname_mock. My name is Juanito and so I will call it juanito_mock, and we'll also use bundle gem command provided by Bundler to create a skeleton of our gem:

$ bundle gem juanito_mock && cd juanito_mock

Note that Bundler may prompt you to choose which test library you want to use, type minitest and hit ENTER.

Creating gem 'juanito_mock'...
MIT License enabled in config
Do you want to generate tests with your gem?
Type 'rspec' or 'minitest' to generate those test files now and in the future. rspec/minitest/(none):

If your generated skeleton gem has no tests or is generated with spec folder, edit ~/.bundle/config file, add this line (or modify):

BUNDLE_GEM__TEST: minitest

Remove the generated folder and repeat it from the top again.

The structure of the gem should look like this:

├── Gemfile
├── LICENSE.txt
├── README.md
├── Rakefile
├── bin
│   ├── console
│   └── setup
├── juanito_mock.gemspec
├── lib
│   ├── juanito_mock
│   │   └── version.rb
│   └── juanito_mock.rb
└── test
    ├── juanito_mock_test.rb
    └── test_helper.rb

Why Minitest?

Since we are implementing a RSpec-like mocking syntax, we don't want to use RSpec here so as to avoid confusions and conflicts with the original RSpec mocking library. Hence, we are going to use Minitest here to test our Mocking library.

By the way, the correct spelling of Minitest is Minitest, not MiniTest.

Renamed MiniTest to Minitest. Your pinkies will thank me.
Minitest 5.0.0 History

Setup Minitest

First lock Minitest to 5.8.0 in gemspec's development dependency in order to use it in development:

spec.add_development_dependency "minitest", "5.8.0"

Latest version of Minitest is 5.8.0 as of 16th Aug 2015.

Add these lines to test/test_helper.rb:

require "minitest/spec"
require "minitest/autorun"

Reorder and your test/test_helper.rb should look like this:

$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
require "minitest/spec" # simple and clean spec system
require "minitest/autorun" # easy and explicit way to run all your tests
require "juanito_mock"

Note on quotes of string. Just Use double-quoted strings

We use Minitest/Spec syntax to write our tests and require "minitest/autorun" to easily run all our tests.

Next, delete the generated tests in test/juanito_mock_test.rb and update it with DSL:

require "test_helper"

describe JuanitoMock do

end

Now if you run rake, you should have a working test suite:

$ rake
Run options: --seed 55155

# Running:


Finished in 0.000783s, 0.0000 runs/s, 0.0000 assertions/s.

0 runs, 0 assertions, 0 failures, 0 errors, 0 skips

Now let's write our first test!

Implementation of Stub

Create a test case by using it followed by a descriptive description string, and a block of code:

describe JuanitoMock do
  it "allows an object to receive a message and returns a value" do
    warehouse = Object.new

    allow(warehouse).to receive(:full?).and_return(true)

    warehouse.full?.must_equal true
  end
end

Let's walk through the code..

warehouse = Object.new

Firstly, we create a new instance of Object and assign it to a variable warehouse.

allow(warehouse).to receive(:full?).and_return(true)

Then, we create a stub that will receive the method full? and return the result true.

warehouse.full?.must_equal true

Finally, we verify our stub is working by using must_equal.

Sidenote: See the blank lines in our test? These blank lines are very important to distinguish different phases of the test.

How to Run Tests

First, let's take a look at Rakefile:

require "bundler/gem_tasks"
require "rake/testtask"

Rake::TestTask.new(:test) do |t|
  t.libs << "test"
  t.libs << "lib"
  t.test_files = FileList['test/**/*_test.rb']
end

task :default => :test

require "rake/testtask" included in a file with a rake task defined (rake test) that can run our tests easily via rake, see Rake::TestTask for more information.

You can see a full list of rake tasks available by typing rake -T in your terminal:

$ rake -T
rake build          # Build juanito_mock-0.1.0.gem into the pkg directory
rake install        # Build and install juanito_mock-0.1.0.gem into system ...
rake install:local  # Build and install juanito_mock-0.1.0.gem into system ...
rake release        # Create tag v0.1.0 and build and push juanito_mock-0.1...
rake test           # Run tests

The build, install, install:local, and release tasks are provided by Bundler. See bundler/bundler lib/bundler/gem_helper.rb

But you also see that rake test is available for use.

To make it even simple to run your tests, the Rakefile has this task :default => :test which basically maps the default rake task to running tests.

This means that you can just type rake instead of rake test to run all your tests.

Let's run it:

$ rake
Run options: --seed 49489

# Running:

E

Finished in 0.000963s, 1038.1963 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `allow' for #<#<Class:0x007fe04516bf70>:0x007fe045d001d8>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:7:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Yay! Our first failing test, read the error carefully to find out what to do next:

undefined method `allow' for #<#<Class:0x007fe04516bf70>:0x007fe045d001d8>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:7:in `block (2 levels) in <top (required)>'

It even tells you which line to fix the code:

test/juanito_mock_test.rb:7

:7 means line 7 from the file test/juanito_mock_test.rb.

Add DSL to Minitest

Let's proceed to fix the failing test.

From Minitest README, we know every test in Minitest is a subclass of Minitest::Test:

To add method allow to Minitest::Test, all we have to do is to create a module TestExtensions and include it in the Minitest::Test class:

require "juanito_mock/version"

module JuanitoMock
  module TestExtensions
    def allow
    end
  end
end

class Minitest::Test
  include JuanitoMock::TestExtensions
end

Let's run our test:

$ rake
Run options: --seed 41300

# Running:

E

Finished in 0.001002s, 997.6067 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
ArgumentError: wrong number of arguments (1 for 0)
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:5:in `allow'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Nice! Now we get a different error:

ArgumentError: wrong number of arguments (1 for 0)
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:5:in `allow'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

The error occurs because we are calling allow like so allow(warehouse) in our code, which means we are passing in an argument warehouse which our allow method doesn't accept yet.

allow(warehouse).to receive(:full?).and_return(true)

Let's fix this by modifying our allow method to accept an argument obj. Then, we'll construct an instance of StubTarget with the argument, as described in our design:

require "juanito_mock/version"

module JuanitoMock
  module TestExtensions
    def allow(obj)
      StubTarget.new(obj)
    end
  end
end

class Minitest::Test
  include JuanitoMock::TestExtensions
end

Now run the test again:

$ rake
Run options: --seed 7548

# Running:

E

Finished in 0.000915s, 1092.3434 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NameError: uninitialized constant JuanitoMock::TestExtensions::StubTarget
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:6:in `allow'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Another error this time:

NameError: uninitialized constant JuanitoMock::TestExtensions::StubTarget
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:6:in `allow'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

Ruby is now complaining that it can't find the constant JuanitoMock::TestExtensions::StubTarget. Of course! That's because we haven't define StubTarget class yet, so let's define it:

module JuanitoMock
  class StubTarget
    def initialize(obj)
      @obj = obj
    end
  end

  module TestExtensions
    def allow(obj)
      StubTarget.new(obj)
    end
  end
end

class Minitest::Test
  include JuanitoMock::TestExtensions
end

For a start, we will just save the obj in an instance variable.

Now run the test again:

$ rake
Run options: --seed 25153

# Running:

E

Finished in 0.001059s, 944.4913 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `receive' for #<#<Class:0x007fe080b5d430>:0x007fe081057058>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

What? Another error. This doesn't seem like it's ending soon. But you should actually rejoice, because we now have a different error, and that means we are progressing!

NoMethodError: undefined method `receive' for #<#<Class:0x007fe080b5d430>:0x007fe081057058>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

This time it's ranting about another missing method receive. Hmm what about to? Why didn't it complain about a missing method to?

That's because Ruby always tries to evaluate the right-hand side first, and so it's going to process receive first before it gets to to. Dont' worry, you'll see an error for to later.

Let's define a receive method in TestExtensions module which accepts a message:

require "juanito_mock/version"

module JuanitoMock
  class StubTarget
    ...
  end

  module TestExtensions
    def allow(obj)
      ...
    end

    def receive(message)
      ExpectationDefinition.new(message)
    end
  end
end

As described in design section, receive will return a ExpectationDefinition instance.

Now run the test again:

$ rake
Run options: --seed 27383

# Running:

E

Finished in 0.001145s, 873.0986 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NameError: uninitialized constant JuanitoMock::TestExtensions::ExpectationDefinition
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:16:in `receive'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

You probably already expected it and now Ruby complains that it cannot find ExpectationDefinition:

NameError: uninitialized constant JuanitoMock::TestExtensions::ExpectationDefinition
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:16:in `receive'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

Let's go ahead and define it, keeping ExpectationDefinition simple, such that it only accepts an argument and stores it in an instance variable.

module JuanitoMock
  class StubTarget
    ...
  end

  class ExpectationDefinition
    def initialize(message)
      @message = message
    end
  end

  module TestExtensions
    ...
  end
end

Now run the test again:

$ rake
Run options: --seed 47423

# Running:

E

Finished in 0.001005s, 995.4657 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `and_return' for #<JuanitoMock::ExpectationDefinition:0x007fe072f6a798>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Now Ruby cannot find the and_return method
(poor Ruby, thanks for doing so much work for us 😢):

NoMethodError: undefined method `and_return' for #<JuanitoMock::ExpectationDefinition:0x007fe072f6a798>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

Looking at the error, it's actually telling us that it cannot find the and_return method on ExpectationDefinition, so let's define it there:

require "juanito_mock/version"

module JuanitoMock
  class StubTarget
    ...
  end

  class ExpectationDefinition
    def initialize(message)
      @message = message
    end

    def and_return(return_value)
      @return_value = return_value
      self
    end
  end

  module TestExtensions
    ...
  end
end

This new method and_return is interesting and contains the secret to enabling method chaining.

Do you know what it is?

Yes. The method is returning self!

def and_return(return_value)
  @return_value = return_value
  self
end

That's the magic to building a chaining interface for your objects! All you have to do is to build up objects and return self!

Now let's run our test again:

$ rake
Run options: --seed 11338

# Running:

E

Finished in 0.001084s, 922.9213 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `to' for #<JuanitoMock::StubTarget:0x007ff48a516590>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Yes! Now we see the error for undefined method to on StubTarget class, and so let's define the to method on StubTarget class according to our design:

allow(warehouse).to receive(:full?).and_return(true)
^^^^^^^^^^^^^^^^    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    StubTarget            ExpectationDefinition

where the to method accepts an ExpectationDefinition object as argument.

module JuanitoMock
  class StubTarget
    def initialize(obj)
      @obj = obj
    end

    def to(definition)
    end
  end

  class ExpectationDefinition
    ...
  end

  module TestExtensions
    ...
  end
end

Now let's run our test again:

$ rake
Run options: --seed 31564

# Running:

E

Finished in 0.001092s, 915.9027 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `full?' for #<Object:0x007f8fcc47dc28>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:11:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Reading our next failure, the error guides us to define a full? method on the object:

NoMethodError: undefined method `full?' for #<Object:0x007f8fcc47dc28>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:11:in `block (2 levels) in <top (required)>'

Let's use the aforementioned define_singleton_method magic to define the full? method, and which returns the expected value of true as specified in our test:

module JuanitoMock
  class StubTarget
    ...

    def to(definition)
      @obj.define_singleton_method definition.message do
        definition.return_value
      end
    end
  end

  class ExpectationDefinition
    ...
  end

  module TestExtensions
    ...
  end
end

Now run the tests again:

$ rake
Run options: --seed 14082

# Running:

E

Finished in 0.001091s, 916.4954 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `message' for #<JuanitoMock::ExpectationDefinition:0x007ff31d8ae220>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:10:in `to'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

This time Ruby cannot find message on ExpectationDefinition:

NoMethodError: undefined method `message' for #<JuanitoMock::ExpectationDefinition:0x007ff31d8ae220>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:10:in `to'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

Keeping it simple, we expose message and return_value in ExpectationDefinition class with attr_reader:

module JuanitoMock
  ...

  class ExpectationDefinition
    attr_reader :message, :return_value

    def initialize(message)
      @message = message
    end

    ...
  end

  ...
end

Now run this test again:

$ rake
Run options: --seed 46498

# Running:

.

Finished in 0.000975s, 1025.2078 runs/s, 1025.2078 assertions/s.

1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

Our first passing test!

allow(warehouse).to receive(:full?).and_return(true)

This line in the test is actually passing! Just with 42 lines of code in a relatively short amount of time!

Let's take a step back to see what we have done so far. Basically, we started to build our Mocking library by writing a test - a failing test. Then we write some code to error that was thrown, and some more code to fix the next error that was thrown and so on and so forth. And finally, through our persistence, we got the test to pass!

This practice of writing software is what we call Test Driven Development (TDD), where we go from red (failing test), to green (passing test) and moving on to refactor. This is a practice that a lot of software engineers embrace, and it's one which we have found immense benefits when doing it consistently.

The Edge of Mocking

Are we done already? Not quite!

In our current code, we defined the full?method on the object when the test starts, but we didn't do anything to reset our change after the test finishes, and that's actually not so good, because it might affect other tests. So, we should reset the state and unset the full? method that we have "stubbed".

Let's write another test for this:

  it "removes stubbed method after tests finished" do
    warehouse = Object.new

    allow(warehouse).to receive(:full?).and_return(true)

    JuanitoMock.reset

    assert_raises(NoMethodError) { warehouse.full? }
  end

I intentionally prefix each line with two spaces to make it copy-paste friendly, but I strongly encourage you to type on your own.

In the above test, we invoke JuanitoMock.reset to clear/undo all changes to the code, and we verify this by using assert_raises where we test that an exception is raised
when full? is invoked.

At this point, this is how your test file should look like:

require "test_helper"

describe JuanitoMock do
  it "allows an object to receive a message and returns a value" do
    warehouse = Object.new

    allow(warehouse).to receive(:full?).and_return(true)

    warehouse.full?.must_equal true
  end

  it "removes stubbed method after tests finished" do
    warehouse = Object.new

    allow(warehouse).to receive(:full?).and_return(true)

    JuanitoMock.reset

    assert_raises(NoMethodError) { warehouse.full? }
  end
end

Once again, we run the test to find out what to do next:

$ rake
Run options: --seed 30441

# Running:

.E

Finished in 0.001152s, 1736.7443 runs/s, 868.3721 assertions/s.

  1) Error:
JuanitoMock#test_0002_removes stubbed method after tests finished:
NoMethodError: undefined method `reset' for JuanitoMock:Module
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:17:in `block (2 levels) in <top (required)>'

2 runs, 1 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Oops. Did you expect that - undefined method reset for JuanitoMock:Module?

Let's write this method! Edit lib/juanito_mock.rb and add this module-level method:

module JuanitoMock
  ...

  module TestExtensions
    ...
  end

  def self.reset
  end
end

What do we do next? What should we write in the method? Run the test and let that help us!

$ rake
Run options: --seed 22585

# Running:

.F

Finished in 0.001207s, 1657.1930 runs/s, 1657.1930 assertions/s.

  1) Failure:
JuanitoMock#test_0002_removes stubbed method after tests finished [/Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:19]:
NoMethodError expected but nothing was raised.

2 runs, 2 assertions, 1 failures, 0 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

NoMethodError expected but nothing was raised.. Yup. That's what I expected, too.

How can we undefine the method full? that we have stubbed on the object? As we had defined the method full? in the object's singleton class, there is actually no reference to it and so we don't know how to undefine it, at least for now...

Let's park that for now, and do something else instead (which would help us later).

Let's improve the code!

We are going to make some changes to our code without losing the any of our current functionality.

Let's start by wrapping the define method step into a class, a delegate class and name it: Stubber. Put Stubber below StubTarget and above the ExpectationDefinition:

module JuanitoMock
  class StubTarget
    ...
  end

  class Stubber
    def initialize(obj)
      @obj = obj
    end

    def stub(definition)
    end
  end

  class ExpectationDefinition
    ...
  end
end

Then, move the implementation of StubTarget#to to Stubber#stub:

module JuanitoMock
  class StubTarget
    ...
  end

  class Stubber
    def initialize(obj)
      @obj = obj
    end

    def stub(definition)
      @obj.define_singleton_method definition.message do
        definition.return_value
      end
    end
  end

  class ExpectationDefinition
    ...
  end
end

In StubTarget#to, we delegate the job to Stubber#stub:

module JuanitoMock
  class StubTarget
    ...

    def to(definition)
      Stubber.new(@obj).stub(definition)
    end
  end

  ...
end

Nice refactoring! This is an essential step in the TDD practice, and what we just did was basically to improve our code without modifying the current feature set of our code. We can verify this by running our tests which would prove that the first test is green, while the second test is still red:

$ rake
Run options: --seed 23169

# Running:

.F

Finished in 0.001183s, 1691.2146 runs/s, 1691.2146 assertions/s.

  1) Failure:
JuanitoMock#test_0002_removes stubbed method after tests finished [/Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:19]:
NoMethodError expected but nothing was raised.

2 runs, 2 assertions, 1 failures, 0 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Let's get back to fixing the error.

Let's store what we stubbed in an array called @definitions, in Stubber#stub:

module JuanitoMock
  ...

  class Stubber
    def initialize(obj)
      @obj = obj
      @definitions = []
    end

    def stub(definition)
      @definitions << definition

      @obj.define_singleton_method definition.message do
        definition.return_value
      end
    end
  end

  ...
end

However, having the @definitions array is not enough because the Stubber instance in:

    def to(definition)
      Stubber.new(@obj).stub(definition)
    end

immediately goes out of scope and gets garbage collected, and so we still do not have a list of all methods that were stubbed.

Hence we need to be able to save the Stubber instance(s) by using a Stubber.for_object class-level method:

module JuanitoMock
  class StubTarget
    def initialize(obj)
      @obj = obj
    end

    def to(definition)
      Stubber.for_object(@obj).stub(definition)
    end
  end

  ...
end

Now run the test again:

$ rake
Run options: --seed 37100

# Running:

EE

Finished in 0.001317s, 1518.4864 runs/s, 0.0000 assertions/s.

  1) Error:
JuanitoMock#test_0002_removes stubbed method after tests finished:
NoMethodError: undefined method `for_object' for JuanitoMock::Stubber:Class
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:10:in `to'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:15:in `block (2 levels) in <top (required)>'


  2) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `for_object' for JuanitoMock::Stubber:Class
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:10:in `to'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:7:in `block (2 levels) in <top (required)>'

2 runs, 0 assertions, 0 failures, 2 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

The next error to fix is to define for_object on Stubber class:

NoMethodError: undefined method `for_object' for JuanitoMock::Stubber:Class
  /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:10:in `to'
  /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:7:in `block (2 levels)

This Stubber.for_object method is a custom initializer for the Stubber class that will not only create Stubber instances, but also store them in a lazily-initialized hash, with its object_id as key:

module JuanitoMock
  class Stubber
    def self.stubbers
      @stubbers ||= {}
    end

    def self.for_object(obj)
      stubbers[obj.__id__] ||= Stubber.new(obj)
    end

    ...
  end
end

But are we making progress for JuanitoMock.reset? Hmm.. Let's run the tests first.

$ rake
Run options: --seed 4701

# Running:

.F

Finished in 0.001117s, 1789.8854 runs/s, 1789.8854 assertions/s.

  1) Failure:
JuanitoMock#test_0002_removes stubbed method after tests finished [/Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:19]:
NoMethodError expected but nothing was raised.

2 runs, 2 assertions, 1 failures, 0 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

The failure is still the same as before, but we are actually making a progress.

Given that all the stubbed methods are now stored in the Stubber class, it would be great if we have one single method in Stubber that can help us. Thinking along that line of thought, let's have a Stubber.reset method that does exactly that, and then it would be trivial for JuanitoMock.reset to invoke it!

Let's try to implement the logic for Stubber.reset that we wish we have.

stubbers currently is a hash that looks like this:

{
  70173643198180 => #<Stubber instance>
}

It is a one-to-one object id mapping to a Stubber instance. We would first want each instance to unstub the method that we stub earlier. The intent is still similar, so each instance should have its own reset method that we can call. Also, the reset method should empty the hash after we are done with it.
Cool! Ruby has a clear method that we can use.

module JuanitoMock
  ...

  class Stubber
    ...

    def self.for_object(obj)
      ...
    end

    def self.reset
      stubbers.each_value(&:reset)
      stubbers.clear
    end

    ...
  end

  ...

  module TestExtensions
    ...
  end

  def self.reset
    Stubber.reset
  end
end

Run the tests again:

$ rake
Run options: --seed 11282

# Running:

.E

Finished in 0.001142s, 1751.6509 runs/s, 875.8255 assertions/s.

  1) Error:
JuanitoMock#test_0002_removes stubbed method after tests finished:
NoMethodError: undefined method `reset' for #<JuanitoMock::Stubber:0x007f9a85c7bf38>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:24:in `each_value'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:24:in `reset'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:66:in `reset'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:17:in `block (2 levels) in <top (required)>'

2 runs, 1 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Now we have an undefined method reset for #<JuanitoMock::Stubber:0x007f9a85c7bf38> - a Stubber instance:

JuanitoMock#test_0002_removes stubbed method after tests finished:
NoMethodError: undefined method `reset' for #<JuanitoMock::Stubber:0x007f9a85c7bf38>

Let's implement Stubber#reset. In Stubber#reset, what we need to do is to undefine/unstub the method we have defined/stubbed earlier.

In Ruby, we can use remove_method with some class_eval craziness to achieve this:

module JuanitoMock
  ...

  class Stubber
    ...

    def stub(definition)
      ...
    end

    def reset
      @definitions.each do |definition|
        @obj.singleton_class.class_eval do
          remove_method(definition.message) if method_defined?(definition.message)
        end
      end
    end
  end

  ...
end

We avoid the NoMethodError exception by checking method_defined? on definition.message.

Now if you are brave enough to run the tests:

$ rake
Run options: --seed 55448

# Running:

..

Finished in 0.001233s, 1622.4943 runs/s, 1622.4943 assertions/s.

2 runs, 2 assertions, 0 failures, 0 errors, 0 skips

You shall see all our tests passed! All green! Yay!!!

All tests passed, old sport! Can we live happily ever after now? Hmm...

Blindly Removing Methods

Till now, we have covered the cases of stubbing and unstubbing. But there's actually a third case to consider!

What if, at the very beginning, there was already a full? method defined? We would have "killed" or "replaced" the original method unknowingly.

Let's write another test to describe this case:

  it "preserves methods that originally existed" do
    warehouse = Object.new
    def warehouse.full?; false; end # defining methods on Ruby singleton class

    allow(warehouse).to receive(:full?).and_return(true)

    JuanitoMock.reset

    warehouse.full?.must_equal false
  end

Run the tests:

$ rake
Run options: --seed 4474

# Running:

.E.

Finished in 0.001266s, 2369.2790 runs/s, 1579.5193 assertions/s.

  1) Error:
JuanitoMock#test_0003_preserves methods that are originally existed:
NoMethodError: undefined method `full?' for #<Object:0x007fcdcd4d3b70>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:29:in `block (2 levels) in <top (required)>'

3 runs, 2 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

We have a failure on our new test!

What happened was that our stub allow(warehouse).to receive(:full?).and_return(true) replaced the original method, and when we called JuanitoMock.reset, it only removed the stub but didn't bring back the original implementation for full?.

Hence the NoMethodError exception is expected, because the method's basically gone!

This is not ok. Let's fix that. But first let's take a look at Stubber#stub method:

class Stubber
  ...

  def stub(definition)
    @definitions << definition

    # preserve original method if already exists

    @obj.define_singleton_method definition.message do
      definition.return_value
    end
  end

  ...
end

In our current implementation of Stubber#stub, we didn't check if the object already has the method or not and we just simply (re)defined the singleton method.

We should preserve the original method if it already exists like so:

  class Stubber
    ...

    def stub(definition)
      @definitions << definition

      if @obj.singleton_class.method_defined?(definition.message)
        @preserved_methods <<
          @obj.singleton_class.instance_method(definition.message)
      end

      @obj.define_singleton_method definition.message do
        definition.return_value
      end
    end

    ...
  end

Let's walk through what we just did:

@obj.singleton_class.instance_method(definition.message)

The magic comes from the use of Module#instance_method which will return a method object of given name from the singleton class.

Think of this method object as a proc or lambda which we then we store in a @preserved_methods array:

  class Stubber
    ...

    def initialize(obj)
      @obj = obj
      @definitions = []
      @preserved_methods = []
    end

    ...
  end

Preserving the orignal method is only one part of the solution.

When we do a Stubber#reset, we actually want to reinstate and redefine these saved preserved methods:

  class Stubber
    ...

    def reset
      ...

      @preserved_methods.reverse_each do |method|
        @obj.define_singleton_method(method.name, method)
      end
    end
  end

We use reverse_each here because we need to preserve the original order of the methods. You can write a test here too to see the importance of using reverse_each but we'll leave it as an exercise!

P.S. Did you know reverse_each is more efficient than reverse.each?

In Stubber#stub, we used obj.define_singleton_method with a block, but it also pairs really well with method objects that we are dealing with in the @preserved_methods array.

Every method object Method#instance_method has a Method#name method that returns the name of the method. We can simply redefine the method by calling define_singleton_method with the method name and the method object itself.

Run the tests again and we should have three passing tests:

$ rake
Run options: --seed 63328

# Running:

...

Finished in 0.001223s, 2453.9275 runs/s, 2453.9275 assertions/s.

3 runs, 3 assertions, 0 failures, 0 errors, 0 skips

This also means we have successfully restored the original methods after the tests!

Congrats on getting so far, but we are not quite done. By now we have only implemented stub (and unstub), and next we are going to implement mock - which is an expectation that a message will be received.

To Mock a Mockingbird

Let's start with a new failing test as usual:

  it "expects that a message will be received" do
    warehouse = Object.new

    assume(warehouse).to receive(:empty)

    # warehouse.empty not called!

    assert_raises(JuanitoMock::ExpectationNotSatisfied) do
      JuanitoMock.reset
    end
  end

In our test, assume(warehouse).to receive(:empty) expects that warehouse.empty will be invoked. However we are not actually going to call the empty method and so, we assert that a custom exception JuanitoMock::ExpectationNotSatisfied will be raised when we call JuanitoMock.reset which loops and verfies each expectation.

Let's run the test:

$ rake
Run options: --seed 30442

# Running:

..E.

Finished in 0.001308s, 3058.4267 runs/s, 2293.8200 assertions/s.

  1) Error:
JuanitoMock#test_0004_expects that a message will be received:
NoMethodError: undefined method `assume' for #<#<Class:0x007facec071a20>:0x007facecbea5a0>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:35:in `block (2 levels) in <top (required)>'

4 runs, 3 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

The first thing we see is:

NoMethodError: undefined method `assume' for #<#<Class:0x007facec071a20>:0x007facecbea5a0>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:35:in `block (2 levels) in <top (required)>'

We have not define assume in our TestExtensions module, hence the error message. Let's do that! (TestExtensions should be at the bottom of lib/juanito_mock.rb):

module JuanitoMock
  ...

  module TestExtensions
    def allow(obj)
      ...
    end

    def assume(obj)
    end

    def receive(message)
      ...
    end
  end

  def self.reset
    ...
  end
end

Instead of an instance of StubTarget, let's return an instance of ExpectationTarget:

module JuanitoMock
  ...

  module TestExtensions
    ...

    def assume(obj)
      ExpectationTarget.new(obj)
    end

    ...
  end

  def self.reset
    ...
  end
end

Now if you run the tests, it will complain that ExpectationTarget is undefined:

$ rake
Run options: --seed 58985

# Running:

...E

Finished in 0.001235s, 3237.5687 runs/s, 2428.1766 assertions/s.

  1) Error:
JuanitoMock#test_0004_expects that a message will be received:
NameError: uninitialized constant JuanitoMock::TestExtensions::ExpectationTarget
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:79:in `assume'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:35:in `block (2 levels) in <top (required)>'

4 runs, 3 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

We use ExpectationTarget in assume because it's a target of a mock expectation (vs. a stub). However, ExpectationTarget is actully very similar to a StubTarget (a specialized form of StubTarget), in that both stubs the original method implementation of an object, but ExpectationTarget does a little something extra by checking that the message has been called.

allow(object).to receive(:message)
assume(object).to receive(:message)

Hence we can make ExpectationTarget a subclass of StubTarget, and let to method in ExpectationTarget inherit the implementation of to method in StubTarget by using super. Then we also store the definition object to a not-yet-exist JuanitoMock.expectations array, so that we can use that to perform our expectation checks later:

module JuanitoMock
  class StubTarget
    ...
  end

  class ExpectationTarget < StubTarget
    def to(definition)
      super
      JuanitoMock.expectations << definition
    end
  end
end

Now run the tests again:

$ rake
Run options: --seed 53163

# Running:

...E

Finished in 0.001286s, 3109.3585 runs/s, 2332.0189 assertions/s.

  1) Error:
JuanitoMock#test_0004_expects that a message will be received:
NoMethodError: undefined method `expectations' for JuanitoMock:Module
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:17:in `to'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:35:in `block (2 levels) in <top (required)>'

4 runs, 3 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

You know the drill. Let's initialize the expectations array, lazily:

module JuanitoMock
  ...

  module TestExtensions
    ...
  end

  def self.reset
    Stubber.reset
  end

  def self.expectations
    @expectations ||= []
  end
end

Run the tests once more and make a little bit more progress:

$ rake
Run options: --seed 51829

# Running:

.E..

Finished in 0.001005s, 3980.0243 runs/s, 2985.0182 assertions/s.

  1) Error:
JuanitoMock#test_0004_expects that a message will be received:
NameError: uninitialized constant JuanitoMock::ExpectationNotSatisfied
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:39:in `block (2 levels) in <top (required)>'

4 runs, 3 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Where's the class JuanitoMock::ExpectationNotSatisfied? Oops we don't have that yet, so let's fix it:

module JuanitoMock
  ExpectationNotSatisfied = Class.new(StandardError)

  class StubTarget
    ...
  end

  ...
end

Define a simple exception class and run the tests again. You'll see that JuanitoMock::ExpectationNotSatisfied expected but nothing was raised.:

$ rake
Run options: --seed 27046

# Running:

...F

Finished in 0.001435s, 2788.1462 runs/s, 2788.1462 assertions/s.

  1) Failure:
JuanitoMock#test_0004_expects that a message will be received [/Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:39]:
JuanitoMock::ExpectationNotSatisfied expected but nothing was raised.

4 runs, 4 assertions, 1 failures, 0 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

That's expected. We merely created the ExpectationTarget and ExpectationNotSatisfied classes, and we have not added anything new to the Stubber.reset method, so it's right that the new test is failing.

What should Stubber.reset do that would make our test pass? Hmm.. Stubber.reset should be checking that all of our expectations are verified, and would raise an error if any of the expectations failed. Why don't we add a verify method to each Stubber instance that would do the checking?

module JuanitoMock
  ...

  module TestExtensions
    ...
  end

  def self.reset
    expectations.each(&:verify)
    Stubber.reset
  end

  def self.expectations
    @expectations ||= []
  end
end

This works, but if an exceptation is raised when verify fails, then Stubber.reset would not actually be executed because the exception would have broke the control flow.

We want to make sure that Stubber.reset is called even if any expectation raised an exception, and we also want to clear @expectations too so that weird things won't happen. Ruby's ensure is here to help:

module JuanitoMock
  ...

  module TestExtensions
    ...
  end

  def self.reset
    expectations.each(&:verify)
  ensure
    expectations.clear
    Stubber.reset
  end

  ...
end

Run the tests again:

$ rake
Run options: --seed 12211

# Running:

...F

Finished in 0.001460s, 2738.9588 runs/s, 2738.9588 assertions/s.

  1) Failure:
JuanitoMock#test_0004_expects that a message will be received [/Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:39]:
[JuanitoMock::ExpectationNotSatisfied] exception expected, not
Class: <NoMethodError>
Message: <"undefined method `verify' for #<JuanitoMock::ExpectationDefinition:0x007f89bb4b9640>">
---Backtrace---
/Users/Juan/null/juanito_mock/lib/juanito_mock.rb:97:in `each'
/Users/Juan/null/juanito_mock/lib/juanito_mock.rb:97:in `reset'
/Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:40:in `block (3 levels) in <top (required)>'
---------------

4 runs, 4 assertions, 1 failures, 0 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Getting there! We have an undefined method verify on ExpectationDefinition. Let's do the simplest thing to make the test pass! We'll define the verify method and just raise ExpectationNotSatisfied:

module JuanitoMock
  ...

  class ExpectationDefinition
    ...

    def and_return(return_value)
      @return_value = return_value
      self
    end

    def verify
      raise ExpectationNotSatisfied
    end
  end

  ...
end

Run the tests! All green!

$ rake
Run options: --seed 22996

# Running:

....

Finished in 0.001272s, 3143.7915 runs/s, 3143.7915 assertions/s.

4 runs, 4 assertions, 0 failures, 0 errors, 0 skips

But this is clearly not right even though we have all passing tests. We have a gap in our testing and we'll expose that gap by writing a new test:

  it "does not raise an error if expectations are satisfied" do
    warehouse = Object.new

    assume(warehouse).to receive(:empty)

    warehouse.empty

    JuanitoMock.reset # assert nothing raised!
  end

Now run the tests again:

$ rake
Run options: --seed 46019

# Running:

E....

Finished in 0.001292s, 3870.3166 runs/s, 3096.2532 assertions/s.

  1) Error:
JuanitoMock#test_0005_does not raise an error if expectations are satisfied:
JuanitoMock::ExpectationNotSatisfied: JuanitoMock::ExpectationNotSatisfied
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:82:in `verify'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:101:in `each'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:101:in `reset'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:51:in `block (2 levels) in <top (required)>'

5 runs, 4 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

The new test is failing now because verify always raises an exception! That's our cue to implement the actual logic for the verify method which checks if a method has been invoked.

Again, a simple way to solve this would be to use an invocation count as verification, like so:

module JuanitoMock
  ...

  class ExpectationDefinition
    def initialize(message)
      @message = message
      @invocation_count = 0
    end

    ...

    def verify
      if @invocation_count != 1
        raise ExpectationNotSatisfied
      end
    end
  end

  ...
end

But we don't really have a way to increment invocation count. Maybe...

Let's look at the following in Stubber#stub:

@obj.define_singleton_method definition.message do
  definition.return_value
end

When we define the singleton method, we are just simply returning the value via definition.return_value. Instead, let's modify it to look like:

@obj.define_singleton_method definition.message do
  definition.call
end

Invoking a call method is a standard practice if you want an object to act like a callable piece of code, like a proc or lambda (which also has the call method).

Let's run the tests:

$ rake
Run options: --seed 56524

# Running:

.E..E

Finished in 0.001311s, 3815.1804 runs/s, 2289.1082 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `call' for #<JuanitoMock::ExpectationDefinition:0x007fa065d1a030>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:52:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'


  2) Error:
JuanitoMock#test_0005_does not raise an error if expectations are satisfied:
NoMethodError: undefined method `call' for #<JuanitoMock::ExpectationDefinition:0x007fa065d18b40>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:52:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:49:in `block (2 levels) in <top (required)>'

5 runs, 3 assertions, 0 failures, 2 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Let's add the method call for ExpectationDefinition:

module JuanitoMock
  ...

  class ExpectationDefinition
    ...

    def call
      @invocation_count += 1
      @return_value
    end

    def verify
      ...
    end
  end

  ...
end

The call method will still return the return_value (as was happening earlier with definition.return_value), but at the same time, it also increases the @invocation_count.

Now run the tests again, and we would be all green again!

$ rake
Run options: --seed 47647

# Running:

.....

Finished in 0.001300s, 3846.9144 runs/s, 3077.5315 assertions/s.

5 runs, 4 assertions, 0 failures, 0 errors, 0 skips

Great! We now have basic stub and mock functionality for JuanitoMock. But we don't have yet the ability to pass (and expect) arguments to stubs.

Let's write a test for that:

  it "allows object to receive messages with arguments" do
    warehouse = Object.new

    allow(warehouse).to receive(:include?).with(1234).and_return(true)
    allow(warehouse).to receive(:include?).with(9876).and_return(false)

    warehouse.include?(1234).must_equal true
    warehouse.include?(9876).must_equal false
  end

Now run the tests to see what should we do next:

$ rake
Run options: --seed 17857

# Running:

E.....

Finished in 0.001458s, 4116.0535 runs/s, 2744.0357 assertions/s.

  1) Error:
JuanitoMock#test_0006_allows object to receive messages with arguments:
NoMethodError: undefined method `with' for #<JuanitoMock::ExpectationDefinition:0x007fb1f2d010f0>
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:57:in `block (2 levels) in <top (required)>'

6 runs, 4 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

We don't have the with on ExpectationDefinition. Let's do it:

module JuanitoMock
  ...

  class ExpectationDefinition
    def and_return
      ...
    end

    def with(*arguments)
      @arguments = arguments
      self
    end

    def call
      ...
    end

    ...
  end

  ...
end

The with method will accept an array of arguments, made possible using the splat operator (*), and we also return self to make it chainable.

Run the tests again:

$ rake
Run options: --seed 16039

# Running:

...E..

Finished in 0.001207s, 4969.8536 runs/s, 3313.2358 assertions/s.

  1) Error:
JuanitoMock#test_0006_allows object to receive messages with arguments:
ArgumentError: wrong number of arguments (1 for 0)
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:51:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:60:in `block (2 levels) in <top (required)>'

6 runs, 4 assertions, 0 failures, 1 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Now we see ArgumentError: wrong number of arguments (1 for 0).

Let's decrypt this error message.

What it's saying is that you passed in 1 argument, but the method defined only requires 0 arguments.

Luckily there is also a line number telling us where things went wrong:

lib/juanito_mock.rb:51:in `block in stub'

Line 51 or Stubber#stub should be:

@obj.define_singleton_method definition.message do
  definition.call
end

Let's allow the define_singleton_method block to accept splat arguments as well:

@obj.define_singleton_method definition.message do |*arguments|
  definition.call
end

Run the tests again:

$ rake
Run options: --seed 3190

# Running:

..F...

Finished in 0.001697s, 3536.4931 runs/s, 2947.0775 assertions/s.

  1) Failure:
JuanitoMock#test_0006_allows object to receive messages with arguments [/Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:60]:
Expected: true
  Actual: false

6 runs, 5 assertions, 1 failures, 0 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

And we now have a failure on our test:

  warehouse.include?(1234).must_equal true
  warehouse.include?(9876).must_equal false
end

Let's look at the test again:

it "allows object to receive messages with arguments" do
  warehouse = Object.new

  allow(warehouse).to receive(:include?).with(1234).and_return(true)
  allow(warehouse).to receive(:include?).with(9876).and_return(false)

  warehouse.include?(1234).must_equal true
  warehouse.include?(9876).must_equal false
end

warehouse.include?(1234) is returning false (and failing the test). That's because we have yet to do any matching on the stub argument and so the last stub

allow(warehouse).to receive(:include?).with(9876).and_return(false)

is the one that's being returned, no matter what arguments are used.

Why is the last stub returned? Remember when we defined the singleton method:

@obj.define_singleton_method definition.message do |*arguments|
  definition.call
end

We only invoked a definition via definition.call, but we didn't actually invoke the right definition.

Similar to our reset method, we should (reverse) search and find the definition that matches the method name and arguments:

@obj.define_singleton_method definition.message do |*arguments|
  @definitions
    .reverse
    .find { |definition| definition.matches(definition.message, *arguments) }
    .call
end

Run the tests again:

$ rake
Run options: --seed 61311

# Running:

E.EEE.

Finished in 0.001315s, 4563.6538 runs/s, 1521.2179 assertions/s.

  1) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `reverse' for nil:NilClass
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:54:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'


  2) Error:
JuanitoMock#test_0005_does not raise an error if expectations are satisfied:
NoMethodError: undefined method `reverse' for nil:NilClass
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:54:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:49:in `block (2 levels) in <top (required)>'


  3) Error:
JuanitoMock#test_0003_preserves methods that are originally existed:
JuanitoMock::ExpectationNotSatisfied: JuanitoMock::ExpectationNotSatisfied
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:97:in `verify'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:117:in `each'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:117:in `reset'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:27:in `block (2 levels) in <top (required)>'


  4) Error:
JuanitoMock#test_0006_allows object to receive messages with arguments:
NoMethodError: undefined method `reverse' for nil:NilClass
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:54:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:60:in `block (2 levels) in <top (required)>'

6 runs, 2 assertions, 0 failures, 4 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

Yikes. 4 tests failed! Let's take a look at the last one:

JuanitoMock#test_0006_allows object to receive messages with arguments:
NoMethodError: undefined method `reverse' for nil:NilClass
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:54:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:60:in `block (2 levels) in <top (required)>'

Hmm. Let's look at our implementation again:

@obj.define_singleton_method definition.message do |*arguments|
  @definitions
    .reverse
    .find { |definition| definition.matches(definition.message, *arguments) }
    .call
end

Why is @definitions nil? That's because self has changed, in a singleton method block like this:

@obj.define_singleton_method definition.message do |*arguments|
  ...
end

And because instance variables (@definitions) are looked up on self (which is now @obj and not the outer instance), @definitions is something different (and unintialized) in the block. We call this a closure.

An easy fix would be to create a temporary variable:

module JuanitoMock
  ...

  class Stubber
    ...

    def stub(definition)
      ...

      definitions = @definitions
      @obj.define_singleton_method definition.message do |*arguments|
        definitions
          .reverse
          .find { |definition| definition.matches(definition.message, *arguments) }
          .call
      end
    end

    def reset
      ...
    end
  end

  ...
end

Run the tests again:

$ rake
Run options: --seed 52635

# Running:

..EEEE

Finished in 0.001867s, 3214.3833 runs/s, 1071.4611 assertions/s.

  1) Error:
JuanitoMock#test_0006_allows object to receive messages with arguments:
NoMethodError: undefined method `matches' for #<JuanitoMock::ExpectationDefinition:0x007ff542c9bf00>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `block (2 levels) in stub'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `each'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `find'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:60:in `block (2 levels) in <top (required)>'


  2) Error:
JuanitoMock#test_0005_does not raise an error if expectations are satisfied:
NoMethodError: undefined method `matches' for #<JuanitoMock::ExpectationDefinition:0x007ff542c9b7d0>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `block (2 levels) in stub'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `each'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `find'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:49:in `block (2 levels) in <top (required)>'


  3) Error:
JuanitoMock#test_0003_preserves methods that are originally existed:
JuanitoMock::ExpectationNotSatisfied: JuanitoMock::ExpectationNotSatisfied
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:98:in `verify'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:118:in `each'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:118:in `reset'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:27:in `block (2 levels) in <top (required)>'


  4) Error:
JuanitoMock#test_0001_allows an object to receive a message and returns a value:
NoMethodError: undefined method `matches' for #<JuanitoMock::ExpectationDefinition:0x007ff542c9ad30>
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `block (2 levels) in stub'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `each'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `find'
    /Users/Juan/null/juanito_mock/lib/juanito_mock.rb:55:in `block in stub'
    /Users/Juan/null/juanito_mock/test/juanito_mock_test.rb:9:in `block (2 levels) in <top (required)>'

6 runs, 2 assertions, 0 failures, 4 errors, 0 skips

rake aborted!
Command failed with status (1): [ruby -I"lib:test:lib"  "/Users/Juan/.rubies/ruby-2.2.2/lib/ruby/2.2.0/rake/rake_test_loader.rb" "test/juanito_mock_test.rb" ]

Tasks: TOP => default => test
(See full trace by running task with --trace)

We got rid of the nil error, and now we have an undefined method matches in ExpectationDefinition!

This is the final step, I promise:

  class ExpectationDefinition
    ...

    def with(*arguments)
      ...
    end

    def matches(message, *arguments)
      message == @message &&
        (@arguments.nil?) || arguments == @arguments
    end

    def call
      ...
    end

    ...
  end

Again, we'll run all the tests:

$ rake
Run options: --seed 14495

# Running:

......

Finished in 0.001514s, 3963.4020 runs/s, 3963.4020 assertions/s.

6 runs, 6 assertions, 0 failures, 0 errors, 0 skips

Now we have ALL OUR TESTS PASSING!

C O N G R A T U L A T I O N S

You've got a basic mocking library!

This library is pretty good now, except with some caveats...

with(...) and calling it with different arguments raises NoMethodError
define_singleton_method and singleton_class are on Object and so stubbing on BasicObject is not supported
private methods are not preserved
reset method should be invoked automatically at the end of each test (teardown)

Luckily, RSpec already addressed these and more, so you can just use rspec-mocks.