adachsoft/phpunit-runner-tool

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

v0.1.1 2025-12-02 07:05 UTC

Requires

• php: ^8.3
• adachsoft/ai-tool-call: ^1.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.

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([
            'basePath' => '/path/to/your/project',
            'phpunitPath' => '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',
    'phpunitXml' => 'custom-phpunit.xml',
    'filter' => 'testUserCreation',
    'coverage' => false,
    'maxErrors' => 3,
    'timeout' => 60
]);

Configuration Options

Parameter	Type	Default	Description
path	string	null	Path to test file or directory
phpunitXml	string	null	Custom PHPUnit configuration file
filter	string	null	Test method name or pattern filter
coverage	bool	true	Enable code coverage
maxErrors	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([
    'basePath' => '/absolute/path/to/project',
    'phpunitPath' => 'vendor/bin/phpunit', // Relative to basePath or absolute
    'defaultCoverage' => true,
    'defaultMaxErrors' => 5,
    'defaultTimeout' => null
])

Response Format

The tool returns an array with:

[
    'stdout' => 'PHPUnit output...',
    'stderr' => 'Error output...',
    'exitCode' => 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 ^1.0
• adachsoft/command-executor-lib ^1.0

License

MIT