README

PHPUnit extension to re-run only failed tests.

Installation

composer require --dev mracos/phpunit-run-failed

Usage

1. Add Extension to PHPUnit Configuration

Add the extension to your phpunit.xml:

<phpunit>
    <!-- your existing configuration -->
    <extensions>
        <bootstrap class="PhpUnitRunFailed\FailedTestRerunnerExtension" />
    </extensions>
</phpunit>

2. Ignore where we store the last failed tests

Failed test information is stored in .phpunit-failed-tests.json in your project root. Add this to your .gitignore:

.phpunit-failed-tests.json

3. Run Tests Normally

vendor/bin/phpunit

The extension automatically tracks any failed tests.

3. Re-run Only Failed Tests

Use PHPUnit's native --testsuite option:

vendor/bin/phpunit --testsuite=failed

Compatibility

PHP: 8.0+
PHPUnit: 10.0+, 11.0+
Integration: Works with existing PHPUnit configurations and other extensions

Test Project

This repository includes a test-project/ directory that serves as an integration test for the extension. It demonstrates how the extension works in a real PHPUnit environment.

What is the Test Project?

The test-project/ is a minimal PHP project that:

Has its own composer.json with PHPUnit as a dependency
Includes sample test files with intentionally failing tests
Demonstrates the full extension workflow in isolation
Serves as a reference implementation for integration

How to Use the Test Project

Navigate to the test project:
```
cd test-project
```
Install dependencies (automatically done):
```
composer install
```
Run the initial test suite (creates failures):
```
vendor/bin/phpunit
```
This will run the tests with several intentional failures and errors:
Test the --testsuite=failed functionality:
```
vendor/bin/phpunit --testsuite=failed
```

Should re-run only the failing tests.

Uncomment what makes the tests passes. Should see No recorded failed tests found. Running empty test suite.

mracos / phpunit-run-failed

Maintainers

Details