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.
This commit is contained in:
1 parent
02703f40ab
commit
2acf2cc099
7 files changed
+542
No files matched your search
@@ -0,0 +1,205 @@
|
||||
<?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);
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user