NAME

    Jasmine::Spy

VERSION

    version 1.01

SYNOPSIS

            use Test::Spec;
            use Jasmine::Spy qw(spyOn stopSpying expectSpy);
    
            describe "FooClass" => sub {
                    before each => sub {
                            spyOn("BarClass", "bazMethod")->andReturn("Bop");
                            spyOn("BarClass", "bam")->andCallThrough;
                    };
                    it "calls BarClass" => sub {
                            FooClass->doTheThing();
                            expectSpy("BarClass", "bazMethod")->toHaveBeenCalled();
                    };
                    it "calls BarClass->bat method with 'bam'" => sub {
                            FooClass->doTheThing();
                            expectSpy("BarClass", "bat")->toHaveBeenCalledWith('bam')
                    };
                    after each => sub {
                            stopSpying("BarClass");
                    };
            };

Methods

    Nothing is exported by default, but they cann all be pulled in with the
    :all tag

 Base Class Methods

    spyOn($invocant, $method)

      This is the setup method to begin spying. $invocant may be either an
      object instance or the name of a class. Spying on a Class will
      automatically spy on all instances of the class, even those created
      before setting up the spy. Spyng on an instance only effects that
      instance, not the class or other instances of that class.

      A "spy" object is returned from this call which will allow
      introspection and testing of calls. However there is no need to catch
      this, as other convience methods provide a better way of performing
      the same introspection later.

    stopSpying($invocant)

      Use this call to stop spying and restore original functionality to
      the object or class.

    expectSpy($invocant, $method)

      Use this to retrieve the "spy" object created by spyOn. It also sets
      the spy object to introspect of the provided $method. There is only
      one spy object created for each distinct $invocant beign spied on,
      even if multiple methods are being watched. This is why expectSpy is
      the recomended way to start introspection on a spied method.

    getCalls($invocant, $method)

      This will fetch an array of array's containing the arguments passed
      each time the $method was called. This is a tied array ref which also
      provides convience methods first and mostRecent.

 Spy object methods

    toHaveBeenCalled

      Test that the spied method has been called atleast once.

    notToHaveBeenCalled

      Test that the spied method was never called.

    toHaveBeenCalledWith($matchers)

      Expects that the spied method has been called with arguments matching
      $matchers atleast once. This is done with deep comparison via
      Test::Deep.

    notToHaveBeenCalledWith($matchers)

      Inverse of toHaveBeenCalledWith.

    andReturn($value)

      Sets the spied method to return the supplied value. Usually this
      would be called directly on the return from spyOn.

      For example:

              spyOn($foo, 'bar')->andReturn('baz')

    andCallThrough

      Sets the spied method to call through to the original method,
      recording arguments passed along the way.

    andCallFake(sub {})

      Sets the spied method to invoke the supplied code reference in place
      of the original method. It does also record the arguments along the
      way.

 Qunatifiers

    Quantifiers may be called on the return of either toHaveBeenCalled or
    toHaveBeenCalledWith to stipulate how many times the method should have
    been called.

    once()

      The method was called exactly one time

    atleast(X)

      Method was called atleast X times

    atMost(X)

      Method was not called more than X times

    exactly(X)

      Method was called exactly X times.

TODO

    Convience Method for andThrow

      Having put some thought into this, I haven't come up with a clean
      robust way to handle it. In the end, I think you are better off using
      andCallFake to throw an exception if you need to test that.

See also

    Test::Spec, Test::Deep

