A parallel-first test framework for PHP 8.4 and later.

Greenlight runs test classes in parallel by default and has zero runtime dependencies. Greenlight discovers one suite and sends assignments to a pool of worker processes.

Read the documentation

Greenlight runs its own test suite with bin/greenlight run.

Capabilities

• Parallel test execution with a dynamic schedule
• Resource limits for shared databases and services
• Worker recycle, leak detection, crash recovery, timeouts, and process isolation
• Strict mocks, stubs, and spies with automatic verification
• Typed expectations with clear differences
• Stable CI shards and deterministic reports
• Test attachments for values, text, bytes, and files
• Coverage through pcov or Xdebug
• Plain PHP test classes and PHP configuration
• First-party Symfony, Laravel, and PHPStan extensions
• Automated PHPUnit test conversion with a bundled Rector rule

Example test

<?php

declare(strict_types=1);

namespace App\Tests;

use Greenlight\Attribute\DataRow;
use Greenlight\Attribute\Test;
use Greenlight\Expect\Expect;

final class PriceTest
{
    #[Test]
    #[DataRow(['9.99', 2, '19.98'], label: 'two units')]
    #[DataRow(['0.50', 3, '1.50'], label: 'three small units')]
    public function multipliesLineTotals(string $unit, int $quantity, string $expected): void
    {
        $total = Price::fromString($unit)->times($quantity);

        Expect::that($total->format())->toBe($expected);
    }

    #[Test]
    public function rejectsNegativeQuantities(): void
    {
        Expect::that(static function (): void {
            Price::fromString('9.99')->times(-1);
        })->toThrow(\InvalidArgumentException::class, matching: '/quantity/');
    }
}

Tests use typed PHP classes. Attributes identify tests, before and after methods, data sets, retries, timeouts, skip conditions, groups, resource requirements, and isolation.

Constructor injection supplies fixtures, doubles, and services from plugins.

Start

Install Greenlight as a development dependency:

composer require --dev greenlight/greenlight

Create greenlight.php in the project root:

<?php

declare(strict_types=1);

use Greenlight\Config\GreenlightConfig;

return GreenlightConfig::create()
    ->paths(['tests'])
    ->workers(count: 'auto');

Run the suite:

vendor/bin/greenlight run

See the start guide for a complete example.

Execution model

Greenlight discovers each test class once and creates an execution plan. Workers request assignments when they have capacity.

The orchestrator controls resource limits, worker replacement, event checks, and reports. It also stores test durations to improve the order of later runs.

Greenlight normally schedules complete test classes. It schedules each #[Isolated] test separately. It preserves the method order in a class, but different workers can run different classes.

Use a channel to give each worker a separate external resource. Use #[RequiresResource] to limit concurrent access to a shared resource.

See worker lifecycle and scheduling for the complete model.

Documentation

• Start with Greenlight
• Configuration reference
• Attribute reference
• Expectations
• Test doubles
• Write plugins
• Test attachments
• Static analysis with PHPStan
• Test Symfony applications
• Test Laravel applications
• Move from PHPUnit
• Benchmarks
• Architecture
• Contribute

Requirements and limits

Greenlight requires PHP 8.4 or later. The parallel runner uses core stream sockets and proc_open.

Coverage requires pcov or Xdebug. Greenlight does not run PHPUnit suites directly.

License

MIT. See LICENSE.