module Spectator::Stubbable

Overview

Mix-in for mocks and doubles providing method stubs.

Macros in this module can override existing methods. Stubbed methods will look for stubs to evaluate in place of their original functionality. The primary macro of interest is #stub. The macros are intended to be called from within the type being stubbed.

Types including this module must define #_spectator_find_stub and #_spectator_stubbed_name. These are internal, reserved method names by Spectator, hence the _spectator prefix. These methods can't (and shouldn't) be stubbed.

Direct including types

Defined in:

spectator/mocks/stubbable.cr

Instance Method Summary

Macro Summary

Instance Method Detail

abstract def _spectator_abstract_stub_fallback(call : MethodCall, type) #

Method called when a stub isn't found.

This is similar to #_spectator_stub_fallback, but called when the original (un-stubbed) method isn't available. The received message is captured in call. The expected return type is provided by type. The stubbed method returns the value returned by this method. This method can also raise an error if it's impossible to return something.


[View source]
abstract def _spectator_abstract_stub_fallback(call : MethodCall) #

Method called when a stub isn't found.

This is similar to #_spectator_stub_fallback, but called when the original (un-stubbed) method isn't available. The received message is captured in call. The stubbed method returns the value returned by this method. This method can also raise an error if it's impossible to return something.


[View source]
abstract def _spectator_calls #

Retrieves all previously saved calls.


[View source]
abstract def _spectator_clear_calls : Nil #

Clears all previously saved calls.


[View source]
abstract def _spectator_clear_stubs : Nil #

Clears all previously defined stubs.


[View source]
abstract def _spectator_define_stub(stub : Stub) : Nil #

Defines a stub to change the behavior of a method.


[View source]
abstract def _spectator_find_stub(call : MethodCall) : Stub? #

Attempts to find a stub that satisfies a method call.

Returns a stub that matches the method call or nil if no stubs satisfy it.


[View source]
abstract def _spectator_record_call(call : MethodCall) : Nil #

Saves a call that was made to a stubbed method.


[View source]
def _spectator_reset : Nil #

Clears all previously defined calls and stubs.


[View source]
abstract def _spectator_stub_fallback(call : MethodCall, type, &) #

Method called when a stub isn't found.

The received message is captured in call. The expected return type is provided by type. Yield to call the original method's implementation. The stubbed method returns the value returned by this method. This method can also raise an error if it's impossible to return something.


[View source]
abstract def _spectator_stub_fallback(call : MethodCall, &) #

Method called when a stub isn't found.

The received message is captured in call. Yield to call the original method's implementation. The stubbed method returns the value returned by this method. This method can also raise an error if it's impossible to return something.


[View source]
abstract def _spectator_stub_for_method?(method : Symbol) : Bool #

Utility method that looks for stubs for methods with the name specified.


[View source]
abstract def _spectator_stubbed_name : String #

Utility method returning the stubbed type's name formatted for user output.


[View source]

Macro Detail

macro stub(method) #

Redefines a method to require stubs.

The method can be a Def. That is, a normal looking method definition should follow the stub keyword.

stub def stubbed_method
  "foobar"
end

If the method is abstract, then a stub must be provided otherwise attempts to call the method will raise UnexpectedMessage.

stub abstract def stubbed_method

A Call can also be specified. In this case all methods in the stubbed type and its ancestors that match the call's signature are stubbed.

stub stubbed_method(arg)

The method being stubbed doesn't need to exist yet. Stubbed methods will call #_spectator_find_stub with the method call information. If no stub is found, then #_spectator_stub_fallback or #_spectator_abstract_stub_fallback is called.


[View source]