[Bug]: --update-shards fails with --parallel --processes because --processes is forwarded to --list-tests

[xibn]

What Happened

When running Pest with --update-shards, --parallel, and an explicit process count via --processes=4, Pest fails before running the tests.

Expected behavior:

--update-shards should work together with --parallel --processes=4 and update tests/.pest/shards.json.

Actual behavior:

Pest internally calls --list-tests and forwards --processes=4 to that command. The --list-tests command does not accept --processes, so the run fails with:

The command "'php' './vendor/bin/pest' '--processes=4' '--filter=__DefinitelyNoSuchTest__' '--cache-directory' '.../vendor/pestphp/pest/.temp' '--no-output' '--list-tests'" failed.

Exit Code: 2(Misuse of shell builtins)

Output:
================

INFO Unknown option "--processes". Most similar options are --covers, --colors, --group, --no-progress, --no-results.

This also happens in CI when running without the artificial filter:

./vendor/bin/pest --parallel --processes="$PEST_PARALLEL_WORKERS" --update-shards

How to Reproduce

In a project using Pest 4.7.5, run:

./vendor/bin/pest --parallel --processes=4 --update-shards --filter='__DefinitelyNoSuchTest__'

The filter is only used to make the reproduction fast and avoid running the full test suite. The failure happens while Pest is collecting the test list for shard timing updates.

The same issue occurs with a normal run such as:

./vendor/bin/pest --parallel --processes=4 --update-shards

Sample Repository

No response

Pest Version

4.7.5

PHP Version

8.4.10

Operation System

macOS, Linux

Notes

I reproduced this on Pest 4.7.5.

The relevant code seems to be in Pest\Plugins\Shard::removeParallelArguments(). It currently removes only --parallel and -p before calling --list-tests, but it does not remove --processes, --processes=4, or possibly --max-processes.

Current behavior in vendor/pestphp/pest/src/Plugins/Shard.php:

private function removeParallelArguments(array $arguments): array
{
    return array_filter($arguments, fn (string $argument): bool => ! in_array($argument, ['--parallel', '-p'], strict: true));
}

So the internal command still receives --processes=4 together with --list-tests, which causes the failure.

This looks fixed on the 5.x branch, where removeParallelArguments() strips arguments starting with --processes, but the fix does not appear to be present in the latest stable 4.x release (4.7.5).

I would be happy to open a pull request for the 4.x branch if maintainers would like this backported there.