📸Recording Responses

When writing tests for an API integration, it is best to simulate a real request as much as possible. With Saloon's MockResponse class, you can build up example responses manually. This is useful, but it can be time-consuming, especially if an API returns a huge amount of data, it would take a long time to manually write MockResponses and keep it maintained.

Saloon has a feature called fixture recording, this feature will allow you to make a real request to the API you are integrating with and then it will store that response in a file for later. This is a common practice for people writing integrations for APIs, but Saloon makes it effortless.

Registering a MockClient

Request recording starts with a MockClient. This class can be applied directly to a connector instance to be used across all requests, or it can be applied on a per-request basis.

All Requests (Connector)

<?php

use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;

$mockClient = new MockClient([
    MockResponse::fixture('servers.index'),
]);

$forge = new ForgeConnector;
$forge->withMockClient($mockClient);

Individual Request

<?php

use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;

$mockClient = new MockClient([
    MockResponse::fixture('servers.index'),
]);

$forge = new ForgeConnector;
$request = new GetAllServersRequest;

// Send a request with a MockClient

$forge->send($request, $mockClient);

Using Laravel?

If you are using Laravel, as well as the Saloon Laravel helper library, you don't have to use withMockClient on every instance of your connector. You may use the Saloon facade fake method to define your mock responses. This is a built-in global MockClient that when used will be applied to all Saloon requests sent in your application.

<?php

use Saloon\Laravel\Facades\Saloon;

Saloon::fake([
    MockResponse::fixture('servers.index'),
]);

Setup

Getting started with fixture recording is easy. When defining your mock responses, instead of defining a MockResponse with headers, data and config - use the fixture static property. This property will accept a single argument, the fixture name.

Non-Laravel

<?php

$mockClient = new MockClient([
    GetForgeServerRequest::class => MockResponse::fixture('singleServer')
]);

Laravel

<?php

Saloon::fake([
    GetForgeServerRequest::class => MockResponse::fixture('singleServer')
]);

The above example will configure a fixture to be used every time the UserRequest is called during mocking. You may also use a sequence of fixtures, connector mocking, or use a fixture on a specific URL path. Read the mocking pages for more information.

How does it work?

Once you have defined a fixture to be used for a particular request pattern, you can make a request just like you normally would. Saloon will check if the fixture already exists, and if it doesn't - it will make the real API request and store the response for next time.

Non-Laravel

<?php

$mockClient = new MockClient([
    GetForgeServerRequest::class => MockResponse::fixture('singleServer')
]);

$forge = new ForgeConnector;
$forge->withMockClient($mockClient);

// The initial request will check if a fixture called "singleServer" 
// exists. Because it doesn't exist yet, the real request will be
// sent and the response will be recorded.

$request = new GetForgeServerRequest(12345);
$response = $forge->send($request);

// However, the next time the request is made, the fixture will 
// exist, and Saloon will not make the request again.

$request = new GetForgeServerRequest(12345);
$response = $forge->send($request);

Laravel

<?php

Saloon::fake([
    GetForgeServerRequest::class => MockResponse::fixture('singleServer')
]);

$forge = new ForgeConnector;

// The initial request will check if a fixture called "singleServer" 
// exists. Because it doesn't exist yet, the real request will be
// sent and the response will be recorded.

$request = new GetForgeServerRequest(12345);
$response = $forge->send($request);

// However, the next time the request is made, the fixture will 
// exist, and Saloon will not make the request again.

$request = new GetForgeServerRequest(12345);
$response = $forge->send($request);

Namespacing

Depending on the size of your application and the number of API integrations you have, you may want to namespace the fixtures into their own folders, for example, I may have a "forge" namespace and a "digitalOcean" namespace.

Non-Laravel

<?php

$mockClient = new MockClient([
    GetForgeServerRequest::class => MockResponse::fixture('forge/singleServer'),
    GetDigitalOceanServerRequest::class => MockResponse::fixture('digitalOcean/singleServer'),
]);

Laravel

<?php

