adachsoft / sandbox-tool-contract-tests

v0.1.0 2026-10-22 16:07 UTC

Requires

• php: ^8.3
• adachsoft/ai-tool-call: ^1.0 || ^2.0
• adachsoft/collection: ^3.0
• adachsoft/normalized-safe-path: ^0.1
• adachsoft/sandbox-contracts: ^0.1
• phpunit/phpunit: ^11.0 || ^12.0 || ^13.0

Requires (Dev)

• adachsoft/php-code-style: ^0.7.1
• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.3
• phpstan/phpstan-phpunit: ^2.0
• rector/rector: ^2.7
• symplify/phpstan-rules: ^14.9

MIT

• Arkadiusz Adach

• filesystem
• security
• phpunit
• sandbox
• tool
• tests
• contracts

Published on Packagist.org on 2026-10-22 14:12 UTC

README

adachsoft/sandbox-tool-contract-tests is a PHPUnit library for verifying that SPI tools respect filesystem sandbox boundaries.

Requirements

• PHP 8.3 or newer
• Composer
• Tools implementing AdachSoft\AiToolCall\SPI\ToolInterface and factories implementing AdachSoft\AiToolCall\SPI\Factory\ToolFactoryInterface

Installation

composer require --dev adachsoft/sandbox-tool-contract-tests

The library provides a PHPUnit base test case, so PHPUnit is declared as a package dependency.

Usage

Extend AbstractSandboxToolTestCase and call assertSandboxToolPasses() from a PHPUnit test method:

<?php

declare(strict_types=1);

use AdachSoft\SandboxToolContractTests\AbstractSandboxToolTestCase;
use AdachSoft\SandboxToolContractTests\PublicApi\Dto\SandboxToolTestTargetDto;
use App\Tools\ReadFileToolFactory;

final class ReadFileSandboxContractTest extends AbstractSandboxToolTestCase
{
    public function testReadFileToolPassesSandboxContract(): void
    {
        $this->assertSandboxToolPasses(
            new SandboxToolTestTargetDto(new ReadFileToolFactory()),
        );
    }
}

Replace ReadFileToolFactory with a factory for your tool. The default verifier checks the configured base path, path traversal, leading-slash handling, path disclosure on success and I/O errors, and symlink escapes.

If a path parameter cannot be inferred from the tool definition, pass a PathParameterVoCollection to SandboxToolTestTargetDto. Use PathParameterKindEnum::SCALAR_STRING for a single path and PathParameterKindEnum::STRING_LIST for a list of paths. Configure result fields containing paths with the DTO's outputPathKeys argument.

Direct verification

For custom integrations, create a verifier and inspect its report:

<?php

declare(strict_types=1);

use AdachSoft\SandboxToolContractTests\PublicApi\Dto\SandboxToolTestTargetDto;
use AdachSoft\SandboxToolContractTests\SandboxToolContractVerifier;
use App\Tools\ReadFileToolFactory;

$target = new SandboxToolTestTargetDto(new ReadFileToolFactory());
$report = (new SandboxToolContractVerifier())->verifyTarget($target);

if (!$report->isPassed()) {
    throw new RuntimeException($report->formatFailureMessage());
}

SandboxVerificationReportDto contains the detected SandboxRuleViolationDto values. Use isPassed() to check the result and formatFailureMessage() to produce a diagnostic message.