[11.x] Enhance testability of batched jobs

[rust17]

The current approach to testing batched jobs, as shown below, is somewhat unconventional:

Bus::assertBatched(fn (PendingBatchFake $batchedCollection) =>
    $batchedCollection->jobs->count() === 1 && $batchedCollection->jobs->first()->value === 'hello';
);

This pull request introduces some helper functions to enhance the testability of batched jobs. Inspired by fluent JSON testing, these methods provide a more streamlined and readable approach to testing job batches within the Laravel application. The goal is to improve developer experience by offering clear, concise methods with illustrative examples.

Example Usage

has

public function has(string|int $expectedJob, array $expectedParameters = [])

Assert that the batch contains a job of the given type. You can also pass an integer to assert that the batch contains the exact number of jobs.

Example:

Bus::fake();

Bus::batch([
    new AJob(1, 2),
    new BJob,
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->has(2)
        ->has(AJob::class, [1, 2])
);

missing

public function missing(string $expectedJob)

Assert that the batch does not contain a job of the given type.

Example:

Bus::fake();

Bus::batch([
    new BJob,
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->missing(AJob::class)
);

hasAll

public function hasAll(array $expectedJobs)

Assert that the batch contains all of the given jobs.

Example:

Bus::fake();

Bus::batch([
    new AJob,
    new BJob,
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->hasAll([AJob::class, BJob::class])
);

missingAll

public function missingAll(array $expectedJobs)

Assert that the batch does not contain any of the given jobs.

Example:

Bus::fake();

Bus::batch([
    new AJob,
    new BJob,
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->missingAll([CJob::class, DJob::class])
);

hasAny

public function hasAny(...$expectedJobs)

Assert that the batch contains any of the given jobs.

Example:

Bus::fake();

Bus::batch([
    new AJob(1, 2),
    new BJob,
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->hasAny(AJob::class, CJob::class)
);

first

public function first(callable $callback)

Assert that the first job in the batch matches the given callback.

Example:

Bus::fake();

Bus::batch([
    [
        new AJob(1, 2),
        new BJob,
    ],
    new CJob,
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->first(fn (PendingBatchFake $firstBatch) =>
        $firstBatch->has(AJob::class, [1, 2])
            ->has(BJob::class)
    )
);

nth

public function nth(int $index, callable|string $callback, array $parameters = [])

Assert that the nth job in the batch matches the given callback or type and parameters.

Example:

Bus::fake();

Bus::batch([
    [
        new AJob(1, 2),
        new BJob
    ],
    new CJob::class(1)
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->nth(0, fn (PendingBatchFake $batch) =>
        $batch->has(AJob::class, [1, 2])
            ->has(BJob::class)
    )->nth(1, CJob::class, [1])
);

equal

public function equal(array $expectedJobs)

Assert that the batch contains exactly the given jobs with the specified parameters.

Example:

Bus::fake();

Bus::batch([
    [
        new AJob(1, 2),
        new BJob
    ],
    new CJob::class(1)
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->equal([
        [
            AJob::class => [1, 2],
            BJob::class
        ],
        CJob::class => [1]
    ])
);

etc

public function etc()

Assert that the batch has unexpected jobs beyond those checked.

Example:

Bus::fake();

Bus::batch([
    new AJob(1, 2),
    new BJob,
    new CJob::class(1)
])->dispatch();

Bus::assertBatched(fn (PendingBatchFake $batch) =>
    $batch->has(AJob::class, [1, 2])
        ->has(BJob::class)
        ->etc()
);

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.