console-fixture.md 4.81 KB
Newer Older
Qiang Xue committed
1 2 3 4
Managing Fixtures
=================

// todo: this tutorial may be merged into test-fixture.md
Mark committed
5 6 7 8

Fixtures are important part of testing. Their main purpose is to populate you with data that needed by testing
different cases. With this data using your tests becoming more efficient and useful.

Mark committed
9
Yii supports fixtures via the `yii fixture` command line tool. This tool supports:
Mark committed
10

Qiang Xue committed
11
* Loading fixtures to different storage such as: RDBMS, NoSQL, etc;
Mark committed
12
* Unloading fixtures in different ways (usually it is clearing storage);
Mark committed
13 14 15 16 17
* Auto-generating fixtures and populating it with random data.

Fixtures format
---------------

Mark committed
18 19
Fixtures are objects with different methods and configurations, refer to official [documentation](https://github.com/yiisoft/yii2/blob/master/docs/guide/test-fixture.md) on them.
Lets assume we have fixtures data to load:
Mark committed
20 21

```
Mark committed
22
#users.php file under fixtures data path, by default @tests\unit\fixtures\data
Mark committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

return [
	[
		'name' => 'Chase',
		'login' => 'lmayert',
		'email' => 'strosin.vernice@jerde.com',
		'auth_key' => 'K3nF70it7tzNsHddEiq0BZ0i-OU8S3xV',
		'password' => '$2y$13$WSyE5hHsG1rWN2jV8LRHzubilrCLI5Ev/iK0r3jRuwQEs2ldRu.a2',
	],
	[
		'name' => 'Celestine',
		'login' => 'napoleon69',
		'email' => 'aileen.barton@heaneyschumm.com',
		'auth_key' => 'dZlXsVnIDgIzFgX4EduAqkEPuphhOh9q',
		'password' => '$2y$13$kkgpvJ8lnjKo8RuoR30ay.RjDf15bMcHIF7Vz1zz/6viYG5xJExU6',
	],
];
```
Mark committed
41 42
If we are using fixture that loads data into database then these rows will be applied to `users` table. If we are using nosql fixtures, for example `mongodb`
fixture, then this data will be applied to `users` mongodb collection. In order to learn about implementing various loading strategies and more, refer to official [documentation](https://github.com/yiisoft/yii2/blob/master/docs/guide/test-fixture.md).
Mark committed
43
Above fixture example was auto-generated by `yii2-faker` extension, read more about it in these [section](#auto-generating-fixtures).
Mark committed
44
Fixture classes name should not be plural.
Mark committed
45

Mark committed
46 47 48
Loading fixtures
----------------

Mark committed
49
Fixture classes should be suffixed by `Fixture` class. By default fixtures will be searched under `tests\unit\fixtures` namespace, you can
Mark committed
50
change this behavior with config or command options.
Mark committed
51

Mark committed
52
To load fixture, run the following command:
Mark committed
53 54

```
Mark committed
55
yii fixture/load <fixture_name>
Mark committed
56 57
```

Mark committed
58
The required `fixture_name` parameter specifies a fixture name which data will be loaded. You can load several fixtures at once.
Mark committed
59 60 61
Below are correct formats of this command:

```
Mark committed
62 63
// load `users` fixture
yii fixture/load User
Mark committed
64

Mark committed
65
// same as above, because default action of "fixture" command is "load"
Mark committed
66
yii fixture User
Mark committed
67

Mark committed
68
// load several fixtures. Note that there should not be any whitespace between ",", it should be one string.
Mark committed
69
yii fixture User,UserProfile
Mark committed
70

Mark committed
71
// load all fixtures
Mark committed
72
yii fixture/load all
Mark committed
73 74 75 76

// same as above
yii fixture all

Mark committed
77
// load fixtures, but for other database connection.
Mark committed
78
yii fixture User --db='customDbConnectionId'
Mark committed
79

Mark committed
80
// load fixtures, but search them in different namespace. By default namespace is: tests\unit\fixtures.
Mark committed
81
yii fixture User --namespace='alias\my\custom\namespace'
Mark committed
82

Mark committed
83
// load global fixture `some\name\space\CustomFixture` before other fixtures will be loaded.
Mark committed
84 85
// By default this option is set to `InitDbFixture` to disable/enable integrity checks. You can specify several
// global fixtures separated by comma.
Mark committed
86
yii fixture User --globalFixtures='some\name\space\Custom'
Mark committed
87 88
```

Mark committed
89 90
Unloading fixtures
------------------
Mark committed
91

Mark committed
92
To unload fixture, run the following command:
Mark committed
93 94

```
Mark committed
95
// unload Users fixture, by default it will clear fixture storage (for example "users" table, or "users" collection if this is mongodb fixture).
Mark committed
96
yii fixture/unload User
Mark committed
97

Mark committed
98
// Unload several fixtures. Note that there should not be any whitespace between ",", it should be one string.
Mark committed
99
yii fixture/unload User,UserProfile
Mark committed
100

Mark committed
101
// unload all fixtures
Mark committed
102
yii fixture/unload all
Mark committed
103 104
```

Mark committed
105
Same command options like: `db`, `namespace`, `globalFixtures` also can be applied to this command.
Mark committed
106

Mark committed
107 108 109 110 111 112 113 114 115
Configure Command Globally
--------------------------
While command line options allow us to configure the migration command
on-the-fly, sometimes we may want to configure the command once for all. For example you can configure
different migration path as follows:

```
'controllerMap' => [
    'fixture' => [
116
        'class' => 'yii\console\controllers\FixtureController',
Mark committed
117
		'db' => 'customDbConnectionId',
Mark committed
118
		'namespace' => 'myalias\some\custom\namespace',
Mark committed
119 120 121 122
		'globalFixtures' => [
			'some\name\space\Foo',
			'other\name\space\Bar'
		],
Mark committed
123 124 125 126 127 128 129 130 131
    ],
]
```

Auto-generating fixtures
------------------------

Yii also can auto-generate fixtures for you based on some template. You can generate your fixtures with different data on different languages and formats.
These feature is done by [Faker](https://github.com/fzaninotto/Faker) library and `yii2-faker` extension.
Qiang Xue committed
132
See extension [guide](https://github.com/yiisoft/yii2/tree/master/extensions/faker) for more docs.