AliceBundle
A Symfony bundle to manage fixtures with nelmio/alice and
fzaninotto/Faker.
The database support is done in FidryAliceDataFixtures. Check this
project to know which database/ORM is supported.
Warning: this is the documentation for HautelookAliceBundle 2.0. If you want to check the documentation for 1.x, head
this way.
When to use this bundle?
HautelookAliceBundle changed a lot, it first was acting as a simple bundle for nelmio/alice,
it then started to ship some additional features to enrich it.
HautelookAliceBundle 1.x was the first milestone reaching a certain level of maturity in its usage:
- Easily load a set of fixtures from a command
- Being able to define different sets of fixtures for multiple environments
- Customize the data generation with custom Faker providers
- Customize the loading behaviour with processors
HautelookAliceBundle 2.x changes a lot, although not so much. In 1.x, a lot of complexity was brought in the bundle
due to nelmio/alice 2.x limitations and were at best workarounds (like the lack of handling of circular references).
A lot of that complexity has been pushed back to nelmio/alice 3.x which has a much more flexible design. As a result:
- nelmio/alice 3.x allows you to easily create PHP objects with random data in an elegant way
- FidryAliceDataFixtures is a persistence layer for nelmio/alice 3.x. If you need to persist the loaded objects, it is the package you need. It provides you the flexibility to be able to purge the data between each loadings or wrap the loading in a transaction for your tests for example to simply rollback once the test is finished instead of calling an expansive purge.
- hautelook/alice-bundle 2.x provides high-level features including fixtures discovery (find the appropriate files and load them), and helpers for database testing. If you just need to load specific sets of files for your tests, FidryAliceDataFixtures is enough.
Documentation
- Install
- Basic usage
- Database testing
- Advanced usage
- Custom Faker Providers
- Custom Alice Processors
- Resources
Installation
With Symfony Flex (recommended):
# If you do not have Doctrine installed yet:
composer require doctrine-orm
composer require --dev hautelook/alice-bundle
You're ready to use AliceBundle, and can jump to the next section!
Without Flex you will have to install doctrine/orm
and register the bundles accordingly in app/AppKernel.php
or
wherever your Kernel class is located:
<?php
// app/AppKernel.php
public function registerBundles()
{
$bundles = [
new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),
// ...
new Doctrine\Bundle\DoctrineBundle\DoctrineBundle(),
];
if (in_array($this->getEnvironment(), ['dev', 'test'])) {
//...
$bundles[] = new Nelmio\Alice\Bridge\Symfony\NelmioAliceBundle();
$bundles[] = new Fidry\AliceDataFixtures\Bridge\Symfony\FidryAliceDataFixturesBundle();
$bundles[] = new Hautelook\AliceBundle\HautelookAliceBundle();
}
return $bundles;
}
Configure the bundle to your needs, for example:
# config/packages/dev/hautelook_alice.yaml
hautelook_alice:
fixtures_path: 'fixtures' # Path to which to look for fixtures relative to the project directory or the bundle path. May be a string or an array of strings.
root_dirs:
- '%kernel.root_dir%'
- '%kernel.project_dir%'
If you are using a non-flex architecture, you may want to use Resources/fixtures
instead of fixtures
.
Basic usage
Assuming you are using Doctrine, make sure you
have the doctrine/doctrine-bundle
and
doctrine/data-fixtures
packages installed.
Then create a fixture file in one of the following location:
fixtures
if you are using flexapp/Resources/fixtures
if you have a non-flex bundle-less Symfony applicationsrc/AppBundle/Resources/fixtures
or any bundle under which you want to place the fixtures
# fixtures/dummy.yaml
App\Entity\Dummy:
dummy_{1..10}:
name: <name()>
related_dummy: '@related_dummy*'
# fixtures/related_dummy.yaml
App\Entity\RelatedDummy:
related_dummy_{1..10}:
name: <name()>
Then simply load your fixtures with the doctrine command php bin/console hautelook:fixtures:load
.
If you want to load the fixtures of a bundle only, do php bin/console hautelook:fixtures:load -b MyFirstBundle -b MySecondBundle
.
See more.
Next chapter: Advanced usage
Database testing
The bundle provides nice helpers, inspired by Laravel,
dedicated for database testing: RefreshDatabaseTrait
, ReloadDatabaseTrait
and RecreateDatabaseTrait
.
These traits allow to easily reset the database in a known state before each PHPUnit test: it purges the database then loads
the fixtures.
They are particularly helpful when writing functional tests
and when using Panther.
To improve performance, RefreshDatabaseTrait
populates the database only one time, then wraps every tests in a
transaction that will be rolled back at the end after its execution (regardless of if it's a success or a failure):
<?php
namespace App\Tests;
use Hautelook\AliceBundle\PhpUnit\RefreshDatabaseTrait;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
class NewsTest extends WebTestCase
{
use RefreshDatabaseTrait;
public function postCommentTest()
{
$client = static::createClient(); // The transaction starts just after the boot of the Symfony kernel
$crawler = $client->request('GET', '/my-news');
$form = $crawler->filter('#post-comment')->form(['new-comment' => 'Symfony is so cool!']);
$client->submit($form);
// At the end of this test, the transaction will be rolled back (even if the test fails)
}
}
Sometimes, wrapping tests in transactions is not possible. For instance, when using Panther, changes to the database
are made by another PHP process, so it wont work.
In such cases, use the ReloadDatabase
trait. It will purge the DB and load fixtures before every tests:
<?php
namespace App\Tests;
use Hautelook\AliceBundle\PhpUnit\ReloadDatabaseTrait;
use Symfony\Component\Panther\PantherTestCase;
class NewsTest extends PantherTestCase // Be sure to extends KernelTestCase, WebTestCase or PantherTestCase
{
use ReloadDatabaseTrait;
public function postCommentTest()
{
$client = static::createPantherClient();// The database will be reset after every boot of the Symfony kernel
$crawler = $client->request('GET', '/my-news');
$form = $crawler->filter('#post-comment')->form(['new-comment' => 'Symfony is so cool!']);
$client->submit($form);
}
}
This strategy doesn't work when using Panther, because the changes to the database are done by another process, outside
of the transaction.
Both traits provide several configuration options as protected static properties:
self::$manager
: The name of the Doctrine manager to useself::$bundles
: The list of bundles where to look for fixturesself::$append
: Append fixtures instead of purgingself::$purgeWithTruncate
: Use TRUNCATE to purgeself::$shard
: The name of the Doctrine shard to useself::$connection
: The name of the Doctrine connection to use
Use them in the setUpBeforeClass
method.
<?php
namespace App\Tests;
use Hautelook\AliceBundle\PhpUnit\RefreshDatabaseTrait;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
class NewsTest extends WebTestCase
{
use RefreshDatabaseTrait;
public static function setUpBeforeClass()
{
self::$append = true;
}
// ...
}
Finally, if you're using in memory SQLite for your tests, use RecreateDatabaseTrait
to create the database schema "on the fly":
```php
<?php
namespace App\Tests;
use Hautelook\AliceBundle\PhpUnit\RecreateDatabaseTrait;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
class NewsTest extends WebTestCase
{
use RecreateDatabaseTrait;
// ...
}
```
Resources
- Behat extension: AliceBundleExtension
- Bundle for generating AliceBundle compatible fixtures directly from Doctrine entities: AliceGeneratorBundle
- Upgrade guide
- Changelog
Credits
This bundle was originaly developped by Baldur RENSCH and HauteLook. It is now maintained by Théo FIDRY.
License
Copyright (c) 2013 HauteLook
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
Make tree of files readable in advanced usage doc (#505)
By web-flow, 11 months ago
-
Fix faker provider auto-configuration (#504)
By web-flow, 11 months ago
-
Remove `final` keyword from DoctrineOrmLoader (#502)
By web-flow, 1 year ago
-
Add funding file
By web-flow, 1 year ago
-
Update advanced-usage.md (#500)
By web-flow, 1 year ago
-
Use correct configuration key in deprecation message (#499)
By web-flow, 1 year ago
-
Add the --no-bundles option
By theofidry, 1 year ago
-
Fix overriding custom path fixtures root dir (#494)
By theofidry, 1 year ago
-
Address deprecations from persistence lib (#493)
By theofidry, 1 year ago
-
Enable support for Symfony 5 (#487)
By theofidry, 1 year ago
-
Add support for doctrine bundle 2.x (#485)
By theofidry, 1 year ago
-
Fix the builds (#488)
By theofidry, 1 year ago
-
Remove final from DoctrineOrmLoadDataFixturesCommand (#473)
By theofidry, 1 year ago
-
Improved docs about multiple fixtures paths (#470)
By theofidry, 1 year ago
-
Allow multiple fixture paths during bundle configuration (#467)
By theofidry, 2 years ago
-
Do not rollback if there are no active transactions (#466)
By theofidry, 2 years ago
-
Update Symfony decorator configuration (#458)
By theofidry, 2 years ago
-
Update finder folders for PHP-CS-Fixer (#451)
By theofidry, 2 years ago
-
Add a trait to recreate the database schema (#447)
By theofidry, 2 years ago
-
Fix root node deprecation in symfony/config > 4.1 (#448)
By theofidry, 2 years ago
-
Make the Phpunit trait compatible with WebTestCase (#441)
By theofidry, 2 years ago
-
Make loaded fixture available (#439)
By theofidry, 2 years ago
-
Remove the theofidry/alice-bundle-extension installation suggestion (#438)
By theofidry, 2 years ago
-
Add traits to purge the DB and load fixtures in PHPUnit tests (#432)
By theofidry, 2 years ago
-
Fix shortcut value for manager option (#435)
By theofidry, 2 years ago
-
Remove dead code (#431)
By theofidry, 2 years ago
-
Add DoctrineBundle to the dependencies (#428)
By theofidry, 2 years ago
-
Fix test with specific version (#430)
By theofidry, 2 years ago
-
Remove the dependency to symfony/symfony (#429)
By theofidry, 2 years ago
-
Fix Travis (#426)
By theofidry, 2 years ago