Getting Started

Minimal Steps

Install the package in your Laravel project (dev dependency):
```
composer require --dev testo/data
```
Set up Testo (if not already installed):
```
composer require --dev php-testo/testo
```

Create a basic test file (e.g., tests/Unit/DataTest.php) with a simple parameterized test:

use Testo\Testo;
use Testo\Data\Data;

Testo::describe('Data Provider Example', function () {
    // Inline tuple example
    Data::fromTuples([[1, 'one'], [2, 'two']])->it('should map numbers to words', function ($number, $word) {
        $this->assertEquals($word, strval($number));
    });

    // Named dataset example
    Data::fromArray([
        'valid' => [['name' => 'John'], ['name' => 'Jane']],
        'invalid' => [['name' => ''], ['name' => null]],
    ])->it('should handle user names', function ($userData) {
        $user = new User($userData);
        // Assertions...
    });
});

Run the test:
```
vendor/bin/testo
```

First Use Case

Scenario: Testing a User model with varied input combinations.

Problem: Manually writing test cases for each input variation is repetitive.

Solution: Use testo/data to define datasets once and let the framework generate test cases.

Data::fromArray([
    'valid' => [['name' => 'Alice', 'email' => 'alice@example.com']],
    'invalid' => [
        ['name' => '', 'email' => 'invalid@example.com'],
        ['name' => 'Bob', 'email' => null],
    ],
])->it('should validate user attributes', function ($userData) {
    $user = new User($userData);
    $this->assertValidation($user); // Custom assertion
});

Where to Look First

Testo Documentation (for Testo syntax and features).
Data Plugin README (for dataset-specific examples).
Laravel Testo Integration: Check if any community wrappers exist for Laravel-specific test helpers (e.g., create(), assertDatabaseHas()).

Implementation Patterns

Core Workflows

1. Inline Tuples

Use for small, ad-hoc datasets defined directly in the test.

Data::fromTuples([[1, 2, 3], [4, 5, 6]])->it('should sum arrays', function ($a, $b, $c) {
    $this->assertEquals(9, $a + $b + $c);
});

2. Named Datasets

Organize datasets by name (e.g., valid, invalid) for clarity and reuse.

Data::fromArray([
    'valid' => [['status' => 'active'], ['status' => 'pending']],
    'invalid' => [['status' => ''], ['status' => null]],
])->it('should handle status values', function ($data) {
    // Test logic...
});

3. Cartesian Product (Cross)

Generate all combinations of inputs from multiple datasets.

Data::cross([
    ['role' => 'admin', 'permission' => 'read'],
    ['role' => 'user', 'permission' => 'write'],
])->it('should validate role-permission pairs', function ($role, $permission) {
    $this->assertCan($role, $permission);
});

4. Zipped Iteration

Iterate over multiple datasets in lockstep (e.g., pairing inputs from two sources).

Data::zip(
    ['name' => ['Alice', 'Bob']],
    ['age' => [25, 30]]
)->it('should create user profiles', function ($name, $age) {
    $user = new User(compact('name', 'age'));
    $this->assertInstanceOf(User::class, $user);
});

5. Unions

Combine multiple datasets into a single test suite.

Data::union(
    Data::fromTuples([[1, 2]]),
    Data::fromArray(['extra' => [[3, 4]]])
)->it('should handle unioned data', function ($a, $b) {
    $this->assertGreaterThan(0, $a + $b);
});

Laravel Integration Tips

1. Leverage Laravel Factories

Generate test data using Laravel’s factories and pass them to datasets:

Data::fromTuples([
    [User::factory()->make()->toArray()],
    [User::factory()->create()->toArray()],
])->it('should handle user data', function ($userData) {
    $user = User::create($userData);
    $this->assertDatabaseHas('users', $userData);
});

2. Database Testing

Use RefreshDatabase with Testo by extending a custom test case:

use Illuminate\Foundation\Testing\RefreshDatabase;
use Testo\Testo;

class DatabaseTest extends Testo\TestCase {
    use RefreshDatabase;
}

Testo::describe('Database Operations', function () {
    Data::fromTuples([[1], [2]])->it('should insert records', function ($id) {
        DB::table('users')->insert(['id' => $id, 'name' => 'Test']);
        $this->assertDatabaseHas('users', ['id' => $id]);
    });
});

3. HTTP Testing

Combine with Testo’s HTTP plugin (if available) or use Laravel’s HttpTestCase:

Data::fromArray([
    'valid' => [['name' => 'John']],
    'invalid' => [['name' => '']],
])->it('should handle API requests', function ($data) {
    $response = $this->post('/api/users', $data);
    $response->assertStatus(201);
});

4. Custom Assertions

Create reusable assertions for Laravel-specific logic:

function assertValidation($model) {
    $this->assertTrue($model->isValid());
}

Test Organization

Group related datasets under a single Data::fromArray() call for readability.
Use descriptive names for datasets (e.g., valid_users, edge_cases).
Separate test files by feature/domain (e.g., UserValidationTest.php, PermissionTest.php).

Gotchas and Tips

Pitfalls

1. Testo vs. PHPUnit Syntax

Gotcha: Testo’s syntax differs from PHPUnit/Pest. For example:
- PHPUnit: @dataProvider, public function testCase($data).
- Testo: Data::fromTuples(...)->it('description', function ($data) { ... }).
Fix: Document the migration path for your team and provide cheat sheets.

2. Cartesian Explosion

Gotcha: Cartesian products can generate exponentially large test suites (e.g., 3 datasets with 10 items each = 1,000 test cases).
Fix:
- Limit dataset sizes.
- Use Data::sample() to test a subset:
```
Data::cross([...])->sample(5)->it(...);
```

3. Laravel-Specific Gaps

Gotcha: Testo lacks native support for Laravel’s create(), assertDatabaseHas(), etc.

Fix:

Create helper methods:

function createUser(array $data) {
    return User::factory()->create($data);
}

Or use PHPUnit’s beforeEach (if hybrid testing):

beforeEach(function () {
    $this->user = User::factory()->create();
});

4. Debugging Data Issues

Gotcha: Debugging failed test cases with complex datasets can be tricky.