Properly testing an SDK that calls an API

Question

I have an API that I've written and now I'm in the middle of writing an SDK for 3rd parties to more easily interact with my API.

When writing tests for my SDK, it's my understanding that it's best not to simply call all of the API endpoints because:

1. The tests in the API will be responsible for making sure that the API works.
2. If the SDK tests did directly call the API, my tests would be really slow.

As an example, let's say my API has this endpoint:

/account

In my API test suite I actually call this endpoint to verify that it returns the proper data.

What approach do I take to test this in my SDK? Should I be mocking a request to /account? What else would I need to do to give my SDK good coverage?

I've looked to other SDKs to see how they're handling this (Stripe, Algolia, AWS), but in some cases it does look like they're calling a sandbox version of the actual API.

(I'm currently working with PHPUnit, but I'll be writing SDKs in other languages as well.)

Answer 1

I ended up taking this approach:

I have both unit tests AND integration tests.

My integration tests call the actual API. I usually run this much less frequently — like before I push code to a remote. (Anyone who consumes my code will have to supply their own API credentials)

My unit tests — which I run very frequently — just make sure that the responses from my code are what I expect them to look like. I trust the 3rd party API is going to give me good data (and I still have the integration tests to back that up).

I've accomplished this by mocking Guzzle, using Reflection to replace the client instance in my SDK code, and then using Mock Handlers to mock the actual response I expect.

Here's an example:

/** @test */
public function it_retrieves_an_account()
{
    $account = $this->mockClient()->retrieve();

    $this->assertEquals(json_decode('{"id": "9876543210"}'), $account);
}

protected function mockClient()
{
    $stream = Psr7\stream_for('{"id": "9876543210"}');
    $mock = new MockHandler([new Response(
        200,
        ['Content-Type' => 'application/json'],
        Psr7\stream_for($stream)
    )]);

    $handler = HandlerStack::create($mock);
    $mockClient = new Client(['handler' => $handler]);

    $account = new SparklyAppsAccount(new SparklyApps('0123456789'));
    $reflection = new \ReflectionClass($account);
    $reflection_property = $reflection->getProperty('client');
    $reflection_property->setAccessible(true);
    $reflection_property->setValue($account, $mockClient);

    return $account;
}

Answer 2

When writing tests for the SDK you assume that your api DOES work exactly like it should (and you write tests for your api to assure that).

So using some kind of sandbox or even a complete mock of your api is sufficient.