silverstripe-framework/docs/en/topics/testing/fixtures.md

# Fixtures

## Overview

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.

## YAML Fixtures

YAML is a markup language which is deliberately simple and easy to read,
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).

## Test Class Definition

### Manual Object Creation

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.
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.
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');
			}
		}
	}

## Fixture Factories

### Why Factories?

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.

<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.

### Usage

Since blueprints are auto-created for all available DataObject subclasses,
you only need to instantiate a factory to start using it.

	:::php
	$factory = Injector::inst()->create('FixtureFactory');
	$obj = $factory->createObject('MyClass', 'myobj1');

It is important to remember that fixtures are referenced by arbitrary
identifiers ('myobj1'). These are internally mapped to their database identifiers.

	:::php
	$databaseId = $factory->getId('MyClass', 'myobj1');

In order to create an object with certain properties, just add a second argument:

	:::php
	$obj = $factory->createObject('MyClass', 'myobj1', array('MyProperty' => 'My Value'));

#### Default Properties

Blueprints can be overwritten in order to customize their behaviour,
for example with default properties in case none are passed into `createObject()`.

	:::php
	$factory->define('MyObject', array(
		'MyProperty' => 'My Default Value'
	));

#### Dependent Properties

Values can be set on demand through anonymous functions, which can either generate random defaults,
or create composite values based on other fixture data.

	:::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);
		}
	));

#### Relations

Model relations can be expressed through the same notation as in the YAML fixture format
described earlier, through the `=>` prefix on data values.

	:::php
	$obj = $factory->createObject('MyObject', 'myobj1', array(
		'MyHasManyRelation' => '=>MyOtherObject.obj1,=>MyOtherObject.obj2'
	));

#### Callbacks

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.

	:::php
	$blueprint = Injector::inst()->create('FixtureBlueprint', 'Member');
	$blueprint->addCallback('afterCreate', function($obj, $identifier, $data, $fixtures) {
		$obj->publish('Stage', 'Live');
	});
	$page = $factory->define('Page', $blueprint);

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.

	:::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

### Full Test Example

	:::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
		}
	}