Module Datafactory Laravel Package

Getting Started

Minimal Setup

1. Installation Add the module to your composer.json:

   composer require --dev codeception/module-datafactory
   

   Register it in codeception.yml under modules:

   modules:
     enabled:
       - DataFactory
   

2. First Use Case Define a factory in tests/_data/factories.php:

   $I->haveInDatabase('users', [
       'name' => 'John Doe',
       'email' => 'john@example.com',
   ]);
   

   Or use the DataFactory DSL:

   $I->haveInDatabase('users', [
       'name' => 'John Doe',
       'email' => 'john@example.com',
   ]);
   

3. Where to Look First

   • Documentation: Codeception DataFactory Module Docs
   • Example Factories: Check tests/_data/factories.php in your project.
   • Built-in Helpers: Methods like haveInDatabase(), haveInMemory(), and haveInFile().

Implementation Patterns

Common Workflows

1. Database Factories

   $I->haveInDatabase('posts', [
       'title' => 'Test Post',
       'body' => 'Test content',
       'user_id' => function() {
           return $I->grabFromDatabase('users', 'id', ['name' => 'John Doe']);
       }
   ]);
   

2. Memory Factories (for non-database objects)

   $I->haveInMemory('Order', [
       'id' => 1,
       'items' => [
           ['product_id' => 1, 'quantity' => 2],
       ],
   ]);
   

3. File Factories (for JSON/XML/CSV)

   $I->haveInFile('tests/_data/users.json', [
       'name' => 'Jane Doe',
       'email' => 'jane@example.com',
   ]);
   

4. Reusable Factories Define a factory in _data/factories.php:

   $I->haveInDatabase('users', [
       'name' => 'Admin',
       'email' => 'admin@example.com',
       'role' => 'admin',
   ]);
   

   Reference it in tests:

   $I->haveInDatabase('posts', [
       'user_id' => function() {
           return $I->grabFromDatabase('users', 'id', ['role' => 'admin']);
       },
   ]);
   

5. Dynamic Data with Callbacks

   $I->haveInDatabase('products', [
       'name' => 'Dynamic Product',
       'price' => function() {
           return rand(10, 100);
       },
   ]);
   

Integration Tips

• Laravel Eloquent: Use haveInDatabase() with Eloquent models.

  $I->haveInDatabase('App\Models\User', [
      'name' => 'Test User',
      'email' => 'test@example.com',
  ]);
  

• Seeding: Combine with Laravel’s DatabaseSeeder for complex setups.
• Fixtures: Use haveInFile() for large datasets (e.g., JSON fixtures).

Gotchas and Tips

Pitfalls

1. Database Transactions Ensure your test database is fresh (e.g., using Db module or Laravel’s DatabaseTransactions trait). Factories persist data unless rolled back.

2. Foreign Key Constraints Insert parent records (e.g., users) before child records (e.g., posts). Use callbacks to reference IDs dynamically:

   $I->haveInDatabase('users', ['name' => 'Parent']);
   $I->haveInDatabase('posts', [
       'user_id' => function() {
           return $I->grabFromDatabase('users', 'id', ['name' => 'Parent']);
       },
   ]);
   

3. File Paths Ensure haveInFile() paths are correct (relative to tests/ by default). Use absolute paths if needed:

   $I->haveInFile(__DIR__ . '/_data/users.json', [...]);
   

4. Memory Leaks Avoid mixing haveInMemory() with database factories unless explicitly needed (e.g., for API tests).

Debugging

• Verify Data: Use grabFromDatabase() or seeInDatabase() to check inserted data.

  $I->seeInDatabase('users', ['email' => 'john@example.com']);
  

• Logs: Enable Codeception’s verbose mode (-vv) to debug factory execution.
• Factory Overrides: If a factory fails, check for typos in table/model names or missing required fields.

Extension Points

1. Custom Factories Extend the module by creating a custom factory class:

   class CustomFactory extends \Codeception\Module\DataFactory
   {
       public function haveCustomData($data) { ... }
   }
   

   Register it in codeception.yml:

   modules:
     config:
       DataFactory:
         class: CustomFactory
   

2. Hooks Use Codeception’s before/after hooks to reset data:

   $I->haveInDatabase('users', ['name' => 'Cleanup']);
   $I->runSql('DELETE FROM users WHERE name = ?', ['Cleanup']);
   

3. Laravel Integration For Laravel, pair with Db module to reset the database:

   $I->haveInDatabase('users', [...]);
   $I->runSql('SET FOREIGN_KEY_CHECKS = 0; TRUNCATE users;');
   

Tips

• Use haveInDatabase() for Eloquent: Simplifies model interactions.
• Leverage Callbacks: Generate dynamic data (e.g., timestamps, UUIDs).
• Combine with Other Modules: Use Filesystem module to manage fixture files.
• Test Data Isolation: Prefix test data (e.g., test_user_) to avoid conflicts.