Sometimes the best documentation is code itself. Here are several examples of GrayMocks in action in some standard unit tests. Note: these require PHPUnit. These examples are also included in the downloadable package of GrayMocks, along side the rest of the GrayMocks unit tests. If you notice any errors or have any questions, please contact us.

<?php

require_once( 'PHPUnit/Framework/TestCase.php' );
require_once( 'GrayMocks/MockRepository.php' );
require_once( 'GrayMocks/Expect.php' );

class GrayMocks_Tests_UsageExampleTests extends PHPUnit_Framework_TestCase
{
    private $mockRepository;

    /**
     * @setUp
     */
    public function setUp()
    {
        // Notice we create a new MockRepository before every test method
        // call. This ensures a clean slate each time.
        $this->mockRepository = new GrayMocks_MockRepository();
    }

    /**
     * @test
     */
    public function testTypicalUsageForMethodsReturningSomething()
    {
        // First, we create a new mock for the type we want to inject.
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        // Next, we set up some expectations on the mock in terms of what's going to be
        // called, and what we want the mock to return.
        GrayMocks_Expect::call( $mockMapper->getAllMemberIds() )->returns( array( 35, 100 ) );

        // Then, we create the actual object we're testing, in this case, a MemberService.
        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        // Now, we call the actual method we're testing, in this case, getAllMemberIds()
        // Notice we wrap the method call with a call to the MockRepository's replayAll()
        // and verifyAll() methods.
        $this->mockRepository->replayAll();
        $allMembers = $systemUnderTest->getAllMemberIds();
        $this->mockRepository->verifyAll();

        // Finally, we perform any additional assertions on the data returned by the system
        // under test.
        $this->assertEquals( 2, count( $allMembers ) );
        $this->assertTrue( in_array( 35, $allMembers ) );
        $this->assertTrue( in_array( 100, $allMembers ) );
    }

    /**
     * @test
     */
    public function testReusingAMockInTheSameTest()
    {
        // First, we'll do basically the same test as in testTypicalUsageForMethodsReturningSomething()
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        GrayMocks_Expect::call( $mockMapper->getAllMemberIds() )->returns( array( 35, 100 ) );

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        $this->mockRepository->replayAll();
        $allMembers = $systemUnderTest->getAllMemberIds();
        $this->mockRepository->verifyAll();

        $this->assertEquals( 2, count( $allMembers ) );
        $this->assertTrue( in_array( 35, $allMembers ) );
        $this->assertTrue( in_array( 100, $allMembers ) );

        // Now, for whatever reason, let's say we want to re-use the same mock in this test
        // just with different expectations

        // First, we have to tell the repository to go back to record mode
        $this->mockRepository->backToRecordAll();

        // Then we can setup new expectations and proceed as usual
        // Except, notice we're setting up a different return value
        GrayMocks_Expect::call( $mockMapper->getAllMemberIds() )->returns( array( 999, 50, 2 ) );

        $this->mockRepository->replayAll();
        $allMembers = $systemUnderTest->getAllMemberIds();
        $this->mockRepository->verifyAll();

        $this->assertEquals( 3, count( $allMembers ) );
        $this->assertTrue( in_array( 999, $allMembers ) );
        $this->assertTrue( in_array( 50,  $allMembers ) );
        $this->assertTrue( in_array( 2,   $allMembers ) );
    }

    /**
     * @test
     */
    public function testTypicalUsageForAVoidMethod()
    {
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        // Next, we set up some expectations on the mock in terms of what's going to be
        // called. Since this is a "void" method (no return), there's no need to setup an
        // expected return value
        GrayMocks_Expect::call( $mockMapper->setLazyLoad( true ) );

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        // Now, we call the actual method we're testing, in this case, setLazyLoad()
        // Notice we wrap the method call with a call to the MockRepository's replayAll()
        // and verifyAll() methods.
        $this->mockRepository->replayAll();
        $systemUnderTest->setLazyLoad( true );
        $this->mockRepository->verifyAll();
    }

    /**
     * @test
     */
    public function testCheckingForMethodArguments()
    {
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        // Next, we set up some expectations on the mock in terms of what's going to be
        // called. This will also cause the method arguments to be checked as well, meaning
        // if a different argument is used when the mock method is actually called, then
        // GrayMocks will throw an expection
        GrayMocks_Expect::call( $mockMapper->setLazyLoad( true ) );

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        try
        {
            // Now we're going to call the method, but we're passing an unexpected argument
            // to the mock's expected method.
            $this->mockRepository->replayAll();
            $systemUnderTest->setLazyLoad( false );
            $this->mockRepository->verifyAll();

            $this->assertTrue( false );
        }
        catch ( GrayMocks_VerificationException $ve )
        {
            // Sure enough, this caused GrayMocks to throw an exception.
            $this->assertNotNull( $ve );
            $this->assertTrue( true );
        }

        // But say we make the concious decision to ignore the method arguments,
        // we just want to test that the method was called at all. Enter "ignoreArguments()"
        // Of course, we need to set the MockRepository back to record mode
        $this->mockRepository->backToRecordAll();

        GrayMocks_Expect::call( $mockMapper->setLazyLoad( true ) )->ignoreArguments();

        // Now we're going to call the method again, but this time, we shouldn't get any exceptions
        // since we're actively ignoring arguments passed to the mock
        $this->mockRepository->replayAll();
        $systemUnderTest->setLazyLoad( false );
        $this->mockRepository->verifyAll();
    }

