README

The modern test data factory for PEST. Write cleaner, more maintainable PHP tests with expressive factories.

Inspired by Laravel's Eloquent factories, Data Factory brings the same elegant API to any PHP project—no framework required.

✨ Features

• ✅ Write DRY test code - Define test data once, reuse everywhere
• ✅ Readable test assertions - Clear intent with named states like ->succeeded()
• ✅ Easy complex objects - Create nested graphs without boilerplate
• ✅ Built with PEST in mind - Works with any PHP testing framework, optimized for PEST
• ✅ Framework-agnostic - Works with any PHP class, not tied to Eloquent
• ✅ Type-safe factories - Modern type hints with 100% type coverage
• ✅ Faker integration - Realistic test data out of the box

📋 Requirements

• PHP 8.2 or higher
• Composer

Fully tested on PHP 8.2, 8.3, 8.4 across Windows, Linux, and macOS

Installation

Install via Composer:

composer require fbarrento/data-factory --dev

Why Use Data Factories for Testing?

The Problem: Test setup code is repetitive, hard to maintain, and clutters your test files.

// ❌ Without factories - repetitive and brittle
it('processes deployment', function () {
    $deployment = [
        'id' => '123e4567-e89b-12d3-a456-426614174000',
        'status' => 'deployment.succeeded',
        'branch_name' => 'main',
        'commit_hash' => 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0',
        'commit_message' => 'Deploy feature X to production',
        'failure_reason' => null,
        'php_major_version' => '8.4',
        'uses_octane' => true,
        'started_at' => '2024-01-15 10:00:00',
        'finished_at' => '2024-01-15 10:05:00',
    ];

    // Your actual test logic here...
});

// ✅ With factories - clean and focused
it('processes deployment', function () {
    $deployment = Deployment::factory()->succeeded()->make();

    // Your actual test logic here - clear and focused!
});

The Benefits:

• DRY (Don't Repeat Yourself) - Define test data once, reuse across all tests
• Maintainability - Change data structure in one place, not hundreds of tests
• Readability - ->succeeded() is clearer than 10 lines of setup
• Flexibility - Easy to test edge cases with different states
• Focus - Spend time testing behavior, not setting up data

Quick Start

// tests/Factories/DeploymentFactory.php
use FBarrento\DataFactory\Factory;

class DeploymentFactory extends Factory
{
    protected function definition(): array
    {
        return [
            'id' => $this->fake->uuid(),
            'status' => 'pending',
            'branch_name' => 'main',
            'commit_hash' => $this->fake->sha1(),
        ];
    }

    public function succeeded(): static
    {
        return $this->state(['status' => 'deployment.succeeded']);
    }
}

// tests/Feature/DeploymentTest.php
it('handles successful deployments', function () {
    $deployment = Deployment::factory()->succeeded()->make();

    expect($deployment->status)->toBe('deployment.succeeded');
});

it('creates multiple test deployments', function () {
    $deployments = Deployment::factory()->count(5)->make();

    expect($deployments)->toHaveCount(5);
});

Documentation

• Getting Started - Overview and feature list
• Installation - Install and setup
• Basic Usage - Create your first factory
• Faker Integration - Generate realistic fake data
• States - Define reusable variations
• Sequences - Cycle through values
• Nested Factories - Build complex object graphs
• Array Factories - Generate arrays for JSON/API responses
• Class Integration - Integrate factories with your classes using HasDataFactory trait
• Advanced Examples - Real-world Laravel Cloud API examples
• Testing - Use factories in PEST tests

Roadmap

Features under consideration for future releases:

• 🎯 raw() method - Return attribute arrays without instantiating objects, useful for testing raw data or API payloads

  $attributes = Vehicle::factory()->raw(); // Returns ['make' => '...', 'model' => '...']

• 🪝 afterMaking() callbacks - Post-processing hooks for generated data, enabling validation or side effects

  Vehicle::factory()
      ->afterMaking(fn($vehicle) => logger()->info('Made vehicle', ['id' => $vehicle->id]))
      ->make();

• 🗂️ Export to JSON - Save datasets as JSON fixtures for testing or seeding

  Vehicle::factory()->count(1000)->toJson('fixtures/vehicles.json');

• 📦 Export to Arrays - Transform objects to nested array structures

  $array = Customer::factory()->count(100)->toArray();

• ⚡ Streaming/Chunking - Process large datasets (100k+ records) without memory issues

  Vehicle::factory()->count(200000)->chunk(1000)->toJson('fixtures/vehicles.json');

• 🚨 Exception Handling - Custom exceptions with helpful error messages for configuration and validation errors

Have ideas for other features? Open an issue or submit a PR!

Contributing

We welcome contributions! Data Factory is built with high quality standards:

• ✅ 100% test coverage
• ✅ 100% type coverage
• ✅ PHPStan level 9
• ✅ Modern PHP 8.2+ patterns

Quick Start for Contributors:

# Run all quality checks
composer test

# Format code
composer lint

# Run tests with coverage
composer test:unit

For detailed contributing guidelines, development setup, and code standards, see CONTRIBUTING.md.

References

• Stop Writing Arrays in Your Tests: Laravel Factories for Data Objects - The article that inspired this package

License

Data Factory is open-sourced software licensed under the MIT license.