Going Deeper with Factories Through Factory States

Published on by

Going Deeper with Factories Through Factory States image

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.

Paul Redmond photo

Staff writer at Laravel News. Full stack web developer and author.

Cube

Laravel Newsletter

Join 40k+ other developers and never miss out on new tips, tutorials, and more.

image
Paragraph

Manage your Laravel app as if it was a CMS – edit any text on any page or in any email without touching Blade or language files.

Visit Paragraph
Laravel Forge logo

Laravel Forge

Easily create and manage your servers and deploy your Laravel applications in seconds.

Laravel Forge
Tinkerwell logo

Tinkerwell

The must-have code runner for Laravel developers. Tinker with AI, autocompletion and instant feedback on local and production environments.

Tinkerwell
No Compromises logo

No Compromises

Joel and Aaron, the two seasoned devs from the No Compromises podcast, are now available to hire for your Laravel project. ⬧ Flat rate of $7500/mo. ⬧ No lengthy sales process. ⬧ No contracts. ⬧ 100% money back guarantee.

No Compromises
Kirschbaum logo

Kirschbaum

Providing innovation and stability to ensure your web application succeeds.

Kirschbaum
Shift logo

Shift

Running an old Laravel version? Instant, automated Laravel upgrades and code modernization to keep your applications fresh.

Shift
Bacancy logo

Bacancy

Supercharge your project with a seasoned Laravel developer with 4-6 years of experience for just $2500/month. Get 160 hours of dedicated expertise & a risk-free 15-day trial. Schedule a call now!

Bacancy
Lucky Media logo

Lucky Media

Bespoke software solutions built for your business. We ♥ Laravel

Lucky Media
Lunar: Laravel E-Commerce logo

Lunar: Laravel E-Commerce

E-Commerce for Laravel. An open-source package that brings the power of modern headless e-commerce functionality to Laravel.

Lunar: Laravel E-Commerce
LaraJobs logo

LaraJobs

The official Laravel job board

LaraJobs
Larafast: Laravel SaaS Starter Kit logo

Larafast: Laravel SaaS Starter Kit

Larafast is a Laravel SaaS Starter Kit with ready-to-go features for Payments, Auth, Admin, Blog, SEO, and beautiful themes. Available with VILT and TALL stacks.

Larafast: Laravel SaaS Starter Kit
SaaSykit: Laravel SaaS Starter Kit logo

SaaSykit: Laravel SaaS Starter Kit

SaaSykit is a Laravel SaaS Starter Kit that comes with all features required to run a modern SaaS. Payments, Beautiful Checkout, Admin Panel, User dashboard, Auth, Ready Components, Stats, Blog, Docs and more.

SaaSykit: Laravel SaaS Starter Kit
Rector logo

Rector

Your partner for seamless Laravel upgrades, cutting costs, and accelerating innovation for successful companies

Rector

The latest

View all →
Microsoft Clarity Integration for Laravel image

Microsoft Clarity Integration for Laravel

Read article
Apply Dynamic Filters to Eloquent Models with the Filterable Package image

Apply Dynamic Filters to Eloquent Models with the Filterable Package

Read article
Property Hooks Get Closer to Becoming a Reality in PHP 8.4 image

Property Hooks Get Closer to Becoming a Reality in PHP 8.4

Read article
Asserting Exceptions in Laravel Tests image

Asserting Exceptions in Laravel Tests

Read article
Reversible Form Prompts and a New Exceptions Facade in Laravel 11.4 image

Reversible Form Prompts and a New Exceptions Facade in Laravel 11.4

Read article
Basset is an alternative way to load CSS & JS assets image

Basset is an alternative way to load CSS & JS assets

Read article