Saloon::fake([
    GetForgeServerRequest::class => MockResponse::fixture('forge/singleServer'),
    GetDigitalOceanServerRequest::class => MockResponse::fixture('digitalOcean/singleServer'),
]);

Configuration

Fixture Path

Ordinarily, Saloon will store all fixtures in a tests/Fixtures/Saloon directory. If you would like to customise this, you may use the MockConfig class in your tests or in your setUp methods.

<?php

MockConfig::setFixturePath('tests/other-directory')

Preventing Unwanted Requests

Once you have written all of your tests, you might want to prevent accidental API requests in the future for fixtures that don't exist. If you would like Saloon to throw exceptions if a fixture does not exist, you may do this with the MockConfig class.

<?php

MockConfig::throwOnMissingFixtures()

Redacting Fixture Information

When using fixtures to record real responses from an API - sometimes the API will return some sensitive information that you shouldn't store in your application's repository, like names of real people, financial data or emails. With Saloon, you can create a custom fixture class and provide a few methods to obscure the information when the data is stored. You can even provide closures for the data replacement so you can use tools like Faker to replace data like-for-like.

The first time the request is made and the fixture is stored, the original response won't be redacted. Only future requests made with the fixture will use the redacted recording.

Firstly, create a new class in your tests directory and give the class a name. We'll call this class SingleServerFixture. Then make sure to extend the base Fixture class provided by Saloon.

<?php

namespace Tests\Fixtures\Forge\SingleServerFixture;

use Saloon\Http\Faking\Fixture;

class ForgeSingleServerFixture extends Fixture
{
    //
}

Next, we need to give the fixture a name. Just extend the defineName method and give the fixture a name. You can still use slashes in this directory to denote folders.

<?php

namespace Tests\Fixtures\Forge\SingleServerFixture;

use Saloon\Http\Faking\Fixture;

class SingleServerFixture extends Fixture
{
    protected function defineName(): string
    {
        return 'forge/singleServer';
    }
}

Now you can use a few different methods to redact your fixture data. You can use the defineSensitiveHeaders method to swap any headers out with sensitive data, the defineSensitiveJsonParameters for JSON responses or defineSensitiveRegexPatterns to define regex patterns for Saloon to find.

<?php

namespace Tests\Fixtures\Forge\SingleServerFixture;

use Saloon\Http\Faking\Fixture;

class SingleServerFixture extends Fixture
{
    protected function defineName(): string
    {
        return 'forge/singleServer';
    }
    
    protected function defineSensitiveHeaders(): array
    {
        return [];
    }

    protected function defineSensitiveJsonParameters(): array
    {
        return [];
    }
    
    protected function defineSensitiveRegexPatterns(): array
    {
        return [];
    } 
}

Replacing Sensitive Headers

If a particular header contains sensitive information, you may use this method to define the headers that are sensitive and what to replace them with. You may use a value or a closure for a custom replacement based on the value

Simple - Using Arrays

protected function defineSensitiveHeaders(): array
{
    return [
        // Key = Header Name
        // Value = Replacement Value
    
        'Content-Type' => 'REDACTED',
    ];
}

Advanced - Using Closures

protected function defineSensitiveHeaders(): array
{
    return [
        // Key = Header Name
        // Value = Replacement Value / Closure
    
        'Content-Type' => static function (string $value) {
            return substr_replace($value, 'xxx', 1);
        },
    ];
}

Replacing Sensitive JSON Parameters

If the response you are dealing with is JSON - you can define sensitive JSON keys that should be replaced. For example, if there is a "name" key - anytime this is found the value will be replaced with the replacement you define. The keys provided are recursive, so if "name" is within a nested JSON array, it will still be replaced.

Simple - Using Arrays

protected function defineSensitiveJsonParameters(): array
{
    return [
        // Key = JSON Key
        // Value = Replacement Value
    
        'name' => 'REDACTED',
    ];
}

Advanced - Using Closures

protected function defineSensitiveJsonParameters(): array
{
    return [
        // Key = JSON Key
        // Value = Replacement Value / Closure
    
        'name' => static function (string $value) {
            // Example: You could use something like Faker to generate
            // fake information and provide a similar structure.
        
            return faker()->firstName();
        },
    ];
}

