Files
camelia-orm/tests/Unit/Seeding/SeederRunnerTest.php
T
dgarcia 2acf2cc099 feat(seeding): add the seeder concept with an idempotent runner
A seeder fills reference or bootstrap data - the permission catalogue, the
built-in roles, the first administrator. It is not a migration: it never
touches the schema, it runs on demand, and it must be safe to run twice.

- Seeder: the contract (name + run).
- AbstractSeeder: seedOnce() inserts only when the criteria match nothing and
  records inserted/skipped counts. It never overwrites a row a user edited.
- SeederRunner: runs an ordered batch inside one transaction, so a failing
  seeder leaves the database untouched. Supports running a named subset.
- SeederResult: per-seeder outcome for reporting.
- ConfigurationException::unknownSeeder() lists the registered names.

docs/SEEDING.md documents the contract and how to write one.
2026-11-15 13:30:54 -03:00

206 lines
5.7 KiB
PHP

<?php
declare(strict_types=1);
namespace Camelia\Orm\Tests\Unit\Seeding;
use Camelia\Orm\Exception\ConfigurationException;
use Camelia\Orm\Orm;
use Camelia\Orm\Seeding\AbstractSeeder;
use Camelia\Orm\Seeding\Seeder;
use Camelia\Orm\Seeding\SeederRunner;
use Camelia\Orm\Tests\Fixture\Usuario;
use Camelia\Orm\Tests\Support\FakeConnection;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
final class SeederRunnerTest extends TestCase
{
private FakeConnection $connection;
private Orm $orm;
protected function setUp(): void
{
$this->connection = new FakeConnection();
$this->orm = Orm::fromConnection($this->connection);
}
#[Test]
public function it_runs_seeders_in_registration_order(): void
{
$log = new \ArrayObject();
$runner = new SeederRunner($this->orm)->addMany([
$this->recordingSeeder('first', $log),
$this->recordingSeeder('second', $log),
]);
$runner->run();
self::assertSame(['first', 'second'], $log->getArrayCopy());
}
#[Test]
public function it_wraps_the_batch_in_one_transaction(): void
{
$log = new \ArrayObject();
new SeederRunner($this->orm)->add($this->recordingSeeder('only', $log))->run();
self::assertSame(1, $this->connection->beginCount);
self::assertSame(1, $this->connection->commitCount);
self::assertSame(0, $this->connection->rollBackCount);
}
#[Test]
public function it_rolls_back_the_whole_batch_when_a_seeder_throws(): void
{
$log = new \ArrayObject();
$failing = new class implements Seeder {
public function name(): string
{
return 'failing';
}
public function run(Orm $orm): void
{
throw new \RuntimeException('boom');
}
};
$runner = new SeederRunner($this->orm)->addMany([
$this->recordingSeeder('ok', $log),
$failing,
]);
$this->expectException(\RuntimeException::class);
try {
$runner->run();
} finally {
self::assertSame(1, $this->connection->rollBackCount);
self::assertSame(0, $this->connection->commitCount);
}
}
#[Test]
public function it_lists_registered_names(): void
{
$log = new \ArrayObject();
$runner = new SeederRunner($this->orm)->addMany([
$this->recordingSeeder('roles', $log),
$this->recordingSeeder('admin-user', $log),
]);
self::assertSame(['roles', 'admin-user'], $runner->names());
}
#[Test]
public function it_runs_only_the_requested_seeders_in_the_requested_order(): void
{
$log = new \ArrayObject();
$runner = new SeederRunner($this->orm)->addMany([
$this->recordingSeeder('permissions', $log),
$this->recordingSeeder('roles', $log),
$this->recordingSeeder('admin-user', $log),
]);
$runner->run(['admin-user', 'permissions']);
self::assertSame(['admin-user', 'permissions'], $log->getArrayCopy());
}
#[Test]
public function it_rejects_an_unknown_seeder_name(): void
{
$log = new \ArrayObject();
$runner = new SeederRunner($this->orm)->add($this->recordingSeeder('known', $log));
$this->expectException(ConfigurationException::class);
$this->expectExceptionMessage('Unknown seeder(s): nope');
$runner->run(['nope']);
}
#[Test]
public function it_does_nothing_without_seeders(): void
{
$results = new SeederRunner($this->orm)->run();
self::assertSame([], $results);
self::assertSame(0, $this->connection->beginCount);
}
#[Test]
public function it_reports_inserted_and_skipped_counts(): void
{
$this->connection->rowBatches = [
[],
[['codigo' => '1']],
];
$seeder = new class extends AbstractSeeder {
public function name(): string
{
return 'counted';
}
public function run(Orm $orm): void
{
$repository = $orm->repository(Usuario::class);
$this->seedOnce($repository, ['correo' => 'a@x'], ['clave' => 'a']);
$this->seedOnce($repository, ['correo' => 'b@x'], ['clave' => 'b']);
}
};
$results = new SeederRunner($this->orm)->add($seeder)->run();
self::assertCount(1, $results);
self::assertSame(1, $results[0]->inserted);
self::assertSame(1, $results[0]->skipped);
self::assertTrue($results[0]->isSuccessful());
}
#[Test]
public function a_plain_seeder_reports_zero_counts(): void
{
$log = new \ArrayObject();
$results = new SeederRunner($this->orm)->add($this->recordingSeeder('plain', $log))->run();
self::assertSame(0, $results[0]->inserted);
self::assertTrue($results[0]->isNoOp());
}
/**
* @param \ArrayObject<int, string> $log
*/
private function recordingSeeder(string $name, \ArrayObject $log): Seeder
{
return new class($name, $log) implements Seeder {
/**
* @param \ArrayObject<int, string> $log
*/
public function __construct(
private readonly string $label,
private readonly \ArrayObject $log,
) {}
public function name(): string
{
return $this->label;
}
public function run(Orm $orm): void
{
$this->log->append($this->label);
}
};
}
}