by laracasts

laracasts / TestDummy

Easy factories for PHP integration testing.

462 Stars 79 Forks Last release: about 2 months ago (2.5) MIT License 241 Commits 36 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

TestDummy Build Status SensioLabsInsight

TestDummy makes the process of preparing factories (dummy data) for your integration tests as easy as possible. As easy as...

Build a Post model with dummy attributes.

use Laracasts\TestDummy\Factory;

$post = Factory::build('Post');

If we then do

, this might return:
array(4) {
  string(21) "The Title of the Post"
  string(1) "5"
  string(226) "Iusto qui optio et iste. Cumque aliquid et omnis enim. Nesciunt ad esse a reiciendis expedita quidem veritatis. Nostrum repellendus reiciendis distinctio amet sapiente. Eum molestias a recusandae modi aut et adipisci corrupti."
  string(19) "2014-03-02 11:05:48"

Build a post, but override the default title.

use Laracasts\TestDummy\Factory;

$post = Factory::build('Post', ['title' => 'Override Title']);

Again, when cast to an array...

array(4) {
  string(14) "Override Title"
  string(1) "5"
  string(254) "In eos porro qui est rerum possimus voluptatem non. Repudiandae eaque nostrum eaque aut deleniti possimus quod minus. Molestiae commodi odit sunt dignissimos corrupti repudiandae quibusdam quo. Autem maxime tenetur autem corporis aut quis sint occaecati."
  string(19) "2013-06-24 10:01:30"

Build an array of attributes for the model.

$post = Factory::attributesFor('Post');

The difference between

is that the former will return an instance of the given model type (such as
). The latter will simply return an array of the generated attributes, which can be useful in some situations.

Build and persist a song entity.

use Laracasts\TestDummy\Factory;

$song = Factory::create('Song');

Create and persist a comment three times.

use Laracasts\TestDummy\Factory;


In effect, this will give you three rows in your

table. If that table has relationships (such as an owning Post), those related rows will be created with dummy data as well.


Step 1: Install

Pull this package in through Composer, just like any other package.

"require-dev": {
    "laracasts/testdummy": "~2.0"

Step 2: Create a Factories File

TestDummy isn't magic. You need to describe the type of data that should be generated.

Within a

directory, you may create any number of PHP files that will automatically be loaded by TestDummy. Why don't you start with a generic

Each factory file you create will automatically have access to two variables:

  • $factory
  • $faker

is the function that you'll use to define new sets of data, such as the makeup of a Post or Album.
$factory('Album', [
    'name' => 'Rock or Bust',
    'artist' => 'AC/DC'

Think of this as your definition for any future generated albums - like when you do this:

use Laracasts\TestDummy\Factory;

$album = Factory::create('Album');


You probably won't want to hardcode strings for your various factories. It would be easier and faster to use random data. TestDummy pulls in the excellent Faker library to assist with this.

In fact, any files in your

directory will automatically have access to a
object that you may use. Here's an example:
$factory('Comment', [
    'body' => $faker->sentence

Now, each time you generate a new comment, the

field will be set to a random sentence. Refer to the Faker documentation for a massive list of available fakes.


If you wish, TestDummy can automatically generate your relationship models, as well. You just need to let TestDummy know the type of its associated model. TestDummy will then automatically build and save that relationship for you!

Using the

example from above, it stands to reason that a comment belongs to a user, right? Let's set that up:
$factory('Comment', [
    'user_id' => 'factory:User',
    'body' => $faker->sentence

That's it! Notice the special syntax here: "factory:", followed by the name of the associated class/model.

To illustrate this with one more example, if a song belongs to an album, and an album belongs to an artist, then we can easily represent this:

$factory('App\Song', [
    'album_id' => 'factory:App\Album',
    'name' => $faker->sentence

$factory('App\Album', [ 'artist_id' => 'factory:App\Artist', 'name' => $faker->word ]);

$factory('App\Artist', [ 'name' => $faker->word ]);

So here's the cool thing: this will all work recursively. In translation, if you do...

use Laracasts\TestDummy\Factory;

$song = Factory::create('App\Song');

...then not only will TestDummy build and persist a song to the database, but it'll also do the same for the related album, and its related artist. Nifty!

Custom Factories

So far, you've learned how to generate data, using the name of the class, like

. However, sometimes, you'll want to define multiple types of users for the purposes of testing.

While it's true that you can use overrides, like this:

Factory::create('App\User', ['role' => 'admin']);

...if this is something that you'll be doing often, create a custom factory, like so:

// A generic factory for users...

$factory('App\User', [ 'username' => $faker->username, 'password' => $faker->password, 'role' => 'member' ]);

// And a custom one for administrators

$factory('App\User', 'admin_user', [ 'username' => $faker->username, 'password' => $faker->password, 'role' => 'admin' ]);

In the code snippet above, you're already familiar with the first example. For the second one, notice that we've added a "short name", or identifier for this special type of user factory. Now, whenever you want to quickly generate an admin user, you may do:

use Laracasts\TestDummy\Factory;

$adminUser = Factory::create('admin_user');

Defining with Closures

Alternatively, you may pass a closure as the second argument to the

method. This can be useful for situations where you need a bit more control over the values that you assign to each attribute. Here's an example:
$factory('App\Artist', function($faker) {
    $name = sprintf('Some Band Named %s', $faker->word);

return [
    'name' => $name


Of course, just be sure to return an array from this closure. If you don't, an exception will be thrown.

Step 3: Setup

When testing against a database, it's recommended that each test works with the exact same database environment and structure. That way, you can protect yourself against false positives. An SQLite database (maybe even one in memory) is a good choice in these cases.

public function setUp()



Or, if a DB in memory isn't possible, to save a bit of time, a helper

class is included with this package. If you extend it, before each test, your test DB will be migrated (if necessary), and all DB modifications will be channelled through a transaction, and then rolled back on
. This will give you a speed boost, and ensure that all tests start with the same database structure.
use Laracasts\TestDummy\DbTestCase;

class ExampleTest extends DbTestCase {

/** @test */
function it_does_something()
    // Before each test, your database will be rolled back


Step 4: Write Your Tests

You're all set to go now. Start testing! Here's some code to get you started. Assuming that you have a

model created...
use Laracasts\TestDummy\Factory;

$comment = Factory::create('Comment');

This will create and save both a

, as well as a
record to the database.

Or, maybe you need to write a test to ensure that, if you have three songs with their respective lengths, when you call a

method on the owning
model, it will return the correct value. That's easy!
// create three songs, and explicitly set the length
Factory::times(3)->create('Song', ['length' => 200]);

$album = Album::first(); // this will be created once automatically.

$this->assertEquals(600, $album->getTotalLength());

Now, of course, just make sure that you've registered a definition for a

in one of your factory files, and you're good to go!
// tests/factories/factories.php

$factory('Song', [ 'album_id' => 'factory:Album', 'name' => $faker->sentence ]);

$factory('Album', [ 'name' => $faker->sentence ]);


How do I specify a different factories folder?

Easy. Before your tests run, add:

Factory::$factoriesPath = 'app/tests/factories';

Now, TestDummy will look for your registered factories in the


I want to control how my models are built and saved...

Okay, just create your own implementation of

. This contract is composed of a few methods that you'll need to implement.

Once you have your implementation, before your tests run, add:

Factory::$databaseProvider = new MyCustomBuilder;

And that's it! Now, whenever you generate and save an entity, TestDummy will reference your custom implementation.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.