2012-12-07 18:44:00 +01:00
# Fixtures
## Overview
2013-09-21 21:24:32 +02:00
You will often find the need to test your functionality with some consistent data.
If we are testing our code with the same data each time,
we can trust our tests to yeild reliable results.
In Silverstripe we define this data via 'fixtures' (so called because of their fixed nature).
The `[api:SapphireTest]` class takes care of populating a test database with data from these fixtures -
all we have to do is define them, and we have a few ways in which we can do this.
2012-12-07 18:44:00 +01:00
## YAML Fixtures
YAML is a markup language which is deliberately simple and easy to read,
2013-09-21 21:24:32 +02:00
so it is ideal for fixture generation.
Say we have the following two DataObjects:
:::php
class Player extends DataObject {
static $db = array (
'Name' => 'Varchar(255)'
);
static $has_one = array(
'Team' => 'Team'
);
}
class Team extends DataObject {
static $db = array (
'Name' => 'Varchar(255)',
'Origin' => 'Varchar(255)'
);
static $has_many = array(
'Players' => 'Player'
);
}
We can represent multiple instances of them in `YAML` as follows:
:::yml
Player:
john:
Name: John
Team: =>Team.hurricanes
joe:
Name: Joe
Team: =>Team.crusaders
jack:
Name: Jack
Team: =>Team.crusaders
Team:
hurricanes:
Name: The Hurricanes
Origin: Wellington
crusaders:
Name: The Crusaders
Origin: Bay of Plenty
Our `YAML` is broken up into three levels, signified by the indentation of each line.
In the first level of indentation, `Player` and `Team` ,
represent the class names of the objects we want to be created for the test.
The second level, `john` /`joe`/`jack` & `hurricanes` /`crusaders`, are identifiers.
These are what you pass as the second argument of `SapphireTest::objFromFixture()` .
Each identifier you specify represents a new object.
The third and final level represents each individual object's fields.
A field can either be provided with raw data (such as the Names for our Players),
or we can define a relationship, as seen by the fields prefixed with `=>` .
Each one of our Players has a relationship to a Team,
this is shown with the `Team` field for each `Player` being set to `=>Team.` followed by a team name.
Take the player John for example, his team is the Hurricanes which is represented by `=>Team.hurricanes` .
This is tells the system that we want to set up a relationship for the `Player` object `john` with the `Team` object `hurricanes` .
It will populate the `Player` object's `TeamID` with the ID of `hurricanes` ,
just like how a relationship is always set up.
< div class = "hint" markdown = '1' >
Note that we use the name of the relationship (Team), and not the name of the database field (TeamID).
< / div >
This style of relationship declaration can be used for both a `has-one` and a `many-many` relationship.
For `many-many` relationships, we specify a comma separated list of values.
For example we could just as easily write the above as:
:::yml
Player:
john:
Name: John
joe:
Name: Joe
jack:
Name: Jack
Team:
hurricanes:
Name: The Hurricanes
Origin: Wellington
Players: =>Player.john
crusaders:
Name: The Crusaders
Origin: Bay of Plenty
Players: =>Player.joe,=>Player.jack
A crucial thing to note is that **the YAML file specifies DataObjects, not database records** .
The database is populated by instantiating DataObject objects and setting the fields declared in the YML,
then calling write() on those objects.
This means that any `onBeforeWrite()` or default value logic will be executed as part of the test.
The reasoning behind this is to allow us to test the `onBeforeWrite` functionality of our objects.
You can see this kind of testing in action in the `testURLGeneration()` test from the example in
[Creating a SilverStripe Test ](creating-a-silverstripe-test ).
2012-12-07 18:44:00 +01:00
## Test Class Definition
2013-09-21 21:24:32 +02:00
### Manual Object Creation
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
Sometimes statically defined fixtures don't suffice. This could be because of the complexity of the tested model,
or because the YAML format doesn't allow you to modify all of a model's state.
2012-12-07 18:44:00 +01:00
One common example here is publishing pages (page fixtures aren't published by default).
You can always resort to creating objects manually in the test setup phase.
2013-09-21 21:24:32 +02:00
Since the test database is cleared on every test method, you'll get a fresh set of test instances every time.
:::php
class SiteTreeTest extends SapphireTest {
function setUp() {
parent::setUp();
for($i=0; $i< 100 ; $ i + + ) {
$page = new Page(array('Title' => "Page $i"));
$page->write();
$page->publish('Stage', 'Live');
}
}
}
2012-12-07 18:44:00 +01:00
## Fixture Factories
### Why Factories?
2013-09-21 21:24:32 +02:00
While manually defined fixtures provide full flexibility, they offer very little in terms of structure and convention.
Alternatively, you can use the `[api:FixtureFactory]` class, which allows you to set default values,
callbacks on object creation, and dynamic/lazy value setting.
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
< div class = "hint" markdown = '1' >
SapphireTest uses FixtureFactory under the hood when it is provided with YAML based fixtures.
< / div >
The idea is that rather than instantiating objects directly, we'll have a factory class for them.
This factory can have so called "blueprints" defined on it, which tells the factory how to instantiate an object of a specific type. Blueprints need a name, which is usually set to the class it creates.
2012-12-07 18:44:00 +01:00
### Usage
Since blueprints are auto-created for all available DataObject subclasses,
2013-09-21 21:24:32 +02:00
you only need to instantiate a factory to start using it.
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
:::php
$factory = Injector::inst()->create('FixtureFactory');
$obj = $factory->createObject('MyClass', 'myobj1');
2012-12-07 18:44:00 +01:00
It is important to remember that fixtures are referenced by arbitrary
identifiers ('myobj1'). These are internally mapped to their database identifiers.
2013-09-21 21:24:32 +02:00
:::
$databaseId = $factory->getId('MyClass', 'myobj1');
2012-12-07 18:44:00 +01:00
In order to create an object with certain properties, just add a second argument:
2013-09-21 21:24:32 +02:00
:::php
$obj = $factory->createObject('MyClass', 'myobj1', array('MyProperty' => 'My Value'));
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
#### Default Properties
2012-12-07 18:44:00 +01:00
Blueprints can be overwritten in order to customize their behaviour,
for example with default properties in case none are passed into `createObject()` .
2013-09-21 21:24:32 +02:00
:::php
$factory->define('MyObject', array(
'MyProperty' => 'My Default Value'
));
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
#### Dependent Properties
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
Values can be set on demand through anonymous functions, which can either generate random defaults,
or create composite values based on other fixture data.
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
:::php
$factory->define('Member', array(
'Email' => function($obj, $data, $fixtures) {
if(isset($data['FirstName']) {
$obj->Email = strtolower($data['FirstName']) . '@example.org';
}
},
'Score' => function($obj, $data, $fixtures) {
$obj->Score = rand(0,10);
}
));
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
#### Relations
2012-12-07 18:44:00 +01:00
Model relations can be expressed through the same notation as in the YAML fixture format
described earlier, through the `=>` prefix on data values.
2013-09-21 21:24:32 +02:00
:::php
$obj = $factory->createObject('MyObject', 'myobj1', array(
'MyHasManyRelation' => '=>MyOtherObject.obj1,=>MyOtherObject.obj2'
));
2012-12-07 18:44:00 +01:00
2013-09-21 21:24:32 +02:00
#### Callbacks
2012-12-07 18:44:00 +01:00
Sometimes new model instances need to be modified in ways which can't be expressed
in their properties, for example to publish a page, which requires a method call.
2013-09-21 21:24:32 +02:00
:::php
$blueprint = Injector::inst()->create('FixtureBlueprint', 'Member');
$blueprint->addCallback('afterCreate', function($obj, $identifier, $data, $fixtures) {
$obj->publish('Stage', 'Live');
});
$page = $factory->define('Page', $blueprint);
2012-12-07 18:44:00 +01:00
Available callbacks:
* `beforeCreate($identifier, $data, $fixtures)`
* `afterCreate($obj, $identifier, $data, $fixtures)`
### Multiple Blueprints
Data of the same type can have variations, for example forum members vs.
CMS admins could both inherit from the `Member` class, but have completely
different properties. This is where named blueprints come in.
By default, blueprint names equal the class names they manage.
2013-09-21 21:24:32 +02:00
:::php
$memberBlueprint = Injector::inst()->create('FixtureBlueprint', 'Member', 'Member');
$adminBlueprint = Injector::inst()->create('FixtureBlueprint', 'AdminMember', 'Member');
$adminBlueprint->addCallback('afterCreate', function($obj, $identifier, $data, $fixtures) {
if(isset($fixtures['Group']['admin'])) {
$adminGroup = Group::get()->byId($fixtures['Group']['admin']);
$obj->Groups()->add($adminGroup);
}
});
$member = $factory->createObject('Member'); // not in admin group
$admin = $factory->createObject('AdminMember'); // in admin group
2012-12-07 18:44:00 +01:00
### Full Test Example
2013-09-21 21:24:32 +02:00
:::php
class MyObjectTest extends SapphireTest {
protected $factory;
function __construct() {
parent::__construct();
$factory = Injector::inst()->create('FixtureFactory');
// Defines a "blueprint" for new objects
$factory->define('MyObject', array(
'MyProperty' => 'My Default Value'
));
$this->factory = $factory;
}
function testSomething() {
$MyObjectObj = $this->factory->createObject(
'MyObject',
array('MyOtherProperty' => 'My Custom Value')
);
// $myPageObj->MyProperty = My Default Value
// $myPageObj->MyOtherProperty = My Custom Value
}
}