orbituw/faketories

A package to help create data sets when faking APIs for unit tests within laravel

0.0.1 2017-08-16 13:51 UTC

Requires

• php: >=5.6
• fzaninotto/faker: ^1.6
• illuminate/support: 5.*.*

Requires (Dev)

• orchestra/testbench: 3.1
• phpunit/phpunit: 5.*

MIT

• Talv Bansal
• Nash Bansal
• Teejay Bansal

README

This laravel packages providers a trait that can help generate data sets to be returned from fake API's during unit testing.

If you've watched Adam Wathan's Test Driven Laravel series you'll have seen that he recommends creating "fake" objects or gateway classes to be swapped into your Laravel applications container during testing in scenarios when a class needs to talk out to the internet.

If you've used Laravel's model factories before, using faketories should be convenient and instantly recognisable.

Getting started

You can install the package via composer:

composer require orbituw/faketories --dev

Register the package in the providers array of your config/app.php file: (Laravel 5.5+ users can skip this step)

\OrbitUW\Faketories\FaketoriesServiceProvider::class,

Generate a sample /tests/faketories/faketories.php definitions file:

php artisan faketories:install 

Usage Example

// give example of vrm lookup in real world

In the below example we needed to test that we could get a vehicles full details from an api, to present that information in our app, so we used faketories to create a fake gateway to generate the data needed

// Logical Steps

1. Create an interface that lists out all of the methods that your real gateway will call so that your fake gateway can do the same.

2. Create an interface so that your 'fake gateway' implements the same methods as your real gateway to ensure that the fake and real gateways can be bound to Laravels app container and swapped out with no issues.

3. Ensure the fake gateway has the exact same methods and properties as the class that will be accessing the 'real' API.

4. Modify the methods that access the 'real' API to point to the fake data generated by Faketories so the methods can be tested.

// Implementation

In app/Providers/AppServiceProvider.php bind the common interface to the Real Gateway within the laravel container.

    public function register()
    {
         $this->app->bind(VehicleGatewayInterface::class, RealVehicleApi::class);
    }

Then in your testing class, bind your interface to a specific instance of your fake gateway:

    public function test_you_can_get_vehicle_by_reg()
    {

        //create new instance of fake gateway
        $vehicleApi = new FakeVehicleApi();
 

        //generate a new faketory data set with specific values
        $vehicleApi->generate([
            'reg_no' => 've59hgp',
            'make' => 'audi',
        ]);
 

        //generate additional 5 totally random sets
        $vehicleApi->generate([], 5);
 

        //finally bind the interface to this gateway
        $this->app->instance(VehicleApiInterface::class, $vehicleApi);
    }

In your tests directory you will have a faketories directory which contains faketories.php

$faketory->define(\Tests\FakeVehicleApi::class, function( Generator $faker ){

    $transmissions = ['Manual', 'Auto'];

    return [
        'reg_no' => $faker->unique()->name,
        'make' => $faker->name(),
        'model' => $faker->numberBetween(100,400),
        'colour' => $faker->colorName,
        'year' => $faker->year,
        'engine' => $faker->numberBetween(500, 4000),
        'transmission' => $transmissions[ array_rand($transmissions) ],
    ];
});

This may look familiar to you if you've used laravel's model factories previously. You can define a class and a set of sample data you would like it to return. An instance of the faker library is passed into each definition so that you can create fake data sets quickly.

You must then create a new FakeApi class which will be used to create the testing end points for your fake API

class FakeVehicleApi implements VehicleApiInterface
{
    //import faketories trait
    use Faketories;
 

    public function getVehicleByReg($reg)
    {
        return $this->data->filter(function($vehicle) use($reg){
           return $vehicle->reg_no === $reg;
        })->first();
    }
}

note that we are using the Faketories trait which gives us access to a property called $data that will contain all of the data generated by the Faketories trait. $data is a Collection, you can then use any collection pipelines to manipulate the property.

Now when testing Faketory will produce the data acting as a fake api:

    public function test_you_can_get_vehicle_by_reg()
    {
        $vehicle = new FakeVehicleApi();
        $vehicle->generate([
            'reg_no' => 'TE57 ING'
        ]);
    
        $response = $vehicle->getVehicleByReg('TE57 ING');

        $this->assertEquals('TE57 ING', $response->reg_no);

    }

Enjoy :-)