Test requests in Laravel without all the boilerplate.

Last update: Jun 30, 2022

Request Factories

Test requests in Laravel without all the boilerplate.

Unit Tests PHPStan

ūüí° Psst. Although our examples use Pest PHP, this works just as well in PHPUnit.

Take a look at the following test:

it('can sign up a user with an international phone number', function () {
    $this->put('/users', [
        'phone' => '+375 154 767 1088',
        'email' => '[email protected]', ūüôĄ
        'name' => 'Luke Downing', ūüėõ
        'company' => 'Worksome', ūüėí
        'bio' => 'Blah blah blah', ūüėę
        'profile_picture' => UploadedFile::fake()->image('luke.png', 200, 200), ūüė≠
        'accepts_terms_and_conditions' => true, ūü§¨
    ]);
    
    expect(User::latest()->first()->phone)->toBe('+375 154 767 1088');
});

Oof. See, all we wanted to test was the phone number, but because our route's FormRequest has validation rules, we have to send all of these additional fields at the same time. This approach has a few downsides:

  1. It muddies the test. Tests are supposed to be terse and easy to read. This is anything but.
  2. It makes writing tests annoying. You probably have more than one test for each route. Every test you write requires all of these fields over and over again.
  3. It requires knowledge of the FormRequest. You'd need to understand what each field in this form does before being able to write a passing test. If you don't, you're likely going to be caught in a trial-and-error loop, or worse, a false positive, whilst creating the test.

We think this experience can be vastly improved. Take a look:

it('can sign up a user with an international phone number', function () {
    SignupRequest::fake();

    $this->put('/users', ['phone' => '+375 154 767 1088']);

    expect(User::latest()->first()->phone)->toBe('+375 154 767 1088');
});

Soooooo much nicer. And all thanks to Request Factories. Let's dive in...

Installation

You can install the package as a developer dependency via Composer:

composer require --dev worksome/request-factories 

Usage

First, let's create a new RequestFactory. A RequestFactory usually complements a FormRequest in your application (request factories work with standard requests too!). You can create a RequestFactory using the make:request-factory Artisan command:

php artisan make:request-factory "App\Http\Requests\SignupRequest"

Note that we've passed the SignupRequest FQCN as an argument. This will create a new request factory at tests/RequestFactories/SignupRequestFactory.php.

You can also pass your desired request factory name as an argument instead:

php artisan make:request-factory SignupRequestFactory

Whilst you're free to name your request factories as you please, we recommend two defaults for a seamless experience:

  1. Place them in tests/RequestFactories. The Artisan command will do this for you.
  2. Use a Factory suffix. So SignupRequest becomes SignupRequestFactory.

Factory basics

Let's take a look at our newly created SignupRequestFactory. You'll see something like this:

namespace Tests\RequestFactories;

use Worksome\RequestFactories;

class SignupRequestFactory extends RequestFactory
{
    public function definition(): array
    {
        return [
            // 'email' => $this->faker->email,
        ];
    }
}

If you've used Laravel's model factories before, this will look pretty familiar. That's because the basic concept is the same: a model factory is designed to generate data for eloquent models, a request factory is designed to generate data for form requests.

The definition method should return an array of valid data that can be used when submitting your form. Let's fill it out for our example SignupRequestFactory:

namespace Tests\RequestFactories;

use Worksome\RequestFactories;

class SignupRequestFactory extends RequestFactory
{
    public function definition(): array
    {
        return [
            'phone' => '01234567890',
            'email' => '[email protected]',
            'name' => 'Luke Downing',
            'company' => 'Worksome',
            'bio' => $this->faker->words(300, true),
            'accepts_terms_and_conditions' => true,
        ];
    }
    
    public function files(): array
    {
        return [
            'profile_picture' => $this->file()->image('luke.png', 200, 200),
        ];
    }
}

Note that we have access to a faker property for easily generating fake content, such as a paragraph for our bio, along with a files method we can declare to segregate files from other request data.

Usage in tests

So how do we use this factory in our tests? There are a few options, depending on your preferred style.

Using create on the factory

This method is most similar to Laravel's model factories. The create method returns an array, which you can then pass as data to put, post or any other request testing method.

it('can sign up a user with an international phone number', function () {
    $data = SignupRequest::factory()->create(['phone' => '+44 1234 567890']);
    
    $this->put('/users', $data)->assertValid();
});

Using fake on the request factory

Seeing as you only normally make a single request per test, we support registering your factory globally with fake. If you're using this approach, make sure that it's the last method you call on the factory, and that you call it before making a request to the relevant endpoint.

it('can sign up a user with an international phone number', function () {
    SignupRequestFactory::new()->fake();
    
    $this->put('/users')->assertValid();
});

Using fake on the form request

If you've used Laravel model factories, you'll likely be used to calling ::factory() on eloquent models to get a new factory instance. Request factories have similar functionality available. First, add the Worksome\RequestFactories\Concerns\HasFactory trait to the relevant FormRequest:

class SignupRequest extends \Illuminate\Foundation\Http\FormRequest
{
    use \Worksome\RequestFactories\Concerns\HasFactory;
}

