CakePHP Fixture Factories

An alternative approach to create test fixtures.

The CakePHP Fixture Factories plugin

increases the speed of your tests,
reduces the effort of writing and maintaining tests,
enhances the readability of your tests: you get what you seed in your test, tests do not share test fixtures,
offers to manage your test DB schema with the same migrations you use on your regular DB.

You will never have to create, maintain or declare any test fixtures again.

Example:

you need to create three users belonging to a group of users with a certain permission some-permission? Once your UserFactory, GroupFactory and PermissionFactory are baked, you can create your users by calling:

$users = UserFactory::make(3)->with('Groups.Permissions', ['name' => 'some-permission'])->getEntity().

Or move that logic in your UserFactory by creating your own withPermission method, and call

$users = UserFactory::make(3)->withPermission('some-permission')->getEntity().

Creating or persisting test data is made ridiculously simple, and your tests get readable.

Given your preferred style, you can either use static factory instance getter as above or embeds FactoryAwareTrait in your tests :

$users = $this->getFactory('User', 3)->withPermission('some-permission')->getEntity().

Installation

For CakePHP 4.x:

composer require --dev vierge-noire/cakephp-fixture-factories "^2.0"

For CakePHP 3.x:

composer require --dev vierge-noire/cakephp-fixture-factories "^1.0"

Note that PHP 7.0 is supported up to v1.1.x only.

Setup

To be able to bake your factories or to replace automatically the test listeners in your phpunit file, load the CakephpFixtureFactories plugin in your src/Application.php file:

protected function bootstrapCli(): void
{
    // Load more plugins here
    $this->addPlugin('CakephpFixtureFactories');
}

and set up the test listener in phpunit.xml.dist by running:

bin/cake fixture_factories_setup

You can specify a plugin (-p) and a file (-f) if it differs from phpunit.xml.dist.

Take full advantage of the Phinx migrations in order to maintain the schema of your test DB. This is optional, but highly recommended.

The CakePHP Test Migrator package will assist you in doing this very simply.

Baking Fixture Factories

Load the plugin and create all your factories in one command line.

bin/cake bake fixture_factory -h

Inside Fixture Factories

What the fixture factories are. Have a careful look at this section to understand the concept of the package.

Note that the package is compatible with the traditional CakePHP test fixtures. You may continue using them along with the Fixture Factories, these will work just as before.

Creating Test Fixtures

In this section, we will see how to create test fixtures.

Example:

Persisting five articles having each three different authors, each with different addresses, in different cities, but all located in Kenya:

$article = ArticleFactory::make(5)->with('Authors[3].Address.City.Country', ['name' => 'Kenya'])->persist();

On the command line:

Factories can also conveniently populate your database in order to test your application on the browser. The following command will persist 5 articles, each with 3 irish authors, considering that the ArticleFactory class features a withThreeIrishAuthors() method:

bin/cake fixture_factories_persist Authors -n 5 -m withThreeIrishAuthors

The option --dry-run or -d will display the output without persisting. The option -c will persist in the connection provided (default is test). The option -w will create associated fixtures.

The fixture_factories_persist command is featured on CakePHP 4 only (open to contribution for CakePHP 3).

Scenarios:

You can create scenarios that will persist a multitude of test fixtures. This can be useful to seed your test database with a reusable set of data.

Use the CakephpFixtureFactories\Scenario\ScenarioAwareTrait in your test and load your scenario with the loadFixtureScenario() method. You can either provide the fully qualified name of the scenario class, or place your scenarios under the App\Test\Scenario namespace.

Scenarios should implement the CakephpFixtureFactories\Scenario\FixtureScenarioInterface class. This test provides an example on how to use scenarios.

Querying the database

Because the fixture factories are closely related to the database, the package provides two methods to conveniently run queries. Both methods will by-pass the beforeFind event, enabling the direct inspection of your test database.

ArticleFactory::find()

This method will return a query on the table related to the given factory. It takes as input the same parameters as the classic table find() method.

ArticleFactory::count()

This method will return the number of entries in the table of the given factory.

Test Lifecycle

The only step performed by the package's test suite is to truncate dirty tables before each test. More documentation on the management of the test database may be found in the cakephp test suite light documentation.

Authors

Juan Pablo Ramirez
Nicolas Masson

Additional resources

Here is a presentation held at the CakePHP online Meetup on 29th April 2020.

Here is the CakeFest 2020 presentation

Here is a serie of videos on the present package.

Contribute

The development branch is named next (CakePHP 4.x based). Feel free to send us your pull requests!

Support

You like our work?

License

The CakePHPFixtureFactories plugin is offered under an MIT license.

Licensed under The MIT License Redistributions of files must retain the above copyright notice.

dreamingmind / cakephp-fixture-factories Goto Github PK