Going Deeper with Factories Through Factory States

Going Deeper with Factories Through Factory States

I suspect that if you are familiar with Laravel that you might use model factories and possibly even factory states in your application development. The documentation shows you the mechanics of using factories to seed and create test data, but there are a couple of guiding thoughts to using factories with your models effectively that I’d like to consider.

The following are some approaches I’ve been considering in more efficiently using factory states:

First, creating factories with static values instead of using Faker for everything.

Secondly, your factories should only create the simplest set of attributes necessary to create an instance of a model.

Using Static Data Instead of Faker

I am not suggesting that using faker is wrong, but instead, that static values can make testing data more evident than randomized data.

Consider the following User factory:

$factory->define(App\User::class, function (Faker $faker) {
    return [
        'name' => $faker->name,
        'email' => $faker->unique()->safeEmail,
        'password' => '$2y$10$TKh8H1.PfQx37YgCzwiKb.KjNyWgaHb9cbcoQgdIVFlYg7B77UdFm', // secret
        'remember_token' => str_random(10),
    ];
});

The code example is the user factory that ships with Laravel 5.6. The factory definition has nothing with it that I want to criticize—it’s perfectly fine. However, I would like you to consider that when you run your test suite, new values get generated each time:

// First test run
array:5 [
  "name" => "Troy Miller III"
  "email" => "orrin93@example.org"
  "updated_at" => "2018-04-09 01:35:38"
  "created_at" => "2018-04-09 01:35:38"
  "id" => 1
]

// Second test run
array:5 [
  "name" => "Mr. Zachariah McGlynn"
  "email" => "lturcotte@example.net"
  "updated_at" => "2018-04-09 01:35:41"
  "created_at" => "2018-04-09 01:35:41"
  "id" => 1
]

You might feel that this randomization of test data is a good thing, and that it makes your test suite more robust. That’s a valid argument, but consider the accompanying test you need to write to verify the data:

public function testWelcomeMessageTest()
{
    $user = factory('App\User')->create();

    $response = $this->get('/');
    $response->assertSeeText('Welcome '.$user->name);
}

I want to emphasize again that there’s nothing inherently wrong with this test, but I feel like there’s extra “magic” involved that takes a little parsing in your brain. I am using a variable to assert that the test is passing, instead of a hard-coded assertion that makes the test slightly more readable in my mind.

Consider the following factory:

$factory->define(App\User::class, function (Faker $faker) {
    return [
        'name' => 'Example User,
        'email' => 'example@example.com',
        // ...
    ];
});

The hard-coded name and email are a subtle change, but now my test might look like this:

public function testWelcomeMessageTest()
{
    factory('App\User')->create();

    $response = $this->get('/');
    $response->assertSeeText('Welcome Example User');
}

Another approach is to use a factory with dynamic data and override what you intend to test:

public function testWelcomeMessageTest()
{
    factory('App\User')->create([
        'name' => 'Example User',
    ]);

    $response = $this->get('/');
    $response->assertSeeText('Welcome Example User');
}

You should do what feels right to you in your applications, but I hope that you at least consider that you don’t have to use faker for everything. In fact, you might have more clarity in your tests as a result of this subtle shift.

If you don’t want to lose the randomness that faker provides, consider using a factory state for your default tests that include some static values:

$factory->define(App\User::class, 'user', function (Faker $faker) {
    return [
        'name' => 'Example User,
        'email' => 'example@example.com',
    ];
});

Then in your tests where you want a basic, static user:

public function testWelcomeMessageTest()
{
    factory('App\User')->states('user')->create();

    $response = $this->get('/');
    $response->assertSeeText('Welcome Example User');
}

The user state represents the base set of attributes your model needs—it’s the minimum viable attributes necessary to create a model.

Minimum Viable Attributes

Creating factories and test data with the minimum amount of data necessary to create a model is a good habit of promoting in your tests. If a field is nullable, or the model has optional relationships, don’t define them in the default factory.

Your tests will more easily help you catch problems with null values and empty relationships. An empty model relationship is often the first state your users will encounter in your applications.

When a column in the database can be nullable, omit it in your factory by default, and then use states to further test models with more than the minimum data required.

Take for example a forum application. When the user first registers, the will not have created any posts yet, or made any comments on others’ posts. That represents the most basic user in your application with the minimum requirement.

Having factory data and faker at your disposal makes it tempting to fill in as much data as possible, but only define the absolutely necessary data in your default model factory states.

Using States For Enhanced Factory Data

Using the example of a forum application, we can define a state for users that have posts, in cases where our tests need more than the minimum required data:

$factory
    ->state(App\User::class, 'with_posts', [])
    ->afterCreatingState(App\User::class, 'with_posts', function ($user, $faker) {
        factory(App\Post::class, 5)->create([
            'user_id' => $user->id,
        ]);
    });

This state doesn’t have any override data so that we can pass an empty array as the third argument instead of a closure. We use the afterCreatingState method to define some posts associated with the user, which we can use in our tests now:

$user = factory('App\User')->states('with_posts')->create();

The biggest drawback to this approach is the hard-coded 5 posts in the afterCreatingState callback. I am just writing pseudo-code, but something like this API might be nice:

$user = factory('App\User')
    ->states('with_posts', ['posts_count' => 5])
    ->create();

And then on the other side of the factory API, something like this:

$factory
    ->state(App\User::class, 'with_posts', [])
    ->afterCreatingState(App\User::class, 'with_posts', function ($user, $faker, $config) {
        factory(App\Post::class, $config->get('posts_count', 5))->create([
            'user_id' => $user->id,
        ]);
    });

Again, this is pseudo code and won’t work! But I wanted to show a couple of ways that this approach could be better. Perhaps this is an area where a package could extend the base factory functionality somehow to achieve this API.

Even with the shortcomings, we still have an excellent declarative way to use a user state with posts.

Other Factory State Approaches

We could also use a trait in the test framework to create a more dynamic state for a user with posts, and any other state we want to the user:

<?php

namespace Tests\factories;

trait UserFactory
{
    public function userWithPosts($config = [])
    {
        $user = factory(\App\User::class)->create();
        $posts = factory(
            \App\Post::class,
            $config['posts_count'] ?? 5
        )->make([
            'user_id' => $user->id,
        ]);

        $user->posts()->saveMany($posts);

        return $user;
    }
}

In your tests that need a user with posts, you would use the following:

namespace Tests\Feature;

use Tests\TestCase;
use Tests\factories;
use Illuminate\Foundation\Testing\RefreshDatabase;

class ExampleTest extends TestCase
{
    use RefreshDatabase;
    use factories\UserFactory;

    public function testWelcomeMessageTest()
    {
        $user = $this->userWithPosts(['posts_count' => 5]);
        // ...
    }
}

I like to define use Tests\factories at the top, and use factories\UserFactory; where I import the trait because it seems more readable to me at a glance that the trait is for factory data. Using a trait requires a fair amount of boilerplate, but is more flexible than our static factory state with the posts count hard-coded at five.

Learn More

You can learn more about factory states in the Laravel documentation. Another excellent source if you want to get more exposure and thought to how factories work is a Ruby gem Factory Bot, specifically the getting started document.

Factories Should be the Bare Minimum is another excellent resource on working with factories, by the author of the aforementioned Factory Bot library.


Filed in: Laravel Tutorials / Model Factories


Newsletter

Join the weekly newsletter and never miss out on new tips, tutorials, and more.

Laravel News Partners

Laravel Jobs

Software Engineer Lead (PHP)
Remote
CivicPlus, LLC
Full-time Senior Web Developer
Detroit, MI
Wayne State University
Senior Software Engineer
Sydney, Australia
FoodByUs
Full Stack Engineer
Remote or Medford, Oregon
Empire Medical
Laravel Developer (fulltime - Dutch only)
Netherlands
Qbixx | Webservices
Full Stack or Back-End Developer
Alexandria, VA; Tallahassee, FL; Orlando, FL
Marketing for Change
Senior Quality Assurance Engineer
Remote
Bisnow Media