This provides access to 2 new static methods on the form request: ::factory() and ::fake(). You can use these methods in your tests instead of instantiating the request factory directly:

it('can sign up a user with an international phone number', function () {
    // Using the factory method...
    SignupRequest::factory()->fake();
    
    // ...or using the fake method
    SignupRequest::fake();
    
    $this->put('/users')->assertValid();
});

Using fakeRequest in Pest PHP

If you're using Pest, we provide a higher order method that you can chain onto your tests:

// You can provide the form request FQCN...
it('can sign up a user with an international phone number', function () {
    $this->put('/users')->assertValid();
})->fakeRequest(SignupRequest::class);

// Or the request factory FQCN...
it('can sign up a user with an international phone number', function () {
    $this->put('/users')->assertValid();
})->fakeRequest(SignupRequestFactory::class);

// Or even a closure that returns a request factory...
it('can sign up a user with an international phone number', function () {
    $this->put('/users')->assertValid();
})->fakeRequest(fn () => SignupRequest::factory());

You can even chain factory methods onto the end of the fakeRequest method:

it('can sign up a user with an international phone number', function () {
    $this->put('/users')->assertValid();
})
    ->fakeRequest(SignupRequest::class)
    ->state(['name' => 'Jane Bloggs']);

Overriding request factory data

It's important to note the order of importance request factories take when injecting data into your request.

  1. Any data passed to get, post, put, patch, delete or similar methods will always take precedence.
  2. Data defined using state, or methods called on a factory that alter state will be next in line.
  3. Data defined in the factory definition and files methods come last, only filling out missing properties from the request.

Let's take a look at an example to illustrate this order of importance:

it('can sign up a user with an international phone number', function () {
    SignupRequest::factory()->state(['name' => 'Oliver Nybroe', 'email' => '[email protected]'])->fake();
    
    $this->put('/users', ['email' => '[email protected]'])->assertValid();
});

The default email defined in SignupRequestFactory is [email protected]. The default name is Luke Downing. Because we override the name property using the state method before calling fake, the name used in the form request will actually be Oliver Nybroe, not Luke Downing.

However, because we pass [email protected] as data to the put method, that will take priority over all other defined data, both [email protected] and [email protected].

The power of factories

Factories are really cool, because they allow us to create a domain-specific-language for our feature tests. Because factories are classes, we can add declarative methods that serve as state transformers.

// In our factory...
class SignupRequestFactory extends RequestFactory
{
    // After the definition...
    public function withOversizedProfilePicture(): static
    {
        return $this->state(['profile_picture' => $this->file()->image('profile.png', 2001, 2001)])
    }
}

// In our test...
it('does not allow profile pictures larger than 2000 pixels', function () {
    SignupRequest::factory()->withOversizedProfilePicture()->fake();
    
    $this->put('/users')->assertInvalid(['profile_picture' => 'size']);
});

The state method is your friend for any data you want to add or change on your factory. What about if you'd like to omit a property from the request? Try the without method!

it('requires an email address', function () {
    SignupRequest::factory()->without(['email'])->fake();
    
    $this->put('/users')->assertInvalid(['email' => 'required']);
});

ūüí° You can use dot syntax in the without method to unset deeply nested keys

Sometimes, you'll have a property that you want to be based on the value of other properties. In that case, you can provide a closure as the property value, which receives an array of all other parameters:

class SignupRequestFactory extends RequestFactory
{
    public function definition(): array
    {
        return [
            'name' => 'Luke Downing',
            'company' => 'Worksome',
            'email' => fn ($properties) => Str::of($properties['name'])
                ->replace(' ', '.')
                ->append("@{$properties['company']}.com")
                ->lower()
                ->__toString(), // [email protected]
        ];
    }
}

Occasionally, you'll notice that multiple requests across your application share a similar subset of fields. For example, a signup form and a payment form might both contain an address array. Rather than duplicating these fields in your factory, you can nest factories inside factories:

class SignupRequestFactory extends RequestFactory
{
    public function definition(): array
    {
        return [
            'name' => 'Luke Downing',
            'company' => 'Worksome',
            'address' => AddressRequestFactory::new(),
        ];
    }
}

Now, when the SignupRequestFactory is created, it will resolve the AddressRequestFactory for you and fill the address property with all fields contained in the AddressRequestFactory definition. Pretty cool hey?

Using factories without form requests

Not every controller in your app requires a backing form request. Thankfully, we also support faking a generic request:

it('lets a guest sign up to the newsletter', function () {
    NewsletterSignupFactory::new()->fake();
    
    post('/newsletter', ['email' => '[email protected]'])->assertRedirect('/thanks');
});

Solving common issues

I'm getting a CouldNotLocateRequestFactoryException

When using the HasFactory trait on a FormRequest, we attempt to auto-locate the relevant request factory for you. If your directory structure doesn't match for whatever reason, this exception will be thrown.

It can easily be resolved by adding a public static $factory property to your form request:

class SignupRequest extends FormRequest
{
    use HasFactory;
    
    public static $factory = SignupRequestFactory::class; 
}

