ApexMocks Supported Features

Currently the ApexMocks framework supports the following:

  • verify a method was called with the correct arguments
  • verify a method was called n number of times
  • verify a method was never called
  • stub a method call with a particular set of arguments to return a particular value
  • stub a method call with a particular set of arguments to throw a particular exception

Caveats (given I developed ApexMocks in my free time):

  • somewhat stating the obvious, I haven’t tested ApexMocks with every possible variant of method you could write in Apex
  • apex-mocks-generator has not been tested against all possible variations of interface method definitions – it is possible it may fail when generating a mock class for some methods – if that happens please contact me. (Or if you are very brave edit the generated mock code directly.)

Please contact me @comic96 on Twitter or via this blog to feedback or ask questions. Or fork the GitHub repo. Thank you!


Stubbing Dependencies in a Unit Test

Last time we saw how to verify the behaviour of our components using verify() based unit tests.

The other beauty of a mocking framework is that it allows you to stub dependencies so you can focus on unit testing the logic of the component you are working on, without worrying about having to use real versions of dependencies.

For example, suppose you are creating a component like a VisualForce controller extension, which uses a service class to interact with business logic (see Apex Enterprise Patterns).

Traditionally, to unit test your VF controller, you would need to create records and insert them in the database, so that your service class will then load the necessary data when it is used by the controller extension.

But with the ApexMocks framework, you can stub your service class to return whatever data you like – and it doesn’t have to even exist on the database.

This means less setup for your test and also the test will run much more quickly because it doesn’t have to interact with a real version of your service class, which in turn means no interaction with the database. So we can write DML free unit tests.

To give a simple example, say we want to stub a CarService to return some data such that we can test a CarControllerExtension:

private class CarControllerExtensionUnitTest
    static void bookingCarServiceShouldTakeUserToServicingPage()
        // Given
        ApexMocks mocks = new ApexMocks();
        CarService.ICarService mockCarService = new MockCarService(mocks);

        // Create our custom object but don't insert it into the database
        Car__c car = ObjectBuilder.createCar().withName('Audi').

        // Use the ApexMocks IDGenerator to create a dummy Salesforce Id for our object.
        // In reality we would probably get our ObjectBuilder to do this for us.
        Id carId = IDGenerator.generate(Car__c.SObjectType);
        car.Id = carId.

        // Use ApexMocks to stub the return value for the service's getCar() method
        // When
        CarControllerExtension carControllerExtension = new CarControllerExtension(mockCarService);
        PageReference carServicePageRef = carControllerExtension.bookCarService(carId);

        // Then
        System.assertEquals('myExpectedPageRef', carServicePageRef.getUrl());

Anyone familiar with mockito syntax should recognise the when() call immediately, apart from the startStubbing() and stopStubbing() calls.

In this test we have also used an ObjectBuilder with a fluent API for creating our test object, and the ApexMocks IDGenerator to create a fake Salesforce Id.

ApexMocks frees you up to stub any of your Apex classes which should transform the way you are able to write unit tests for the Force.com platform.

The key thing to focus on is testing the logic of your class/component, and to use mock versions of it’s depdendencies where appropriate. But don’t mock yourself into a corner – mocks are very powerful, but can be overused.


Writing Behaviour Verification Unit Tests

Last time we saw how to add a mock implementation of our component to our unit test class using the apex-mocks-generator tool.

Now we have everything in place to verify the behaviour of our components in our unit test.

So to take an example, say we want to verify that a BillingService component interacts correctly with a CreditCardProcessor component. To do this we can write a behaviour verification unit test like this:

private class BillingServiceUnitTest
    static void chargingCustomerShouldProcessCreditCardPayment()
        // Given
        ApexMocks mocks = new ApexMocks();
        CreditCardProcessor.ICreditCardProcessor mockCreditCardProcessor = new MockCreditCardProcessor(mocks);

        Order order = new Order();
        // fill in order details
        order.Id = IDGenerator.generate(Order.SObjectType);

        // When
        BillingService billingService = new BillingService(mockCreditCardProcessor);

        // Then
        ((CreditCardProcessor.ICreditCardProcessor) mocks.verify(mockCreditCardProcessor)).processPayment(order);

Anyone familiar with mockito syntax should recognise the verify() immediately, apart from the cast. Apex has its limits!

The important thing here is the the ApexMocks framework is going to ensure that the correct method on the CreditCardProcessor was called with the correct arguments, when the BillingService charges a customer.

Notice that we didn’t need to insert the Order object into the database, so this test runs very quickly. We also used the ApexMocks IDGenerator to generate a fake Id for the Order object.