    /**
     * @test
     */
    public function testChainingExpectationModifiers()
    {
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        // This example just shows how you can chain expectation modifiers together
        // e.g. ignoreArguments(), returns()
        GrayMocks_Expect::call( $mockMapper->activate( null ) )->ignoreArguments()->returns( true );

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        $this->mockRepository->replayAll();
        $actualValue = $systemUnderTest->activate();
        $this->mockRepository->verifyAll();

        $this->assertTrue( $actualValue );
    }

    /**
     * @test
     */
    public function testUnexpectedCallsThrowExceptions()
    {
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        // Here we've set up an expectation for one method...
        GrayMocks_Expect::call( $mockMapper->activate( 0 ) );

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        try
        {
            $this->mockRepository->replayAll();
            // But we're actually calling a different method on the mock, one that was not expected!
            $systemUnderTest->setLazyLoad( true );
            $this->mockRepository->verifyAll();

            $this->assertTrue( false );
        }
        catch ( GrayMocks_VerificationException $ve )
        {
            $this->assertNotNull( $ve );
            $this->assertTrue( true );
        }
    }

    /**
     * @test
     */
    public function testRepeatedCalls()
    {
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        // This example shows how you can simplify repeated calls to the same method
        // First, we'll demonstrate a failure
        GrayMocks_Expect::call( $mockMapper->setLazyLoad( true ) )->repeatTimes( 3 );

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        try
        {
            $this->mockRepository->replayAll();
            $systemUnderTest->setLazyLoad( true );
            $systemUnderTest->setLazyLoad( true );
            $this->mockRepository->verifyAll();

            $this->assertTrue( false );
        }
        catch ( GrayMocks_VerificationException $ve )
        {
            // Oh dear, the mock wasn't called enough times... let's try again
            $this->assertNotNull( $ve );
            $this->assertTrue( true );
        }

        $this->mockRepository->backToRecordAll();

        // This time around, we'll only expect 2 calls
        // Note: this also shows off one of the convenience methods for setting
        // up repeating expectations: repeatTwice() which is the same as repeatTimes( 2 )
        GrayMocks_Expect::call( $mockMapper->setLazyLoad( true ) )->repeatTwice();

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        $this->mockRepository->replayAll();
        $systemUnderTest->setLazyLoad( true );
        $systemUnderTest->setLazyLoad( true );
        $this->mockRepository->verifyAll();
    }

    /**
     * @test
     */
    public function testExpectingToThrowExceptions()
    {
        $mockMapper = $this->mockRepository->createMock( 'GrayMocks_Tests_IMemberMapper' );

        // This example shows how we can setup mocks to throw exceptions on a given method
        // call. This is useful to test how your system under test responds to these types
        // of situations when certain exceptions are thrown.
        GrayMocks_Expect::call( $mockMapper->getAllMemberIds() )->throws( new GrayMocks_Tests_MemberException( 'Error!' ) );

        $systemUnderTest = new GrayMocks_Tests_MemberService( $mockMapper );

        try
        {
            $this->mockRepository->replayAll();
            $systemUnderTest->getAllMemberIds();
            $this->mockRepository->verifyAll();

            $this->assertTrue( false );
        }
        catch ( GrayMocks_Tests_MemberException $e )
        {
            $this->assertNotNull( $e );
            $this->assertTrue( true );
        }
    }
}

interface GrayMocks_Tests_IMemberMapper
{
    public function setLazyLoad( $value );

    public function getAllMemberIds();

    public function activate( $value );
}

class GrayMocks_Tests_MemberService
{
    private $mapper;

    public function __construct( GrayMocks_Tests_IMemberMapper $mapper )
    {
        $this->mapper = $mapper;
    }

    public function setLazyLoad( $value )
    {
        $this->mapper->setLazyLoad( $value );
    }

    public function getAllMemberIds()
    {
        return $this->mapper->getAllMemberIds();
    }

    public function activate()
    {
        if ( $this->mapper->activate( 0 ) )
        {
            return true;
        }

        return false;
    }
}

class GrayMocks_Tests_MemberException extends Exception
{
    public function __construct( $message, $code = 0 )
    {
        parent::__construct( $message, $code );
    }
}

?>