adachsoft/phpunit-runner-tool

Flexible PHPUnit runner tool for adachsoft/ai-tool-call (SPI tool for running tests with filters, coverage and safe paths)

0.2.0 2025-12-05 08:02 UTC

Requires

• php: ^8.3
• adachsoft/ai-tool-call: ^2.0.0
• adachsoft/command-executor-lib: ^1.0
• adachsoft/normalized-safe-path: ^0.1.0

Requires (Dev)

• adachsoft/php-code-style: ^0.2.1
• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4

MIT

• Arkadiusz Adach

• cli
• phpunit
• tool
• runner
• ai-tool-call

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

Register the tool with adachsoft/ai-tool-call:

use AdachSoft\AiToolCall\AiToolCallFacadeBuilder;
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

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'
]);

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
phpunit_xml	string	null	Custom PHPUnit configuration file
filter	string	null	Test method name or pattern filter
coverage	bool	true	Enable code coverage
max_errors	int	5	Maximum detailed errors to return
timeout	int	null	Execution timeout in seconds

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' => 5,
    'default_timeout' => null
])

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 // Boolean based on exit code
]

Error Handling

The tool throws ToolExecutionException for:

• Non-existent test paths
• Invalid PHPUnit configuration
• Command execution failures
• Timeout errors
• Permission issues

Requirements

• PHP >= 8.3
• PHPUnit installed in target project
• adachsoft/ai-tool-call ^2.0.0
• adachsoft/command-executor-lib ^1.0

License

MIT