| commit | author | age | ||
| 2207d6 | 1 | # DataFactory |
| W | 2 | |
| 3 | ||
| 4 | DataFactory allows you to easily generate and create test data using [**FactoryMuffin**](https://github.com/thephpleague/factory-muffin). | |
| 5 | DataFactory uses an ORM of your application to define, save and cleanup data. Thus, should be used with ORM or Framework modules. | |
| 6 | ||
| 7 | This module requires packages installed: | |
| 8 | ||
| 9 | ```json | |
| 10 | { | |
| 11 | "league/factory-muffin": "^3.0", | |
| 12 | } | |
| 13 | ``` | |
| 14 | ||
| 15 | Generation rules can be defined in a factories file. You will need to create `factories.php` (it is recommended to store it in `_support` dir) | |
| 16 | Follow [FactoryMuffin documentation](https://github.com/thephpleague/factory-muffin) to set valid rules. | |
| 17 | Random data provided by [Faker](https://github.com/fzaninotto/Faker) library. | |
| 18 | ||
| 19 | ```php | |
| 20 | <?php | |
| 21 | use League\FactoryMuffin\Faker\Facade as Faker; | |
| 22 | ||
| 23 | $fm->define(User::class)->setDefinitions([ | |
| 24 | 'name' => Faker::name(), | |
| 25 | ||
| 26 | // generate email | |
| 27 | 'email' => Faker::email(), | |
| 28 | 'body' => Faker::text(), | |
| 29 | ||
| 30 | // generate a profile and return its Id | |
| 31 | 'profile_id' => 'factory|Profile' | |
| 32 | ]); | |
| 33 | ``` | |
| 34 | ||
| 35 | Configure this module to load factory definitions from a directory. | |
| 36 | You should also specify a module with an ORM as a dependency. | |
| 37 | ||
| 38 | ```yaml | |
| 39 | modules: | |
| 40 | enabled: | |
| 41 | - Yii2: | |
| 42 | configFile: path/to/config.php | |
| 43 | - DataFactory: | |
| 44 | factories: tests/_support/factories | |
| 45 | depends: Yii2 | |
| 46 | ``` | |
| 47 | ||
| 48 | (you can also use Laravel5 and Phalcon). | |
| 49 | ||
| 50 | In this example factories are loaded from `tests/_support/factories` directory. Please note that this directory is relative from the codeception.yml file (so for Yii2 it would be codeception/_support/factories). | |
| 51 | You should create this directory manually and create PHP files in it with factories definitions following [official documentation](https://github.com/thephpleague/factory-muffin#usage). | |
| 52 | ||
| 53 | In cases you want to use data from database inside your factory definitions you can define them in Helper. | |
| 54 | For instance, if you use Doctrine, this allows you to access `EntityManager` inside a definition. | |
| 55 | ||
| 56 | To proceed you should create Factories helper via `generate:helper` command and enable it: | |
| 57 | ||
| 58 | ``` | |
| 59 | modules: | |
| 60 | enabled: | |
| 61 | - DataFactory: | |
| 62 | depends: Doctrine2 | |
| 63 | - \Helper\Factories | |
| 64 | ||
| 65 | ``` | |
| 66 | ||
| 67 | In this case you can define factories from a Helper class with `_define` method. | |
| 68 | ||
| 69 | ```php | |
| 70 | <?php | |
| 71 | public function _beforeSuite() | |
| 72 | { | |
| 73 | $factory = $this->getModule('DataFactory'); | |
| 74 | // let us get EntityManager from Doctrine | |
| 75 | $em = $this->getModule('Doctrine2')->_getEntityManager(); | |
| 76 | ||
| 77 | $factory->_define(User::class, [ | |
| 78 | ||
| 79 | // generate random user name | |
| 80 | // use League\FactoryMuffin\Faker\Facade as Faker; | |
| 81 | 'name' => Faker::name(), | |
| 82 | ||
| 83 | // get real company from database | |
| 84 | 'company' => $em->getRepository(Company::class)->find(), | |
| 85 | ||
| 86 | // let's generate a profile for each created user | |
| 87 | // receive an entity and set it via `setProfile` method | |
| 88 | // UserProfile factory should be defined as well | |
| 89 | 'profile' => 'entity|'.UserProfile::class | |
| 90 | ]); | |
| 91 | } | |
| 92 | ``` | |
| 93 | ||
| 94 | Factory Definitions are described in official [Factory Muffin Documentation](https://github.com/thephpleague/factory-muffin) | |
| 95 | ||
| 96 | ### Related Models Generators | |
| 97 | ||
| 98 | If your module relies on other model you can generate them both. | |
| 99 | To create a related module you can use either `factory` or `entity` prefix, depending on ORM you use. | |
| 100 | ||
| 101 | In case your ORM expects an Id of a related record (Eloquent) to be set use `factory` prefix: | |
| 102 | ||
| 103 | ```php | |
| 104 | 'user_id' => 'factory|User' | |
| 105 | ``` | |
| 106 | ||
| 107 | In case your ORM expects a related record itself (Doctrine) then you should use `entity` prefix: | |
| 108 | ||
| 109 | ```php | |
| 110 | 'user' => 'entity|User' | |
| 111 | ``` | |
| 112 | ||
| 113 | ## Actions | |
| 114 | ||
| 115 | ### have | |
| 116 | ||
| 117 | Generates and saves a record,. | |
| 118 | ||
| 119 | ```php | |
| 120 | $I->have('User'); // creates user | |
| 121 | $I->have('User', ['is_active' => true]); // creates active user | |
| 122 | ``` | |
| 123 | ||
| 124 | Returns an instance of created user. | |
| 125 | ||
| 126 | * `param string` $name | |
| 127 | * `param array` $extraAttrs | |
| 128 | ||
| 129 | * `return` object | |
| 130 | ||
| 131 | ||
| 132 | ### haveMultiple | |
| 133 | ||
| 134 | Generates and saves a record multiple times. | |
| 135 | ||
| 136 | ```php | |
| 137 | $I->haveMultiple('User', 10); // create 10 users | |
| 138 | $I->haveMultiple('User', 10, ['is_active' => true]); // create 10 active users | |
| 139 | ``` | |
| 140 | ||
| 141 | * `param string` $name | |
| 142 | * `param int` $times | |
| 143 | * `param array` $extraAttrs | |
| 144 | ||
| 145 | * `return` \object[] | |
| 146 | ||
| 147 | ||
| 148 | ### make | |
| 149 | ||
| 150 | Generates a record instance. | |
| 151 | ||
| 152 | This does not save it in the database. Use `have` for that. | |
| 153 | ||
| 154 | ```php | |
| 155 | $user = $I->make('User'); // return User instance | |
| 156 | $activeUser = $I->make('User', ['is_active' => true]); // return active user instance | |
| 157 | ``` | |
| 158 | ||
| 159 | Returns an instance of created user without creating a record in database. | |
| 160 | ||
| 161 | * `param string` $name | |
| 162 | * `param array` $extraAttrs | |
| 163 | ||
| 164 | * `return` object | |
| 165 | ||
| 166 | ||
| 167 | ### onReconfigure | |
| 168 | ||
| 169 | @throws ModuleException | |
| 170 | ||
| 171 | <p> </p><div class="alert alert-warning">Module reference is taken from the source code. <a href="https://github.com/Codeception/Codeception/tree/2.5/src/Codeception/Module/DataFactory.php">Help us to improve documentation. Edit module reference</a></div> | |
