boltci/shards

Patch PHPUnit and Paratest to shard your Laravel test suite.

v0.1.2 2025-12-11 02:40 UTC

Requires

• php: ^8.2
• brianium/paratest: ^7.2.0
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• illuminate/testing: ^10.0|^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.22
• phpunit/phpunit: ^11.5

MIT

README

Patch PHPUnit and Paratest to shard your Laravel test suite.

Caveats

Both Pest (as of version 4.0.0) and ParaTest (as of version 7.13.0) support test sharding natively, in more robust ways than this package provides.

You should only use this as a last resort if your version of testing framework does not support sharding natively.

Supported Versions

• PHP 8.2 or higher
• Laravel 10.x or higher
• PHPUnit 10.x or higher
• ParaTest 7.2.0 or higher

Installation

Install the package via Composer:

composer require boltci/shards --dev

Usage

1. Patch PHPUnit

Before running your tests, patch PHPUnit to enable sharding:

php artisan shards:patch-phpunit

This command modifies the PHPUnit test suite builder to shard tests based on your environment configuration.

2. Patch ParaTest

If you're using ParaTest versions between 7.2.0 and 7.4.2, you may need to apply a compatibility patch:

php artisan shards:patch-paratest

Note: ParaTest 7.4.3 and above have the issue fixed and don't require patching.

3. Run Your Tests

Run your tests with the SHARD environment variable set to specify which shard to run. The format is x/y, where x is the shard number and y is the total number of shards.

SHARD=1/5 php artisan test

You can optionally set the SEED variable to any positive integers to shuffle the test order using a deterministic seed (i.e. the same seed will always produce the same test order):

SHARD=1/5 SEED=1 php artisan test

When using ParaTest (by passing --parallel), include the --functional flag to parallelize by Test to avoid overlaps between shards:

SHARD=1/5 SEED=1 php artisan test --parallel --functional

This is useful to help distribute tests more evenly across shards.

Credits

• The first version of this code was first written for internal use at Springloaded.
• The use of the word "shard" and the "x/y" shard notation was later adapted from Pest.

License

The MIT License (MIT). Please see License File for more information.