Finding and Replacing From Regex Patterns

When the API response you are given is not JSON - it can be difficult to replace the information. When you encounter APIs like these, you can use the defineSensitiveRegexPatterns method to find and replace regex patterns in an all-string response body. The key of the array is the regex pattern and the value is the replacement.

Simple - Using Arrays

protected function defineSensitiveRegexPatterns(): array
{
    return [
        // Key = Regex Pattern
        // Value = Replacement Value
        
        '/@[a-z0-9_]{0,100}/' => 'REDACTED-TWITTER-HANDLE',
    ];
}

Advanced - Using Closures

protected function defineSensitiveRegexPatterns(): array
{
    return [
        // Key = Regex Pattern
        // Value = Replacement Value
        
        '/@[a-z0-9_]{0,100}/' => static function (string $value) {
            // Example: You could use something like Faker to generate
            // fake information and provide a similar structure.
        
            return faker()->userName();
        },
    ];
}

Using your custom fixtures

Once you have created your custom fixture class with the redaction configuration, you can simply use it instead of MockResponse::fixture() in your tests. All detection methods in the mock client work with this type of fixture too.

<?php

$mockClient = new MockClient([
    GetServerRequest::class => new SingleServerFixture;
]);

Preventing Stray API Requests

Once you have written your tests - it's a good idea to ensure that no real API requests are made in the future while running those tests. This is because you could be making requests when you don't intend to which could incur charges or worse, make real changes to data you don't expect. With Saloon, you can prevent stray API requests with the global Config helper. Simply in your tests, call the Config::preventStrayRequests() method and you should be good to go!

It's recommended that you place this in your Pest.php file or in your setUp() method to make sure it's used on every test.

Pest.php (PEST)

<?php

use Saloon\Helpers\Config;

beforeEach(function () {
    Config::preventStrayRequests();
});

TestCase.php (PHPUnit)

<?php

use Saloon\Helpers\Config;

class TestCase {

    public function setUp()
    {
        Config::preventStrayRequests();
    }

}

Advanced Usage

You may want to return custom fixtures based on the request without specifying exact names of fixtures. For example, I might want to build a fixture name based on the name of the request being sent. You may use a closure inside the mock client and write the custom logic to meet these needs.

Non-Laravel

<?php

$mockClient = new MockClient([
    '*' => function (PendingRequest $request) {
        $reflection = new ReflectionClass($request->getRequest());

        return MockResponse::fixture($reflection->getShortName());
    },
]);

$forge = new ForgeConnector;
$forge->withMockClient($mockClient);

// This will create a fixture called "GetForgeServerRequest"

$request = new GetForgeServerRequest(12345);
$response = $forge->send($request);

// This will create a fixture called "GetAllForgeServersRequest"

$request = new GetAllForgeServersRequest($data);
$response = $forge->send($request);

Laravel

<?php

Saloon::fake([
    '*' => function (PendingRequest $request) {
        $reflection = new ReflectionClass($request->getRequest());

        return MockResponse::fixture($reflection->getShortName());
    },
]);

$forge = new ForgeConnector;

// This will create a fixture called "GetForgeServerRequest"

$request = new GetForgeServerRequest(12345);
$response = $forge->send($request);

// This will create a fixture called "GetAllForgeServersRequest"

$request = new GetAllForgeServersRequest($data);
$response = $forge->send($request);

Another example from Astrotomic's Steam SDK allows you to create a directory for each request. This is really useful for organising your mock fixtures.

<?php

$mockClient = new MockClient([
    '*' => function (PendingRequest $pendingRequest) {
        $name = implode('/', array_filter([
             parse_url($pendingRequest->getUrl(), PHP_URL_HOST),
             mb_strtoupper($pendingRequest->getMethod() ?? 'GET'),
             parse_url($pendingRequest->getUrl(), PHP_URL_PATH),
             http_build_query(array_diff_key($pendingRequest->query()->all(), array_flip(['key', 'format']))),
        ]));
          
        return MockResponse::fixture($name);
    },
]);