README

Flexible PHPUnit runner tool for adachsoft/ai-tool-call. This library provides a single, versatile tool to run PHPUnit tests in various project configurations.

⚠️ Breaking Changes in v0.2.0

Configuration keys changed from camelCase to snake_case to comply with adachsoft/ai-tool-call 2.0.0 standards:

basePath → base_path
phpunitPath → phpunit_path
defaultCoverage → default_coverage
defaultMaxErrors → default_max_errors
defaultTimeout → default_timeout

Installation

composer require adachsoft/phpunit-runner-tool

Quick Start

use AdachSoft\AiToolCall\AiToolCallFacadeBuilder;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\PhpUnitRunnerTool\Tool\PhpUnitRunnerToolFactory;

$facade = (new AiToolCallFacadeBuilder())
    ->withSpiFactories([new PhpUnitRunnerToolFactory()])
    ->withToolConfigs([
        'phpunit_runner' => new ConfigMap([
            'base_path' => '/path/to/your/project',
            'phpunit_path' => 'vendor/bin/phpunit',
        ]),
    ])
    ->build();

Usage Examples

Run All Tests

$result = $facade->callTool('phpunit_runner', []);
// Runs all tests with default configuration
// Internally, PHPUnit is invoked with flags like --display-phpunit-notices,
// --display-phpunit-deprecations and --display-skipped by default.

Run Single Test File

$result = $facade->callTool('phpunit_runner', [
    'path' => 'tests/Unit/UserServiceTest.php',
]);

Run Tests in Directory

$result = $facade->callTool('phpunit_runner', [
    'path' => 'tests/Integration',
]);

Select a PHP Version

$result = $facade->callTool('phpunit_runner', [
    'operation' => 'run',
    'php_version' => '8.3',
]);

List Available PHP Versions

$result = $facade->callTool('phpunit_runner', [
    'operation' => 'list_php_versions',
]);

The list operation returns only logical versions:

[
    'available_versions' => ['8.2', '8.3'],
    'current_version' => '8.3',
]

The tool never exposes PHP interpreter paths, alternative metadata, or command strings.

With Custom Configuration

$result = $facade->callTool('phpunit_runner', [
    'path' => 'tests/Unit',
    'phpunit_xml' => 'custom-phpunit.xml',
    'filter' => 'testUserCreation',
    'coverage' => false,
    'max_errors' => 3,
    'timeout' => 60,
]);

Configuration Options

Parameter	Type	Default	Description
`path`	string	null	Path to test file or directory (relative to `base_path` or absolute). Empty string is treated as `null` and runs all tests.
`phpunit_xml`	string	null	Custom PHPUnit configuration file (relative to `base_path` or absolute).
`filter`	string	null	Test method name or pattern filter.
`coverage`	bool	true	Enable code coverage.
`max_errors`	int	20	Maximum detailed errors to return.
`timeout`	int	null	Execution timeout in seconds for this call. Cannot exceed configured `max_timeout` (if set).
`php_version`	string	null	Logical PHP version in `major.minor` or `major.minor.patch` form. Used only with `operation=run`.
`operation`	string	`run`	Either `run` or `list_php_versions`.

Configuration in ToolFactory

When registering the tool, you can configure:

new ConfigMap([
    'base_path' => '/absolute/path/to/project',
    'phpunit_path' => 'vendor/bin/phpunit', // Relative to base_path or absolute
    'default_coverage' => true,
    'default_max_errors' => 20,
    'max_output_chars' => 10000,      // Maximum output characters returned by the tool
    'default_timeout' => null,       // Default timeout when per-call timeout is not provided
    'max_timeout' => null,           // Optional hard cap for per-call timeout (int > 0 or null for no limit)
    'display_notices' => false,      // Display notices during test execution (adds --display-notices)
    'display_warnings' => false,     // Display warnings during test execution (adds --display-warnings)
    'display_deprecations' => false, // Display deprecations during test execution (adds --display-deprecations)
    'display_phpunit_notices' => true,      // Display PHPUnit framework notices (adds --display-phpunit-notices)
    'display_phpunit_deprecations' => true, // Display PHPUnit framework deprecations (adds --display-phpunit-deprecations)
])

By default, the underlying runner always passes --display-phpunit-notices, --display-phpunit-deprecations and --display-skipped to PHPUnit so that framework-level notices, deprecations and skipped tests are visible without additional configuration.

Response Format

The tool returns an array with:

[
    'stdout' => 'PHPUnit output...',
    'stderr' => 'Error output...',
    'exit_code' => 0, // 0 for success, >0 for failure
    'success' => true, // Value reported by the runner library
]

Error Handling

The tool throws PhpUnitTestExecutionException for infrastructure failures:

Non-existent test paths
Invalid PHPUnit configuration
Command execution failures
Timeout errors
Unavailable PHP versions

A PHPUnit process that exits with a non-zero code is returned as a normal result with success => false; it is not converted into a tool exception.

Error messages do not expose interpreter paths, host configuration paths, environment variables, or complete command strings.

Additionally, the tool throws InvalidArgumentException when:

path points to an excluded folder configured via excluded_folders
timeout or max_errors parameters are of invalid types
timeout exceeds the configured max_timeout limit when such a limit is set

Static Analysis & Code Style

This project uses the shared adachsoft/php-code-style configuration for:

PHP-CS-Fixer ruleset (imported via .php-cs-fixer.php → vendor/adachsoft/php-code-style/.php-cs-fixer.dist.php),
PHPStan configuration (via phpstan.neon including vendor/adachsoft/php-code-style/phpstan.neon.dist),
Rector base config (imported via rector.php → vendor/adachsoft/php-code-style/rector.dist.php).

Recommended Composer scripts:

"scripts": {
    "cs:check": "php-cs-fixer fix --dry-run --diff --config=.php-cs-fixer.php",
    "cs:fix": "php-cs-fixer fix --config=.php-cs-fixer.php",
    "stan": "phpstan analyse",
    "rector": "rector"
}

Run tools via:

composer cs:check   # check coding style
composer cs:fix     # auto-fix coding style
composer stan       # run PHPStan analysis
composer rector     # run Rector refactoring

Requirements

PHP >= 8.3
PHPUnit installed in target project
adachsoft/ai-tool-call ^2.0.0
adachsoft/command-executor-lib ^2.0
adachsoft/phpunit-runner-lib ^0.2.0

License

MIT

adachsoft / phpunit-runner-tool

Package info

Security

Statistics