Package: groovy.mock.interceptor

## [Groovy] Class StubFor

- groovy.mock.interceptor.StubFor

-     class StubFor
      extends Object

  StubFor supports (typically unit) testing of classes in isolation by allowing a loosely-ordered expectation of the behavior of collaborators to be defined. A typical test scenario involves a class under test (CUT) and one or more collaborators. In such a scenario it is often desirable to just test the business logic of the CUT. One strategy for doing that is to replace the collaborator instances with simplified stub objects to help isolate out the logic in the CUT. StubFor allows such stubs to be created using meta-programming. The desired behavior of collaborators is defined as a behavior specification. The behavior can be checked by the user using verify(). With StubFor, a stub's expectation is sequence independent and use of verify() is left to the user. Typical usage is as follows: <

       import groovy.mock.interceptor.StubFor

       class Person {
         String first, last
       }

       class Family {
         Person mother, father
         def nameOfFather() { "$father.first $father.last" }
       }

       def stub = new StubFor(Person)
       stub.demand.with {
         getLast{ 'name' }
         getFirst{ 'dummy' }
       }
       stub.use {
         def john = new Person(first:'John', last:'Smith')
         def f = new Family(father:john)
         assert f.nameOfFather() == 'dummy name'
       }
       stub.expect.verify()

  Here, `Family` is our class under test and `Person` is the collaborator. We are using normal Groovy property semantics here; hence the statement `father.first` causes a call to `father.getFirst()` to occur. For a complete list of features, see: MockFor.

- - ### Properties Summary

    Properties
    Type | Name and description
    --- | ---
    `Class` | `clazz` Collaborator class being stubbed.
    `Demand` | `demand` Recorded demand specification for the stubbed collaborator.
    `Object` | `expect` Sequence-independent expectation enforcing the recorded demands.
    `Ignore` | `ignore` Helper supporting the `ignore.methodName(...)` shorthand.
    `Map` | `instanceExpectations` Per-instance expectations created for proxy-style usage.
    `MockProxyMetaClass` | `proxy` Proxy meta class used to intercept collaborator interactions.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `StubFor(Class clazz, boolean interceptConstruction)` Creates a stub definition for the supplied collaborator class.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `Object` | `ignore(Object filter, Closure filterBehavior)` Allows particular method calls to be ignored and not treated as part of the required behavior specification.
    `` | `GroovyObject` | `makeProxyInstance(Object args, boolean isDelegate)` Creates a proxy-backed instance and wires it to a dedicated loose expectation.
    `` | `GroovyObject` | `proxyDelegateInstance(Object args)` Allows a more traditional instance-style stubbing paradigm.
    `` | `GroovyObject` | `proxyInstance(Object args)` Allows a more traditional instance-style stubbing paradigm.
    `` | `void` | `use(Closure closure)` See: MockFor#use(Closure)
    `` | `void` | `use(GroovyObject obj, Closure closure)` Applies this stub to a single Groovy object for the duration of the supplied closure.
    `` | `void` | `verify(GroovyObject obj)` For manual verification
    `` | `void` | `verify()` Convenience method

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Property Detail

    - #### Class clazz

      Collaborator class being stubbed.

    - #### Demand demand

      Recorded demand specification for the stubbed collaborator.

    - #### Object expect

      Sequence-independent expectation enforcing the recorded demands.

    - #### Ignore ignore

      Helper supporting the `ignore.methodName(...)` shorthand.

    - #### Map instanceExpectations

      Per-instance expectations created for proxy-style usage.

    - #### MockProxyMetaClass proxy

      Proxy meta class used to intercept collaborator interactions.

  - ### Constructor Detail

    - #### StubFor(Class clazz, boolean interceptConstruction)

      Creates a stub definition for the supplied collaborator class.

      Parameters:
        `clazz` - the collaborator class to stub
        `interceptConstruction` - whether constructor calls should be intercepted

  - ### Method Detail

    - #### Object ignore(Object filter, Closure filterBehavior)

      Allows particular method calls to be ignored and not treated as part of the required behavior specification. If you don't specify a return closure the method call will fall through to the underlying instance, i.e. half-mock style. The `filter` object is invoked using the normal Groovy `isCase()` semantics.

      See:
        MockFor#ignore(Object, Closure)

    - #### GroovyObject makeProxyInstance(Object args, boolean isDelegate)

      Creates a proxy-backed instance and wires it to a dedicated loose expectation.

      Parameters:
        `args` - optional constructor arguments
        `isDelegate` - whether Java targets should be wrapped as delegate proxies
      Returns:
        the proxy-backed instance

    - #### GroovyObject proxyDelegateInstance(Object args)

      Allows a more traditional instance-style stubbing paradigm. This is the recommended method to call to use the instance-style with Java classes.

      See:
        MockFor#proxyDelegateInstance(Object)

    - #### GroovyObject proxyInstance(Object args)

      Allows a more traditional instance-style stubbing paradigm. This is the recommended method to call to use the instance-style with Groovy classes.

      See:
        MockFor#proxyInstance(Object)

    - #### void use(Closure closure)

      See:
        MockFor#use(Closure)

    - #### void use(GroovyObject obj, Closure closure)

      Applies this stub to a single Groovy object for the duration of the supplied closure.

      Parameters:
        `obj` - the object whose meta class should be replaced temporarily
        `closure` - the work to run while the stub is active

    - #### void verify(GroovyObject obj)

      For manual verification

    - #### void verify()

      Convenience method