adachsoft / phpunit-runner-lib

v0.2.0 2026-09-22 06:22 UTC

Requires

• php: >=8.3
• adachsoft/collection: ^3.0
• adachsoft/command-executor-lib: ^2.0
• adachsoft/normalized-safe-path: ^0.1

Requires (Dev)

• adachsoft/php-code-style: ^0.7.1
• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4
• rector/rector: ^2.3
• symplify/phpstan-rules: 14.10.*

MIT

• php
• cli
• testing
• phpunit
• test-runner

Published on Packagist.org on 2026-09-22 04:22 UTC

README

A PHP library for running PHPUnit through the command line and converting test output into structured results.

Features

• Execute PHPUnit with a configurable working directory and binary path.
• Run a complete test suite or target a specific path.
• Support PHPUnit configuration files, filters, groups, coverage, and timeouts.
• Capture standard output, error output, exit codes, and a human-readable summary.
• Parse failures, errors, warnings, notices, and deprecations into file issues.
• Work safely with relative test paths.
• Discover available logical PHP versions and run PHPUnit with a selected version.
• Keep PHP interpreter paths internal while exposing version metadata through DTOs.

Requirements

• PHP 8.3 or newer.
• PHPUnit available in the configured project.

Installation

composer require adachsoft/phpunit-runner-lib

Basic usage

<?php

declare(strict_types=1);

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;
use AdachSoft\PhpUnitRunnerLib\Config\PhpUnitRunnerConfigDto;
use AdachSoft\PhpUnitRunnerLib\Dto\RunPhpUnitRequestDto;
use AdachSoft\PhpUnitRunnerLib\Parser\PhpUnitOutputParser;
use AdachSoft\PhpUnitRunnerLib\PhpUnitRunner;

$projectRoot = dirname(__DIR__);

$runner = new PhpUnitRunner(
    new PhpUnitRunnerConfigDto(
        basePath: $projectRoot,
        phpUnitPath: 'vendor/bin/phpunit',
        defaultTimeout: 60,
    ),
    new SimpleCommandExecutor(),
    new PhpUnitOutputParser(),
);

$result = $runner->run(
    new RunPhpUnitRequestDto(
        path: 'tests',
        coverage: false,
    ),
);

if (!$result->success) {
    foreach ($result->fileIssues->all() as $issue) {
        printf("%s:%s [%s] %s\n", $issue->file, $issue->line ?? '-', $issue->type, $issue->message);
    }
}

printf("Exit code: %d\n%s\n", $result->exitCode, $result->summary);

Selecting a PHP version

Use PhpUnitRunnerFactory when the runner must discover and select a logical PHP version through the system alternatives configuration:

<?php

declare(strict_types=1);

use AdachSoft\CommandExecutorLib\SimpleCommandExecutor;
use AdachSoft\PhpUnitRunnerLib\Config\PhpUnitRunnerConfigDto;
use AdachSoft\PhpUnitRunnerLib\Dto\RunPhpUnitRequestDto;
use AdachSoft\PhpUnitRunnerLib\PhpUnitRunnerFactory;

$runner = PhpUnitRunnerFactory::create(
    new PhpUnitRunnerConfigDto(
        basePath: dirname(__DIR__),
        phpUnitPath: 'vendor/bin/phpunit',
    ),
    new SimpleCommandExecutor(),
);

foreach ($runner->listAvailableVersions()->all() as $version) {
    printf("%s%s\n", $version->version, $version->isCurrent ? ' (current)' : '');
}

$result = $runner->run(
    new RunPhpUnitRequestDto(
        path: 'tests',
        phpVersion: '8.3',
        coverage: false,
    ),
);

The selected version is validated against the available alternatives before execution. Interpreter paths are resolved internally and are not exposed by the public DTOs.

Configuration

PhpUnitRunnerConfigDto accepts the project base path, the PHPUnit binary path, an optional default timeout, and flags controlling PHPUnit notices, warnings, and deprecations.

RunPhpUnitRequestDto can target a path and can provide a PHP version, PHPUnit XML configuration, filter, group, coverage flag, and per-run timeout. The runner returns a RunPhpUnitResultDto containing the raw output, exit code, summary, success state, and a FileIssueCollection.

See the examples for focused usage patterns.

License

MIT