I call multiple routes in a single test and want to fake both

No sweat. Just place a call to fake on the relevant request factory before making each request:

it('allows a user to sign up and update their profile', function () {
    SignupRequest::fake();
    post('/signup');
    
    ProfileRequest::fake();
    post('/profile')->assertValid();
});

I don't want to use the default location for storing request factories

Not a problem. We provide a config file you may publish where you can edit the path and namespace of request factories. First, publish the config file:

php artisan vendor:publish --tag=request-factories

Now, in the newly created config/request-factories.php, alter the path and namespace keys to suit your requirements:

return [
    'path' => base_path('request_factories'),
    'namespace' => 'App\\RequestFactories',
];

Testing

We pride ourselves on a thorough test suite and strict static analysis. You can run all of our checks via a composer script:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

License

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

GitHub

https://github.com/worksome/request-factories
Comments
Mock HTTP requests on the server side in your PHP unit tests

HTTP Mock for PHP Mock HTTP requests on the server side in your PHP unit tests. HTTP Mock for PHP mocks the server side of an HTTP request to allow in

Jun 28, 2022
This plugin adds basic HTTP requests functionality to Pest tests, using minicli/curly

Curly Pest Plugin This plugin adds basic HTTP requests functionality to Pest tests, using minicli/curly. Installation composer require minicli/pest-pl

Mar 24, 2022
‚õĹ Pest plugin to test Laravel applications powered by Octane.

‚õĹ Laravel Octane (Pest Plugin) Pest plugin to test Laravel applications powered by Octane. Install Via Composer composer require --dev cerbero/pest-pl

Apr 5, 2022
A sample RESTful API in Laravel with PHPunit test.

Laravel PHP Framework URL | URI | Action |

Jul 11, 2020
Patchstack Test task Laravel&Vue CRUD

Patchstack Test Task - Laravel & Vue CRUD SPA Written with Laravel and Vue2 using mix. Installation Clone this repository Run "composer update" comman

Jun 20, 2022
:heavy_check_mark: PHP Test Framework for Freedom, Truth, and Justice
:heavy_check_mark: PHP Test Framework for Freedom, Truth, and Justice

Kahlan is a full-featured Unit & BDD test framework a la RSpec/JSpec which uses a describe-it syntax and moves testing in PHP one step forward. Kahlan

Jun 22, 2022
Event driven BDD test framework for PHP
Event driven BDD test framework for PHP

The highly extensible, highly enjoyable, PHP testing framework. Read more at peridot-php.github.io or head over to the wiki. Building PHAR Peridot's p

Jun 13, 2022
BDD test framework for PHP

BDD test framework for PHP, inspired by Jasmine and RSpec. Features a familiar syntax, and a watch command to automatically re-run specs during develo

Feb 11, 2022
vfsStream is a stream wrapper for a virtual file system that may be helpful in unit tests to mock the real file system. It can be used with any unit test framework, like PHPUnit or SimpleTest.

vfsStream vfsStream is a stream wrapper for a virtual file system that may be helpful in unit tests to mock the real file system. It can be used with

Jun 20, 2022
PHPUnit Application Architecture Test

PHPUnit Application Architecture Test Idea: write architecture tests as well as feature and unit tests Installation Install via composer composer requ

Feb 27, 2022
A Composer script to run a 'test' or 'spec' Composer script against multiple PHP versions.

composer-multitest composer-multitest is a Composer script that runs a test or spec Composer script against multiple PHP versions managed by PHPBrew o

Aug 27, 2019
The Phoronix Test Suite is the most comprehensive testing and benchmarking platform
The Phoronix Test Suite is the most comprehensive testing and benchmarking platform

The Phoronix Test Suite is the most comprehensive testing and benchmarking platform available for Linux, Solaris, macOS, Windows, and BSD operating systems.

Jul 2, 2022
Prevent none-test output in your Pest tests.
Prevent none-test output in your Pest tests.

Pest Plugin Silence Often, when writing tests, we echo and dump test code to debug and check everything is working correctly. It can be easy to forget

Feb 23, 2022
PHP Test Generator - A CLI tool which generates unit tests

This project make usages of PHPStan and PHPParser to generate test cases for a given PHP File.

May 30, 2022
Few additional testing assertions for Laravel views

Laravel View Test Assertions Few additional assertions for testing Laravel views. Why Laravel has well established and documented way of testing reque

Jun 12, 2022
Real-world Project to learning about Unit Testing/TDD with Laravel for everybody

KivaNote - a Laravel TDD Sample Project Let me introduce you to KivaNote, a simple real-world application using Laravel to show you how the TDD & Unit

May 27, 2022
Package for unit testing Laravel form request classes
Package for unit testing Laravel form request classes

Package for unit testing Laravel form request classes. Why Colin DeCarlo gave a talk on Laracon online 21 about unit testing Laravel form requests cla

May 11, 2022
Wraps your Pest suite in a Laravel application instance, allowing global use of the framework in tests.

Pest Larastrap Plugin This is currently a highly experimental project and is subject to large pre-release changes. Pest PHP is an awesome PHP testing

Jan 6, 2022