From ad3bfa56f5ccff00cedca21b763fc9b12618e225 Mon Sep 17 00:00:00 2001 From: Steve Bauman Date: Sat, 3 Oct 2026 11:39:15 -0400 Subject: [PATCH 1/2] Allow running a specific operation by filename --- README.md | 36 ++++++++++++ src/Commands/RunCommand.php | 7 ++- src/Runner.php | 26 ++++++++- tests/Feature/RunSelectedTest.php | 91 +++++++++++++++++++++++++++++++ tests/Feature/RunTest.php | 24 ++++---- 5 files changed, 168 insertions(+), 16 deletions(-) create mode 100644 tests/Feature/RunSelectedTest.php diff --git a/README.md b/README.md index 7a6923b..2161f43 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,42 @@ The runner stops when an operation throws an exception. The command fails, the o The filename without `.php` is the operation's identity. Keep completed filenames unchanged and create another operation when you need a correction. Operations do not support rollbacks. +To run a single pending operation, pass its exact filename without `.php`: + +```bash +php artisan operations:run 2026_10_03_120000_backfill_company_names +``` + +The name must contain only letters, numbers, underscores, and hyphens. Paths, the `.php` extension, and partial names are not accepted. Invalid or unknown names fail without running any operations. + +Only the selected operation runs. It uses the same transaction support and completion ledger as a full run, and is skipped if already completed. Its file must still exist, even if it has a completion record. + +### Testing Operations + +Call the command from a Laravel/Pest feature test to exercise a specific operation: + +```php +use App\Models\Company; +use Illuminate\Foundation\Testing\RefreshDatabase; + +uses(RefreshDatabase::class); + +test('company names are backfilled', function () { + $company = Company::factory()->create([ + 'name' => 'Acme', + 'display_name' => null, + ]); + + $this->artisan('operations:run', [ + 'operation' => '2026_10_03_120000_backfill_company_names', + ])->assertSuccessful(); + + expect($company->fresh()->display_name)->toBe('Acme'); +}); +``` + +Use your application's Laravel test case and a dedicated test database with the published operations migration. `RefreshDatabase` resets the completion ledger between tests; invoking the same operation twice within a test skips it on the second call. If you configure a separate `operations.connection`, point it to a test database and include it in your database reset setup. + ### Checking Status ```bash diff --git a/src/Commands/RunCommand.php b/src/Commands/RunCommand.php index 21f6df9..9117bc5 100644 --- a/src/Commands/RunCommand.php +++ b/src/Commands/RunCommand.php @@ -16,14 +16,16 @@ class RunCommand extends Command implements Isolatable * * @var string */ - protected $signature = 'operations:run {--force : Run operations in production without confirmation}'; + protected $signature = 'operations:run + {operation? : The exact operation filename without the .php extension} + {--force : Run operations in production without confirmation}'; /** * The console command description. * * @var string */ - protected $description = 'Run all pending deployment operations'; + protected $description = 'Run pending deployment operations'; /** * Execute the console command. @@ -47,6 +49,7 @@ public function handle(Runner $runner): int $this->components->twoColumnDetail($name, "{$duration}s DONE"); $this->newLine(); }, + operation: $this->argument('operation'), ); $this->components->info($count ? "Completed {$count} operation(s)." : 'No pending operations.'); diff --git a/src/Runner.php b/src/Runner.php index 9209d98..8414d60 100644 --- a/src/Runner.php +++ b/src/Runner.php @@ -5,6 +5,7 @@ use Closure; use Illuminate\Console\Command; use Illuminate\Filesystem\Filesystem; +use InvalidArgumentException; use UnexpectedValueException; class Runner @@ -41,12 +42,13 @@ public function files(): array * @param (Closure(string): void)|null $before * @param (Closure(string, float): void)|null $after */ - public function run(Command $command, ?Closure $before = null, ?Closure $after = null): int + public function run(Command $command, ?Closure $before = null, ?Closure $after = null, ?string $operation = null): int { + $files = $operation === null ? $this->files() : $this->find($operation); $completed = $this->repository->completed(); $count = 0; - foreach ($this->files() as $name => $path) { + foreach ($files as $name => $path) { if ($completed->has($name)) { continue; } @@ -70,4 +72,24 @@ public function run(Command $command, ?Closure $before = null, ?Closure $after = return $count; } + + /** + * Find an operation by its exact filename without the extension. + * + * @return array + */ + protected function find(string $name): array + { + if (! preg_match('/\A[a-zA-Z0-9_-]+\z/', $name)) { + throw new InvalidArgumentException('Use an exact operation filename without .php, containing only letters, numbers, underscores, and hyphens.'); + } + + $files = $this->files(); + + if (! isset($files[$name])) { + throw new InvalidArgumentException("Operation [{$name}] not found. Use its exact filename without .php."); + } + + return [$name => $files[$name]]; + } } diff --git a/tests/Feature/RunSelectedTest.php b/tests/Feature/RunSelectedTest.php new file mode 100644 index 0000000..3bff02c --- /dev/null +++ b/tests/Feature/RunSelectedTest.php @@ -0,0 +1,91 @@ +push(\Illuminate\Support\Facades\DB::transactionLevel()); + $command->info('Selected operation executed.'); + } + }; + PHP); + + app()->instance('transaction_levels', collect()); + + artisan('operations:run', ['operation' => '2026_10_03_120000_selected']) + ->expectsOutputToContain('Selected operation executed.') + ->expectsOutputToContain('Completed 1 operation(s).') + ->assertSuccessful(); + + $completedAt = DB::table('operations')->value('completed_at'); + + artisan('operations:run', ['operation' => '2026_10_03_120000_selected']) + ->expectsOutputToContain('No pending operations.') + ->assertSuccessful(); + + expect(app('transaction_levels')->all())->toBe([1]) + ->and(DB::table('operations')->pluck('name')->all())->toBe(['2026_10_03_120000_selected']) + ->and($completedAt)->not->toBeNull() + ->and(DB::table('operations')->value('completed_at'))->toBe($completedAt); +}); + +test('invalid selections fail clearly without loading any operations', function (string $operation, string $message) { + File::ensureDirectoryExists(config('operations.path')); + + foreach (['2026_10_03_120000_backfill', '2026_10_03_130000_backfill'] as $name) { + File::put(config('operations.path')."/{$name}.php", 'registerCommand(app(RunCommand::class)); + $exitCode = $kernel->handle(new ArrayInput([ + 'command' => 'operations:run', + 'operation' => $operation, + ]), $output); + + expect($exitCode)->toBe(1) + ->and($output->fetch())->toContain($message) + ->and(DB::table('operations')->count())->toBe(0); +})->with([ + 'missing filename' => ['2026_10_03_140000_missing', 'not found'], + 'ambiguous suffix' => ['backfill', 'not found'], + 'ambiguous prefix' => ['2026_10_03', 'not found'], + 'empty argument' => ['', 'Use an exact operation filename'], + 'whitespace' => [' ', 'Use an exact operation filename'], + 'extension' => ['2026_10_03_120000_backfill.php', 'Use an exact operation filename'], + 'relative path' => ['./2026_10_03_120000_backfill', 'Use an exact operation filename'], + 'absolute path' => ['/2026_10_03_120000_backfill', 'Use an exact operation filename'], + 'traversal' => ['../2026_10_03_120000_backfill', 'Use an exact operation filename'], + 'windows traversal' => ['..\\2026_10_03_120000_backfill', 'Use an exact operation filename'], + 'wildcard' => ['2026_10_03_*', 'Use an exact operation filename'], +]); + +test('a selected filename must exist even when already completed', function () { + DB::table('operations')->insert([ + 'name' => '2026_10_03_120000_missing', + 'completed_at' => now(), + ]); + + expect(fn () => artisan('operations:run', ['operation' => '2026_10_03_120000_missing'])->run()) + ->toThrow(InvalidArgumentException::class, 'Operation [2026_10_03_120000_missing] not found.'); +}); diff --git a/tests/Feature/RunTest.php b/tests/Feature/RunTest.php index c71a74a..6663f3f 100644 --- a/tests/Feature/RunTest.php +++ b/tests/Feature/RunTest.php @@ -84,7 +84,7 @@ public function handle(\Illuminate\Console\Command $command): void ])->and(DB::table('operations')->count())->toBe(3); }); -test('a transaction rolls back database changes when an operation fails', function () { +test('a transaction rolls back database changes when an operation fails', function (?string $operation) { Schema::create('examples', function (Blueprint $table) { $table->id(); }); @@ -103,13 +103,13 @@ public function handle(\Illuminate\Console\Command $command): void }; PHP); - expect(fn () => app(Runner::class)->run(app(RunCommand::class)))->toThrow(RuntimeException::class, 'Backfill failed.'); + expect(fn () => Artisan::call('operations:run', ['operation' => $operation]))->toThrow(RuntimeException::class, 'Backfill failed.'); expect(DB::table('examples')->count())->toBe(0) ->and(DB::table('operations')->count())->toBe(0); -}); +})->with([null, '2026_10_02_120000_backfill']); -test('a transaction rolls back the operation if recording completion fails', function () { +test('a transaction rolls back the operation if recording completion fails', function (?string $operation) { Schema::create('examples', function (Blueprint $table) { $table->id(); }); @@ -130,11 +130,11 @@ public function handle(\Illuminate\Console\Command $command): void }; PHP); - expect(fn () => app(Runner::class)->run(app(RunCommand::class)))->toThrow(QueryException::class); + expect(fn () => Artisan::call('operations:run', ['operation' => $operation]))->toThrow(QueryException::class); expect(DB::table('examples')->count())->toBe(0) ->and(DB::table('operations')->count())->toBe(0); -}); +})->with([null, '2026_10_02_120000_backfill']); test('operations can dispatch jobs without becoming queued operations themselves', function () { Bus::fake(); @@ -159,14 +159,14 @@ public function handle(\Illuminate\Console\Command $command): void expect(DB::table('operations')->count())->toBe(1); }); -test('completed operation files are not loaded on subsequent runs', function () { +test('completed operation files are not loaded on subsequent runs', function (?string $operation) { File::ensureDirectoryExists(config('operations.path')); File::put(config('operations.path').'/2026_10_02_120000_old.php', 'insert(['name' => '2026_10_02_120000_old', 'completed_at' => now()]); - artisan('operations:run')->expectsOutputToContain('No pending operations.')->assertSuccessful(); -}); + artisan('operations:run', ['operation' => $operation])->expectsOutputToContain('No pending operations.')->assertSuccessful(); +})->with([null, '2026_10_02_120000_old']); test('invalid operation files fail without being recorded', function () { File::ensureDirectoryExists(config('operations.path')); @@ -198,7 +198,7 @@ public function handle(\Illuminate\Console\Command $command): void artisan('operations:run')->expectsOutputToContain('No pending operations.')->assertSuccessful(); }); -test('operation exceptions produce a failing console exit code', function () { +test('operation exceptions produce a failing console exit code', function (?string $operation) { File::ensureDirectoryExists(config('operations.path')); File::put(config('operations.path').'/2026_10_02_120000_failure.php', <<<'PHP' registerCommand(app(RunCommand::class)); - $exitCode = $kernel->handle(new ArrayInput(['command' => 'operations:run']), $output); + $exitCode = $kernel->handle(new ArrayInput(['command' => 'operations:run', 'operation' => $operation]), $output); expect($exitCode)->toBe(1) ->and($output->fetch())->toContain('Backfill failed.') ->and(DB::table('operations')->count())->toBe(0); -}); +})->with([null, '2026_10_02_120000_failure']); From 871c444f1d262dd87bab7c981aec5e589f5e34f5 Mon Sep 17 00:00:00 2001 From: Steve Bauman Date: Sun, 4 Oct 2026 13:51:15 -0400 Subject: [PATCH 2/2] Simplify operation tests and clarify testing guidance --- README.md | 6 +++++- tests/Feature/RunSelectedTest.php | 33 +++++++++++-------------------- tests/Feature/RunTest.php | 27 ------------------------- 3 files changed, 17 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 2161f43..9eaffa3 100644 --- a/README.md +++ b/README.md @@ -113,6 +113,8 @@ Call the command from a Laravel/Pest feature test to exercise a specific operati use App\Models\Company; use Illuminate\Foundation\Testing\RefreshDatabase; +use function Pest\Laravel\artisan; + uses(RefreshDatabase::class); test('company names are backfilled', function () { @@ -121,7 +123,7 @@ test('company names are backfilled', function () { 'display_name' => null, ]); - $this->artisan('operations:run', [ + artisan('operations:run', [ 'operation' => '2026_10_03_120000_backfill_company_names', ])->assertSuccessful(); @@ -131,6 +133,8 @@ test('company names are backfilled', function () { Use your application's Laravel test case and a dedicated test database with the published operations migration. `RefreshDatabase` resets the completion ledger between tests; invoking the same operation twice within a test skips it on the second call. If you configure a separate `operations.connection`, point it to a test database and include it in your database reset setup. +To test whether an operation can safely resume after partial work, create that partial state without a completion record, run the operation, and assert the expected result. Running a completed operation again only verifies that it is skipped. + ### Checking Status ```bash diff --git a/tests/Feature/RunSelectedTest.php b/tests/Feature/RunSelectedTest.php index 3bff02c..c33aff1 100644 --- a/tests/Feature/RunSelectedTest.php +++ b/tests/Feature/RunSelectedTest.php @@ -1,15 +1,15 @@ push(\Illuminate\Support\Facades\DB::transactionLevel()); $command->info('Selected operation executed.'); } }; PHP); - app()->instance('transaction_levels', collect()); - artisan('operations:run', ['operation' => '2026_10_03_120000_selected']) ->expectsOutputToContain('Selected operation executed.') ->expectsOutputToContain('Completed 1 operation(s).') @@ -37,12 +34,13 @@ public function handle(\Illuminate\Console\Command $command): void $completedAt = DB::table('operations')->value('completed_at'); + travel(1)->minute(); + artisan('operations:run', ['operation' => '2026_10_03_120000_selected']) ->expectsOutputToContain('No pending operations.') ->assertSuccessful(); - expect(app('transaction_levels')->all())->toBe([1]) - ->and(DB::table('operations')->pluck('name')->all())->toBe(['2026_10_03_120000_selected']) + expect(DB::table('operations')->pluck('name')->all())->toBe(['2026_10_03_120000_selected']) ->and($completedAt)->not->toBeNull() ->and(DB::table('operations')->value('completed_at'))->toBe($completedAt); }); @@ -54,18 +52,11 @@ public function handle(\Illuminate\Console\Command $command): void File::put(config('operations.path')."/{$name}.php", 'registerCommand(app(RunCommand::class)); - $exitCode = $kernel->handle(new ArrayInput([ - 'command' => 'operations:run', + expect(fn () => artisan('operations:run', [ 'operation' => $operation, - ]), $output); + ])->run())->toThrow(InvalidArgumentException::class, $message); - expect($exitCode)->toBe(1) - ->and($output->fetch())->toContain($message) - ->and(DB::table('operations')->count())->toBe(0); + expect(DB::table('operations')->count())->toBe(0); })->with([ 'missing filename' => ['2026_10_03_140000_missing', 'not found'], 'ambiguous suffix' => ['backfill', 'not found'], diff --git a/tests/Feature/RunTest.php b/tests/Feature/RunTest.php index 6663f3f..1350f23 100644 --- a/tests/Feature/RunTest.php +++ b/tests/Feature/RunTest.php @@ -5,14 +5,11 @@ use DirectoryTree\Operations\Tests\Fixtures\ExampleJob; use Illuminate\Database\QueryException; use Illuminate\Database\Schema\Blueprint; -use Illuminate\Foundation\Console\Kernel; use Illuminate\Support\Facades\Artisan; use Illuminate\Support\Facades\Bus; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\File; use Illuminate\Support\Facades\Schema; -use Symfony\Component\Console\Input\ArrayInput; -use Symfony\Component\Console\Output\BufferedOutput; use function Pest\Laravel\artisan; @@ -197,27 +194,3 @@ public function handle(\Illuminate\Console\Command $command): void test('a missing operations directory has no pending work', function () { artisan('operations:run')->expectsOutputToContain('No pending operations.')->assertSuccessful(); }); - -test('operation exceptions produce a failing console exit code', function (?string $operation) { - File::ensureDirectoryExists(config('operations.path')); - File::put(config('operations.path').'/2026_10_02_120000_failure.php', <<<'PHP' - registerCommand(app(RunCommand::class)); - $exitCode = $kernel->handle(new ArrayInput(['command' => 'operations:run', 'operation' => $operation]), $output); - - expect($exitCode)->toBe(1) - ->and($output->fetch())->toContain('Backfill failed.') - ->and(DB::table('operations')->count())->toBe(0); -})->with([null, '2026_10_02_120000_failure']);