Merge pull request #2279 from Ragazzo/fixtures_controller_improvements

docs/guide/console-fixture.md

-Database Fixtures
-=================
+Fixtures console flow
+=====================
 
 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.
 
-Yii supports database fixtures via the `yii fixture` command line tool. This tool supports:
+Yii supports fixtures via the `yii fixture` command line tool. This tool supports:
 
-* Applying new fixtures to database tables;
-* Clearing, database tables (with sequences);
+* Loading fixtures to different storages such as: database, nosql, etc;
+* Unloading fixtures in different ways (usually it is clearing storage);
 * Auto-generating fixtures and populating it with random data.
 
 Fixtures format
 ---------------
 
-Fixtures are just plain php files returning array. These files are usually stored under `@tests/unit/fixtures` path, but it
-can be [configured](#configure-command-globally) in other way. Example of fixture file:
+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:
 
 ```
-#users.php file under fixtures path
+#users.php file under fixtures data path, by default @tests\unit\fixtures\data
 
 return [
 	[
@@ -36,31 +36,35 @@ return [
 	],
 ];
 ```
-
-This data will be loaded to the `users`, but before it will be loaded table `users` will be cleared: all data deleted, sequence reset.
+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).
 Above fixture example was auto-generated by `yii2-faker` extension, read more about it in these [section](#auto-generating-fixtures).
+Fixture classes name should not be plural.
+
+Loading fixtures
+----------------
 
-Applying fixtures
------------------
+Fixture classes should be suffixed by `Fixture` class. By default fixtures will be searched under `tests\unit\fixtures` namespace, you can
+change this behavior with config or command options.
 
-To apply fixture to the table, run the following command:
+To apply fixture, run the following command:
 
 ```
-yii fixture/apply <tbl_name>
+yii fixture/apply <fixture_name>
 ```
 
-The required `tbl_name` parameter specifies a database table to which data will be loaded. You can load data to several tables at once.
+The required `fixture_name` parameter specifies a fixture name which data will be loaded. You can load several fixtures at once.
 Below are correct formats of this command:
 
 ```
-// apply fixtures to the "users" table of database
-yii fixture/apply users
+// apply `users` fixture
+yii fixture/apply User
 
 // same as above, because default action of "fixture" command is "apply"
-yii fixture users
+yii fixture User
 
-// apply several fixtures to several tables. Note that there should not be any whitespace between ",", it should be one string.
-yii fixture users,users_profiles
+// apply several fixtures. Note that there should not be any whitespace between ",", it should be one string.
+yii fixture User,UserProfile
 
 // apply all fixtures
 yii fixture/apply all
@@ -68,29 +72,31 @@ yii fixture/apply all
 // same as above
 yii fixture all
 
-// apply fixtures to the table users, but fixtures will be taken from different path.
-yii fixture users --fixturePath='@app/my/custom/path/to/fixtures'
+// apply fixtures, but for other database connection.
+yii fixtures User --db='customDbConnectionId'
 
-// apply fixtures to the table users, but for other database connection.
-yii fixtures users --db='customDbConnectionId'
+// apply fixtures, but search them in different namespace. By default namespace is: tests\unit\fixtures.
+yii fixtures User --namespace='alias\my\custom\namespace'
 ```
 
-Clearing tables
----------------
+Unloading fixtures
+------------------
 
-To clear table, run the following command:
+To unload fixture, run the following command:
 
 ```
-// clear given table: delete all data and reset sequence.
-yii fixture/clear users
+// unload Users fixture, by default it will clear fixture storage (for example "users" table, or "users" collection if this is mongodb fixture).
+yii fixture/clear User
 
-// clear several tables. Note that there should not be any whitespace between ",", it should be one string.
-yii fixture/clear users,users_profile
+// Unload several fixtures. Note that there should not be any whitespace between ",", it should be one string.
+yii fixture/clear User,UserProfile
 
-// clear all tables of current connection in current schema
+// unload all fixtures
 yii fixture/clear all
 ```
 
+Same command options like: `db`, `namespace` also can be applied to this command.
+
 Configure Command Globally
 --------------------------
 While command line options allow us to configure the migration command
@@ -101,8 +107,8 @@ different migration path as follows:
 'controllerMap' => [
     'fixture' => [
         'class' => 'yii\console\FixtureController',
-        'fixturePath' => '@app/my/custom/path/to/fixtures',
 		'db' => 'customDbConnectionId',
+		'namespace' => 'myalias\some\custom\namespace',
     ],
 ]
 ```

docs/guide/test-fixture.md

@@ -175,6 +175,47 @@ This means you only need to work with `@app/tests/fixtures/initdb.php` if you wa
 before each test. You may otherwise simply focus on developing each individual test case and the corresponding fixtures.
 
 
+Fixtures hierarchy convention
+-----------------------------
+
+Usually you will have one fixture class per needed fixture and will be only switching data files for fixture classes. 
+When you have simple project that does not have much database testing and fixtures, you can put all fixtures data files under `data` folder, as it is done by default.
+But when your project is not very simple you should not be greedy when using data files and organize them according these rule:
+
+- data file should follow same hierarchy that is used for your project classes namespace.
+
+Lets see example:
+
+```php
+#under folder tests\unit\fixtures
+data\
+     components\
+                some_fixture_data_file1.php
+                some_fixture_data_file2.php
+                ...
+                some_fixture_data_fileN.php
+     models\
+            db\
+               some_fixture_data_file1.php
+               some_fixture_data_file2.php
+               ...
+               some_fixture_data_fileN.php
+            forms\
+               some_fixture_data_file1.php
+               some_fixture_data_file2.php
+               ...
+               some_fixture_data_fileN.php
+
+#and so on
+```
+
+In this way you will avoid fixture data collision between tests and use them as you need.
+
+> **Note** In the example above fixture files are named only for example purposes, in real life you should name them according what fixture type you are using.
+It can be table name, or mongodb collection name if you are using mongodb fixture. In order to know how to specify and name data files for your fixtures read above on this article.
+
+Same rule can be applied to organize fixtures classes in your project, so similar hierarchy will be build under `fixtures` directory, avoiding usage of `data` directory, that is reserved for data files.
+
 Summary
 -------
 

extensions/mongodb/ActiveFixture.php

@@ -53,12 +53,12 @@ class ActiveFixture extends BaseActiveFixture
 
 	/**
 	 * Loads the fixture data.
-	 * The default implementation will first reset the DB table and then populate it with the data
-	 * returned by [[getData()]].
+	 * Data will be batch inserted into the given collection.
 	 */
 	public function load()
 	{
-		$this->resetCollection();
+		parent::load();
+
 		$data = $this->getData();
 		$this->getCollection()->batchInsert($data);
 		foreach ($data as $alias => $row) {
@@ -66,6 +66,17 @@ class ActiveFixture extends BaseActiveFixture
 		}
 	}
 
+	/**
+	 * Unloads the fixture.
+	 * 
+	 * The default implementation will clean up the colection by calling [[resetCollection()]].
+	 */
+	public function unload()
+	{
+		$this->resetCollection();
+		parent::unload();
+	}
+
 	protected function getCollection()
 	{
 		return $this->db->getCollection($this->getCollectionName());

framework/test/ActiveFixture.php

@@ -65,7 +65,6 @@ class ActiveFixture extends BaseActiveFixture
 	/**
 	 * Loads the fixture.
 	 *
-	 * The default implementation will first clean up the table by calling [[resetTable()]].
 	 * It will then populate the table with the data returned by [[getData()]].
 	 *
 	 * If you override this method, you should consider calling the parent implementation
@@ -73,7 +72,7 @@ class ActiveFixture extends BaseActiveFixture
 	 */
 	public function load()
 	{
-		$this->resetTable();
+		parent::load();
 
 		$table = $this->getTableSchema();
 
@@ -92,6 +91,17 @@ class ActiveFixture extends BaseActiveFixture
 	}
 
 	/**
+	 * Unloads the fixture.
+	 * 
+	 * The default implementation will clean up the table by calling [[resetTable()]].
+	 */
+	public function unload()
+	{
+		$this->resetTable();
+		parent::unload();
+	}
+
+	/**
 	 * Returns the fixture data.
 	 * 
 	 * The default implementation will try to return the fixture data by including the external file specified by [[dataFile]].