ranierif/api-mocker

A simple package to mock API responses for testing

v1.0.1 2025-08-15 17:10 UTC

Requires

• php: ^8.2
• ext-json: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.40
• mockery/mockery: ^1.6
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0
• symfony/var-dumper: ^6.3

MIT

• php
• api
• testing
• mock

README

API Mocker

A simple and flexible package to mock API responses for testing in PHP applications. This package helps you create and manage mock responses for your API integrations, making your tests more reliable and faster.

Introduction

API Mocker provides an easy way to mock external API responses in your PHP tests. Instead of making real HTTP requests during testing, you can use predefined JSON responses, making your tests:

• Faster (no actual HTTP requests)
• More reliable (no dependency on external services)
• Deterministic (you control the responses)
• Offline-capable (no internet connection required)

Requirements

• PHP 8.2 or higher
• ext-json
• Composer

Installation

You can install the package via composer:

composer require --dev ranierif/api-mocker

Usage

1. Creating a New API Mocker

First, create a new API mocker for your provider using the command:

vendor/bin/make-api-mocker YourProviderName

For example, to create a Stripe API mocker:

vendor/bin/make-api-mocker Stripe

This will create:

tests/ 
└── ApiMocker/ 
    └── Stripe/ 
        ├── StripeApiMocker.php 
        └── json/

2. Adding Mock Responses

Create JSON files in the json directory for your mock responses. The structure should be:

tests/ApiMocker/Stripe/json/
├── customers/
│   ├── success.json
│   └── error.json
└── payments/
    ├── success.json
    └── error.json

Example JSON response file (tests/ApiMocker/Stripe/json/customers/success.json):

{
  "id": "cus_123456",
  "object": "customer",
  "email": "[e-mail]",
  "name": "Test Customer"
}

3. Using in Tests

Here's how to use the API mocker in your tests:

<?php

namespace Tests\Feature\Payment;

use Illuminate\Http\Response;
use Mockery;
use Ranierif\Traits\ApiMockerTrait;
use Tests\TestCase;
use Tests\ApiMocker\stripe\StripeApiMocker;

class PaymentTest extends TestCase
{
    use ApiMockerTrait;

    public function test_successful_customer_creation(): void
    {
        // Arrange
        $mockResponseBody = $this->getMockResponseAsArray(
            provider: 'stripe', 
            endpoint: 'customers', 
            scenario: 'success',
        );
                
        $this->instance(
            StripeApiService::class,
            Mockery::mock(StripeApiService::class, function (MockInterface $mock) use ($mockResponseBody) {
                return $mock->shouldReceive('requestCreateCustomer')->andReturn([
                    'status_code' => Response::HTTP_OK,
                    'body' => $mockResponseBody,
                ]);
            })
        );
        
        // Act
        $response = $this
            ->postJson(
                '/api/customers',
                [
                    'name' => 'Test Customer',
                    'email' => '[e-mail]',
                ]
            );
        
        // Assert
        $this->assertJson($response);
        $this->assertEquals($mockResponseBody['id'], $response['id']);
    }
}

4. Creating Custom Responses

You can extend the base ApiMocker class to add custom methods for your specific needs:

<?php

namespace Tests\ApiMocker\Stripe;

use Ranierif\ApiMocker\AbstractApiMocker;

class StripeApiMocker extends AbstractApiMocker
{
    protected function getProviderName(): string
    {
        return 'stripe';
    }

    public function getCustomerSuccessResponse(): string
    {
        return $this->getResponse('customers', 'success');
    }

    public function getCustomerErrorResponse(): string
    {
        return $this->getResponse('customers', 'error');
    }
}

Testing Different Scenarios

You can create different JSON files for various scenarios:

• Success responses
• Error responses
• Validation failures
• Special cases

Simply create a new JSON file with an appropriate name and use it in your tests:

// Test success scenario
$successResponse = $mocker->getResponse('payments', 'success');

// Test error scenario
$errorResponse = $mocker->getResponse('payments', 'error');

// Test validation failure
$validationResponse = $mocker->getResponse('payments', 'validation_error');

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.