Fabrica handles the definition and creation of objects for use in testing.
Coupled with its Doctrine integration, Fabrica allows you to fully test CRUD logic without mocking. See the What Problem Does it Solve? page for a full explanation.
composer require noj/fabrica --dev
First initialise Fabrica somewhere within your test suite. For PHPUnit, this can be done using the bootstrap option:
<?php
require 'vendor/autoload.php';
Fabrica::loadFactories([__DIR__ . '/factories']);Assuming that you have a User entity, create a new factory factories/UserFactory.php:
Fabrica::define(User::class, function () {
return [
'username' => 'user123',
'firstName' => 'Test',
'lastName' => 'User',
];
});Now within your test, you can create a new User instance:
$user = Fabrica::create(User::class);
// Check properties have been set
assertEquals('user123', $user->username);
assertEquals('Test', $user->firstName);
assertEquals('User', $user->lastName);If your entity's properties are only accessible through setters then you can use the @ syntax to call methods instead:
Fabrica::define(User::class, function () {
return [
'@setUsername' => 'user123',
'@setFirstName' => 'Test',
'@setLastName' => 'User',
];
});Given that a value is an array, you can indicate that you wish the method to be called for each item using the multiple times suffix (*):
'@addPermission*' => ['USER', 'ADMIN'],You can override any default values when creating your entity:
/// UserFactory.php
Fabrica::define(User::class, function () {
return [
'username' => 'user123',
'firstName' => 'Test',
'lastName' => 'User',
'@setAge' => 47,
];
});
/// UserTest.php
$user = Fabrica::create(User::class, function () {
return [
'firstName' => 'Another',
'@setAge' => 24,
];
});
assertEquals('user1223', $user->username);
assertEquals('Another', $user->firstName);
assertEquals('User', $user->lastName);
assertEquals(24, $user->getAge());You can create multiple entities like so:
$users = Fabrica::createMany(User::class, 3);You can automatically create related entities. For example, if you have Comment entity that belongs to a User then you can define a factory:
Fabrica::define(Comment::class, function () {
return [
'title' => 'A test comment',
'body' => 'This is a test',
'author' => Fabrica::create(User::class),
];
});Whenever a Comment is created it will have an associated User:
$comment = Fabrica::create(Comment::class);
assertInstanceOf(User::class, $comment->user);
assertEquals('user123', $comment->user->username);You can also define the inverse side of the relation. For example, you can define that each created User should have an associated Comment:
Fabrica::define(User::class, function () {
return [
'@setUsername' => 'user123',
'@setFirstName' => 'Test',
'@setLastName' => 'User',
'@addComment' => Fabrica::create(Comment::class)
];
});You can create multiple child relations:
Fabrica::define(User::class, function () {
return [
'comments' => Fabrica::createMany(Comment::class, 3),
// or if you have a setter method, use the `*` suffix to call the method
// once for each element of the array
'@addComment*' => Fabrica::createMany(Comment::class, 3),
];
});Will create a User with 3 Comments.
If the entity has a property that depends on the relation then you can define this like so:
Fabrica::define(Comment::class, function () {
return [
'user' => Fabrica::create(User::class),
'userFirstName' => Fabrica::property('user.firstName'),
];
});You can also override properties of nested relations when creating an entity:
$comment = Fabrica::create(Comment::class, function () {
return [
'author.firstName' => 'John'
];
});
assertEquals('user123', $comment->user->username);
assertEquals('John', $comment->user->firstName);For a single entity of a one-to-many relation:
$user = Fabrica::create(User::class, function () {
return [
'comments.1.title' => 'Only the 2nd comment has this title'
];
});
assertEquals('A test comment', $user->comments[0]->title);
assertEquals('Only the 2nd comment has this title', $user->comments[1]->title);Or even every entity:
$user = Fabrica::create(User::class, function () {
return [
'comments.*.title' => 'Each comment now has this title'
];
});
foreach ($user->comments as $comment) {
assertEquals('Each comment now has this title', $comment->title);
}Rather than always having to pass overrides when creating entities, you can define different types of entities:
Fabrica::define(User::class, function () {
return [
'username' => 'bannedUser',
'firstName' => 'Test',
'lastName' => 'User',
];
})->type('banned');
$normalUser = Fabrica::create(User::class);
$bannedUser = Fabrica::create(User::class, 'banned');
$bannedUser2 = Fabrica::create(User::class, 'banned', function () {
return ['firstName' => 'banned'];
});If a sub-type shares attributes with the parent-type then you can specify that the factory extends from it:
Fabrica::define(User::class, function () {
return [
'username' => 'bannedUser'
];
})->type('banned')->extends(User::class);
$bannedUser = Fabrica::create(User::class, 'banned');
assertEquals('bannedUser', $bannedUser->username);
assertEquals('Test', $bannedUser->firstName);
assertEquals('User', $bannedUser->lastName);You can also extend from a sub-type:
Fabrica::define(User::class, function () {
return [
'permanent' => true
];
})->type('permaBanned')->extends(User::class, 'banned);Fabrica ships with a Doctrine adapter that will automatically persist your entities on creation. Simply configure the store in your bootstrap file:
Fabrica::setStore(new DoctrineStore($entityManager));Where the EntityManager comes from and how it is configured may depend on your application.
Fabrica provides a simple way of creating an annotation backed EntityManager using in-memory SQLite if that meets your requirements:
$entityManager = \Noj\Fabrica\Adapter\Doctrine\EntityManagerFactory::createSQLiteInMemory([__DIR__ . '/path/to/entities']);
Fabrica::setStore(new DoctrineStore($entityManager));Most likely you will want to reset the state of your database before each test runs. There are 2 ways of doing this:
- If you are using PHPUnit 7.5 or above then you can add the following to your
phpunit.xmlwhich will reset your database between each test:<extensions> <extension class="Noj\Fabrica\Adapter\Doctrine\PHPUnit\RefreshDatabase" /> </extensions>
- If you are using a lower version of PHPUnit or you would only like to create the database for specific tests then you can add the trait to your test class:
class MyTest extends TestCase { use \Noj\Fabrica\Adapter\Doctrine\PHPUnit\NeedsDatabase; }
Fabrica ships with a set of PHPUnit assertions for validating the state of the database during a test.
class MyTest extends TestCase
{
use \Noj\Fabrica\Adapter\Doctrine\PHPUnit\DatabaseAssertions;
}This provides the following assertions:
assertDatabaseContainsEntity(string $class, array $criteria = [])assertDatabaseContainsEntities(string $class, int $amount, array $criteria = [])assertDatabaseContainsExactlyOneEntity(string $class, array $criteria = [])assertDatabaseDoesNotContainEntity(string $class, array $criteria = [])
Note: If you are using NeedsDatabase described above then the assertions are already included.
Example usage:
public function test_it_creates_a_user()
{
(new UserCreator)->create('test');
self::assertDatabaseContainsEntity(User::class, ['username' => 'test'])'
}Fabrica can be configured with a faker instance to help generate fake data in your entity definitions.
$faker = \Faker\Factory::create();
Fabrica::addDefineArgument($faker);You will then receive the faker instance in the define callback:
use Faker\Generator as Faker;
Fabrica::define(User::class, function (Faker $faker) {
return [
'firstName' => $faker->firstName,
'lastName' => $faker->lastName,
'email' => $faker->email,
];
});
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent