Spy

Spy is a lightweight stubbing framework with support for method spies, constant stubs, and object mocks.

Spy was designed for 1.9.3+.

Spy features that were completed were tested against the rspec-mocks tests so it covers all cases that rspec-mocks does.

Inspired by the spy api of the jasmine javascript testing framework.

Why use this instead of rspec-mocks, mocha, or etc

Spy will raise error when you try to stub/spy a method that doesn't exist
- when you change your method name your unit tests will break
- no more fantasy tests
Spy arity matches original method
- Your tests will raise an error if you use the wrong arity
Spy visibility matches original method
- Your tests will raise an error if you try to call the method incorrectly
Simple call log api
- easier to read tests
- use ruby to test ruby instead of a dsl
no expectations
- really who thought that was a good idea?
absolutely no polution of global object space
no polution of instance variables for stubbed objects

Fail faster, code faster.

Why not to use this

mocking null objects is not supported(yet)
no argument matchers for Spy::Subroutine#has_been_called_with
cannot watch all calls to an object to check order in which they are called
cannot transfer nested constants when stubbing a constant
- i don't think anybody uses this anyway
- nobody on github does
#with is not supported
- you can usually just check the call logs.
- if you do need to use this. It is probably a code smell. You either need to abstract your method more or add separate tests.
you want to use dumb double, Spy has smart mocks, they are better
you use mock_model and stub_model (I want to impliment this soon)

Installation

Add this line to your application's Gemfile:

gem 'spy'

And then execute:

$ bundle

Or install it yourself as:

$ gem install spy

Usage

Method Stubs

A method stub overrides a pre-existing method and records all calls to specified method. You can set the spy to return either the original method or your own custom implementation.

Spy support 2 different ways of spying an existing method on an object.

Spy.on(book, title: "East of Eden")
Spy.on(book, :title).and_return("East of Eden")
Spy.on(book, :title).and_return { "East of Eden" }

book.title  #=> "East of Eden"

Spy will raise an error if you try to stub on a method that doesn't exist. You can force the creation of a stub on method that didn't exist but it really isn't suggested.

Spy::Subroutine.new(book, :flamethrower).hook(force:true).and_return("burnninante")

You can also stub instance methods of Classes and Modules. This is equivalent to rspec-mock's Module#any_instance

Spy.on_instance_method(Book, :title).and_return("Cannery Row")

Book.new(title: "Siddhartha").title   #=> "Cannery Row"
Book.new(title: "The Big Cheese").title   #=> "Cannery Row"

Test Mocks

A test mock is an object that quacks like a given class but will raise an error when the method is not stubbed. Spy will not let you stub a method that wasn't on the mocked class. You can spy on the classes and call through to the original method.

book = Spy.mock(Book) # Must be a class
Spy.on(book, first_name: "Neil", last_name: "Gaiman")
Spy.on(book, :author).and_call_through
book.author #=> "Neil Gaiman"

book.responds_to? :title #=> true
book.title #=> Spy::NeverHookedError: 'title' was never hooked on mock spy.

To stub methods during instantiation just add arguments.

book = Spy.mock(Book, :first_name, author: "Neil Gaiman")

Arbitrary Handling

If you need to have a custom method based in the method inputs just send a block to #and_return

Spy.on(book, :read_page).and_return do |page, &block|
  block.call
  "awesome " * page
end

An error will raise if the arity of the block is larger than the arity of the original method. However this can be overidden with the force argument.

Spy.on(book, :read_page).and_return(force: true) do |a, b, c, d|
end

Method Spies

When you stub a method it returns a spy. A spy records what calls have been made to a given method.

validator = Spy.mock(Validator)
validate_spy = Spy.on(validator, :validate)
validate_spy.has_been_called? #=> false

validator.validate("01234")   #=> nil
validate_spy.has_been_called? #=> true
validate_spy.has_been_called_with?("01234") #=> true

You can also retrieve a method spy on demand

Spy.get(validator, :validate)

Calling through

If you just want to make sure if a method is called and not override the output you can just use the #and_call_through method

Spy.on(book, :read_page).and_call_through

By if the original method never existed it will call #method_missing on the spied object.

Call Logs

When a spy is called on it records a call log. A call log contains the object it was called on, the arguments and block that were sent to method and what it returned.

read_page_spy = Spy.on(book, read_page: "hello world")
book.read_page(5) { "this is a block" }
book.read_page(3)
book.read_page(7)
read_page_spy.calls.size #=> 3
first_call = read_page_spy.calls.first
first_call.object #=> book
first_call.args   #=> [5]
first_call.block  #=> Proc.new { "this is a block" }
first_call.result #=> "hello world"
first_call.called_from #=> "file_name.rb:line_number"

Test Framework Integration

MiniTest/TestUnit

in your test_helper.rb add this line after you include your framework

require 'spy/integration'

In your test file

  def test_title
    book = Book.new
    title_spy = Spy.on(book, title)
    book.title
    book.title

    assert_received book, :title

    assert title_spy.has_been_called?
    assert_equal 2, title_spy.calls.count
  end

Rspec

In spec_helper.rb

require "rspec/autorun"
require "spy/integration"
RSpec.configure do |c|
  c.mock_with Spy::RspecAdapter
end

In your test

describe Book do
  it "title can be called" do
    book = book.new
    page_spy = Spy.on(book, page)
    book.page(1)
    book.page(2)

    expect(book).to have_received(:page)
    expect(book).to have_received(:page).with(1)
    expect(book).to have_received(:page).with(2)

    expect(page_spy).to have_been_called
    expect(page_spy.calls.count).to eq(2)
  end
end

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

berkcaputcu/spy

Spy