phpunit-parallel

phpunit-parallel

A CLI tool to run PHPUnit tests in parallel, with a beautiful terminal UI.

Features

• Parallel test execution - Distributes tests across multiple workers using round-robin scheduling
• Interactive terminal UI - Real-time progress bars, per-worker status, and ETA powered by Bubble Tea
• Rerun failed tests - Press r to rerun only failures, or a to rerun all tests, without leaving the UI
• Deprecation tracking - Parses and displays PHPUnit deprecation warnings with source locations
• Lifecycle hooks - Run custom commands before/after test runs and before/after each worker
• Docker support - Run each worker in its own container using hooks and the {} placeholder
• TeamCity output - Native TeamCity format for CI integration (JetBrains TeamCity, GitHub Actions, etc.)
• Runner configuration file - Define reusable settings in phpunit-parallel.xml
• PHPUnit compatible - Reads your existing phpunit.xml / phpunit.xml.dist and preserves all settings
• Test filtering - Filter tests with --filter, --group, and --exclude-group
• Copy errors to clipboard - Copy individual or all errors/deprecations with keyboard shortcuts
• IDE integration - Included PHP wrapper script for PhpStorm interop
• Cross-platform - Pre-built binaries for Linux and macOS (amd64/arm64)

Installation

Using Homebrew (Recommended)

brew install alexdempster44/tap/phpunit-parallel

Using Go

go install github.com/alexdempster44/phpunit-parallel@latest

From Releases

Download the pre-built binary for your platform from the releases page.

Usage

# Run with default settings (uses phpunit.xml in current directory)
phpunit-parallel

# Specify number of workers
phpunit-parallel -w 4

# Specify PHPUnit configuration file
phpunit-parallel -c phpunit.xml.dist

# Filter tests
phpunit-parallel --filter testLogin
phpunit-parallel --group integration
phpunit-parallel --exclude-group slow

# Use TeamCity output format (for CI)
phpunit-parallel --teamcity

CLI Flags

Environment Variables

The following environment variables are exposed to hooks and workers:

Terminal UI

The interactive TUI features a three-panel layout:

• Top-left - Running tests panel (switches to a summary after completion)
• Bottom-left - Per-worker progress bars with percentage and test counts
• Right - Error and deprecation panel with expandable details

Keyboard Shortcuts

When piped or redirected, output falls back to a plain-text format automatically.

Runner Configuration File

For reusable or complex setups, create a phpunit-parallel.xml file:

<runner>
    <workers>4</workers>
    <configuration>phpunit.xml</configuration>
    <config-build-dir>.phpunit-parallel</config-build-dir>
    <test-suffix>Test.php</test-suffix>
    <before>echo "Starting test run"</before>
    <before-worker>echo "Setting up worker $WORKER_ID"</before-worker>
    <run-worker>vendor/bin/phpunit</run-worker>
    <after-worker>echo "Cleaning up worker $WORKER_ID"</after-worker>
    <after>echo "Test run complete"</after>
</runner>

Use it with:

phpunit-parallel --runner-config phpunit-parallel.xml

If phpunit-parallel.xml exists in the current directory, it is loaded automatically.

Docker Example

Run each worker in its own Docker container:

<runner>
    <workers>4</workers>
    <before-worker>docker run -d --name "phpunit-worker-$WORKER_ID" -v "$(pwd)":/app -w /app php:8.3-cli sleep infinity</before-worker>
    <run-worker>docker exec "phpunit-worker-$WORKER_ID" php vendor/bin/phpunit {}</run-worker>
    <after-worker>docker rm -f "phpunit-worker-$WORKER_ID"</after-worker>
</runner>

The {} placeholder in run-worker is replaced with the generated PHPUnit arguments (configuration path, flags, filters, etc.).

Output Modes

Building from Source

# Clone the repository
git clone https://github.com/alexdempster44/phpunit-parallel.git
cd phpunit-parallel

# Build
go build -o bin/phpunit-parallel .

# Or using just
just build

License

This is free and unencumbered software released into the public domain. See the LICENSE file for details.