PHPUnit test case splitter

Have you got a slow running PHPUnit test suite?

Do you want to split your tests over separate instances? If so, PHPUnit test case splitter might help. It splits tests into batches in a deterministic way. Each batch of tests can run in separate instances (e.g. by using a matrix in GitHub actions).

Usage

Install via Composer:

composer require --dev dave-liddament/test-splitter

This package provides an executable under vendor/bin/tsplit that takes two arguments: batch, and number of batches. It accepts a list of tests piped into stdin and outputs the tests for the specified batch to stdout.

To split the tests into 4 batches and run the first batch you can do:

vendor/bin/phpunit --filter `vendor/bin/phpunit --list-tests | vendor/bin/tsplit 1 4`

To run the second batch out of 4 you'd use:

vendor/bin/phpunit --filter `vendor/bin/phpunit --list-tests | vendor/bin/tsplit 2 4`

CI/CD Usage

GitHub Actions

Add this to your GitHub actions:

jobs:
  tests:
  
    strategy:
      fail-fast: false
      matrix: 
        test-batch: [1, 2, 3, 4]

    steps: 
      # Steps to checkout code, setup environment, etc.

      - name: "Tests batch ${{ matrix.test--batch }}"
        run: vendor/bin/phpunit --filter `vendor/bin/phpunit --list-tests | vendor/bin/tsplit ${{ matrix.test-batch }} 4`

This will split the tests over 4 different jobs.

GitLab CI/CD

test:
  stage: test
  parallel: 4
  script:
    - vendor/bin/phpunit --filter `vendor/bin/phpunit --list-tests | vendor/bin/tsplit ${CI_NODE_INDEX} ${CI_NODE_TOTAL}`

This will split the tests over 4 different jobs. GitLabs predefined variables CI_NODE_INDEX and CI_NODE_TOTAL are used to automatically specify the batch number and total number of batches.

Additional documentation

• Code of Conduct
• Contributing

Alternative tools

Test splitter is a very simple tool. It was created in 2021, at the time no other tools did something similar. It solved a problem I had on a couple of client projects.

Since 2021 other tools that do similar things have been developed. If you want more mature or more feature rich tools then try these:

• Paratest - You'll need to use the shard functionality introduced in September 2025.
• Shipmonk's PHPUnit parallel job balancer created in December 2025.