PHPackages                             dave-liddament/test-splitter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. dave-liddament/test-splitter

ActiveProject[Testing & Quality](/categories/testing)

dave-liddament/test-splitter
============================

Splits up PHPUnit tests so they can be ran in parallel (e.g. on GitHub actions)

0.4.0(5mo ago)20430.0k↑12.8%2MITPHPPHP 8.1.\*|8.2.\*|8.3.\*|8.4.\*|8.5.\*CI passing

Since Sep 28Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/DaveLiddament/test-splitter)[ Packagist](https://packagist.org/packages/dave-liddament/test-splitter)[ RSS](/packages/dave-liddament-test-splitter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (6)Versions (6)Used By (0)

PHPUnit test case splitter
==========================

[](#phpunit-test-case-splitter)

[![PHP versions: 8.1|8.2|8.3|8.4|8.5](https://camo.githubusercontent.com/f0eab91c543484b640295950ac332833e43da58129d629c67aec8ffe8bab0eb6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e31253743382e32253743382e33253743382e34253743382e352d626c75652e737667)](https://packagist.org/packages/dave-liddament/test-splitter)[![Latest Stable Version](https://camo.githubusercontent.com/c458880634e98e794e88a128dbdf87e4200355039fd0ca9777cfe3a5bd78b25c/68747470733a2f2f706f7365722e707567782e6f72672f646176652d6c696464616d656e742f746573742d73706c69747465722f762f737461626c65)](https://packagist.org/packages/dave-liddament/test-splitter)[![License](https://camo.githubusercontent.com/1e4b31cb541f77dd68ec8d7f855f29511e7e77c18c1a2edad9e99d91375dd600/68747470733a2f2f706f7365722e707567782e6f72672f646176652d6c696464616d656e742f746573742d73706c69747465722f6c6963656e7365)](https://github.com/DaveLiddament/test-splitter/blob/master/LICENSE.md)[![Total Downloads](https://camo.githubusercontent.com/645de269a61d4f82e9ce88cefd7d6890795d0387a10c51b8a6256e6a95a17e6d/68747470733a2f2f706f7365722e707567782e6f72672f646176652d6c696464616d656e742f746573742d73706c69747465722f646f776e6c6f616473)](https://packagist.org/packages/dave-liddament/test-splitter/stats)

[![Continuous Integration](https://github.com/DaveLiddament/test-splitter/workflows/Checks/badge.svg)](https://github.com/DaveLiddament/test-splitter/actions)[![PHPStan max](https://camo.githubusercontent.com/ecb39a33957e802f1f085f1debada1e99904e72b8d807e98991fb7f9660cb6d3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6d61782532306c6576656c2d627269676874677265656e2e737667)](https://github.com/DaveLiddament/sarb/blob/master/phpstan.neon)

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
-----

[](#usage)

Install via [Composer](https://getcomposer.org):

```
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
-----------

[](#cicd-usage)

### GitHub Actions

[](#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

[](#gitlab-cicd)

```
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](https://docs.gitlab.com/ci/variables/predefined_variables/) `CI_NODE_INDEX` and `CI_NODE_TOTAL` are used to automatically specify the batch number and total number of batches.

Additional documentation
------------------------

[](#additional-documentation)

- [Code of Conduct](docs/CodeOfConduct.md)
- [Contributing](docs/Contributing.md)

Alternative tools
-----------------

[](#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](https://github.com/paratestphp/paratest) - You'll need to use the [shard functionality](https://github.com/paratestphp/paratest/pull/1013) introduced in September 2025.
- [Shipmonk's PHPUnit parallel job balancer](https://github.com/shipmonk-rnd/phpunit-parallel-job-balancer) created in December 2025.

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance70

Regular maintenance activity

Popularity46

Moderate usage in the ecosystem

Community13

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 65.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~379 days

Total

5

Last Release

179d ago

PHP version history (2 changes)0.2.0PHP 8.1.\*|8.2.\*|8.3.\*|8.4.\*

0.4.0PHP 8.1.\*|8.2.\*|8.3.\*|8.4.\*|8.5.\*

### Community

Maintainers

![](https://www.gravatar.com/avatar/dc81fab8d878316b9117eb3a8fe3abece1d25a37c3099d76c6f3651f82991505?d=identicon)[DaveLiddament](/maintainers/DaveLiddament)

---

Top Contributors

[![DaveLiddament](https://avatars.githubusercontent.com/u/6787687?v=4)](https://github.com/DaveLiddament "DaveLiddament (23 commits)")[![spawnia](https://avatars.githubusercontent.com/u/12158000?v=4)](https://github.com/spawnia "spawnia (11 commits)")[![OrbisK](https://avatars.githubusercontent.com/u/37191683?v=4)](https://github.com/OrbisK "OrbisK (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/dave-liddament-test-splitter/health.svg)

```
[![Health](https://phpackages.com/badges/dave-liddament-test-splitter/health.svg)](https://phpackages.com/packages/dave-liddament-test-splitter)
```

###  Alternatives

[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[brianium/paratest

Parallel testing for PHP

2.5k118.8M754](/packages/brianium-paratest)[beberlei/assert

Thin assertion library for input validation in business models.

2.4k96.9M570](/packages/beberlei-assert)[mikey179/vfsstream

Virtual file system to mock the real file system in unit tests.

1.4k108.0M2.7k](/packages/mikey179-vfsstream)[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.1k](/packages/orchestra-testbench)[phpspec/phpspec

Specification-oriented BDD framework for PHP 7.1+

1.9k36.7M3.1k](/packages/phpspec-phpspec)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)