Using apex-mocks-generator to create mock class definitions

Last time we saw how to define a component interface such that we could use a mock version of a component in our unit tests.

In order to either verify or stub any given component, we need a mock version of the component which knows how to communicate with the ApexMocks framework.

It would be pretty laborious (and boring!) as a developer if we had to hand-write the mock implementations of our components all the time, so the ApexMocks framework provides a command line tool which will create and add mock class definitions for you.

Having created the component interface definition, you can add a mock implementation of your interface to your unit test class using the apex-mocks-generator. You can either do this via Java or ant. The basic format is the same, apex-mocks-generator needs to be told about:

  1. sourcePath – where your apex source files reside
  2. testClassName – the class to which you want to add the mock
  3. mockClassName – the implementation class name of the component you want to mock
  4. interfaceName – the interface within the implementation class you want to mock

Generating a Mock Implementation Using Command Line Java

Simply download the apex-mocks-generator JAR from GitHub, then run the following from your terminal:

java -jar apex-mocks-generator-2.0.5.jar <sourcePath> <testClassName> <mockClassName> <interfaceName>

e.g. java -jar apex-mocks-generator-2.0.5.jar src/classes BillingServiceUnitTest CreditCardProcessor ICreditCardProcessor

Generating a Mock Implementation Using ant

To generate a mock implementation using ant, add the following target to your build.xml file, replacing the <path-to-apex-mocks-jar>:

<target name="generate.apex.mock">
    <java classname="com.financialforce.apexmocks.ApexMockGenerator">
            <pathelement location="<path-to-apex-mocks-jar>.jar"/>
        <arg value="${sourcePath}"/>
        <arg value="${testClassName}"/>
        <arg value="${mockClassName}"/>
        <arg value="${interfaceName}"/>

Then from your terminal run:

ant generate.apex.mock -DsourcePath="src/classes" -DtestClassName="BillingServiceUnitTest" -DmockClassName="CreditCardProcessor" -DinterfaceName="ICreditCardProcessor"

Using a top-level Mocks Class

If you want to keep all your mock class definitions in a single top-level class file (rather than as inner classes in your unit test), just create something like a Mocks class in your Salesforce project and pass Mocks as the testClassName when  you generate a mock. This could aid reuse if more than one test wants to use any given mock class.

In the next post we’ll see how to start writing unit tests using ApexMocks.

Simple Dependency Injection

To start using the ApexMocks framework, you first need to take a Dependency Injection approach to writing your software. Dependency Injection is one way of achieving a loosely coupled, highly cohesive design for your code.

Personally I prefer constructor injection (as opposed to setter injection – Constructor Versus Setter Injection).

At it’s simplest level all this means is that you pass a given class its dependencies via its constructor. In order to facilitate robust production code and the ability to inject mocks I settled on this pattern:

public class MyClass
    private DependencyA.IDependencyA m_dependencyA;
    private DependencyB.IDependencyB m_dependencyB;

    public MyClass()
        this(new DependencyA(), new DependencyB());

    MyClass(DependencyA.IDependencyA dependencyA, DependencyB.IDependencyB dependencyB)
        this.dependencyA =dependencyA; this.dependencyB =dependencyB;

The ‘real’ production code creates MyClass via the normal default constructor, which still executes the private testVisible constructor, passing in real instances of the dependencies.

The crucial thing is, this frees us up and allows our test to construct MyClass via the private constructor passing in mock versions of the dependencies.

private class MyClass
    static void my_first_apex_mocks_test()
        // Given
        ApexMocks mocks = new ApexMocks();
        DependencyA.IDependencyA mockDependencyA = new MockDependencyA(mocks);
        DependencyB.IDependencyB mockDependencyB = new MockDependencyB(mocks);

        // When
        MyClass myClass = new MyClass(mockDependencyA, mockDependencyB);

We can then verify that MyClass interacts correctly with its dependencies by writing behaviour verification unit tests.

And we can also stub out the dependencies using when() style dependency stubbing.

This approach even allows us to write DML free tests that never even touch the database, and consequently execute very quickly!

Next time we’ll see how to use the apex-mocks-generator tool to create mock implementations of our component interface.

ApexMocks Framework Tutorial

The next series of posts will form a basic tutorial series explaining how to use the ApexMocks framework in detail. The things we will cover are:

  • Simple dependency injection
    • Defining your component interface
    • Defining your implementation class
  • Using apex-mocks-generator to inject mock dependency classes into your unit test class
  • Writing behaviour verification tests
  • Writing tests which stub dependencies