How to shard PHPUnit tests with GitHub Actions

This article goes over how to shard PHPUnit tests with GitHub Actions.

PHPUnit

Motivation

If you run your PHPUnit tests sequentially in GitHub Actions, it can take a long time if you have a lot of tests.

With test sharding, you divide your tests to speed up test runtime. As a result, this means your tests run in parallel for faster build times.

Although you can write a Bash script to do this, there’s already a GitHub Action called find-and-split that automates this for you.

Test Sharding

Let’s say you have a GitHub Actions workflow that runs PHPUnit tests sequentially:

# .github/workflows/test.yml
name: test
on: push

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install dependencies
        run: composer install

      - name: Run tests
        run: vendor/bin/phpunit tests

With find-and-split and the matrix strategy, you can split your tests into 2 jobs based on the number of test files:

 # .github/workflows/test.yml
 name: test
 on: push

jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shard: [1/2, 1/2]

     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

       - name: Install dependencies
         run: composer install

+      - name: Find and split files
+        uses: remarkablemark/find-and-split@v1
+        id: tests
+        with:
+          chunk: ${{ matrix.shard }}
+          directory: tests
+          pattern: '*Test.php'

       - name: Run tests
-        run: vendor/bin/phpunit tests
+        run: vendor/bin/phpunit ${{ steps.tests.outputs.files }}

Resources

For more details, check out the test repository.

This article was originally published on remarkablemark.org on February 16, 2025.