Getting Started

Minimal Setup

Install the package (PHP 8.2+ and PHPUnit 10 required as of v0.3.0):
```
composer require --dev tarantool/phpunit-extras
```

Extend Tarantool\PhpUnit\TestCase (or register the AttributeExtension / equivalent in phpunit.xml — the annotation-based extension from v0.2.x is gone):

use Tarantool\PhpUnit\TestCase;

class MyTarantoolTest extends TestCase {
    protected function getClient(): Client {
        return new Client('tcp://127.0.0.1:3301');
    }
}

First Use Case: Test a Lua operation with pre-execution setup via PHP attributes (annotations were removed in v0.3.0):

use Tarantool\PhpUnit\Attribute\Lua;

#[Lua("box.schema.space.create('test_space', {if_not_exists = true})")]
public function testSpaceCreation(): void
{
    $this->assertTrue($this->client->spaceExists('test_space'));
}

Implementation Patterns

Workflows

Pre-Test Setup: Use #[Lua] / #[Sql] attributes to initialize test data. Attributes can be repeated on the same method:

use Tarantool\PhpUnit\Attribute\Lua;
use Tarantool\PhpUnit\Attribute\Sql;

#[Sql("INSERT INTO users (id, name) VALUES (1, 'Alice')")]
#[Lua('box.space.users:select{1}')]
public function testUserFetch(): void
{
    $user = $this->client->select('users', 1);
    $this->assertEquals('Alice', $user['name']);
}

Request Validation: Assert Tarantool request behavior (e.g., caching):

public function testSpaceCache(): void
{
    $this->expectSelectRequestToBeCalledOnce();
    $this->client->getSpace('test_space');
    $this->client->getSpace('test_space'); // Should not trigger another request
}

Mocking Scenarios: Simulate server responses without a real Tarantool instance:

public function testErrorHandling(): void
{
    $mockClient = $this->getTestDoubleClientBuilder()
        ->shouldHandle(
            RequestTypes::EVALUATE,
            TestDoubleFactory::createErrorResponse('Error')
        )
        ->build();

    $this->expectException(TarantoolException::class);
    $mockClient->eval('box.error()');
}

Version-Specific Tests: Skip tests for unsupported Tarantool versions using the new attribute-based requirement (replaces the @requires annotation):

use Tarantool\PhpUnit\Attribute\RequiresTarantool;

#[RequiresTarantool('^2.3.0')]
public function testNewFeature(): void
{
    // Only runs if Tarantool >= 2.3.0
}

Integration Tips

Combine with tarantool/php: Use the official client alongside this package for seamless testing.

Environment Variables: Configure the attribute extension in phpunit.xml to use dynamic Tarantool endpoints (the extension class name changed in v0.3.0 — check the release docs; the annotation-based AnnotationExtension is removed):

<extensions>
    <bootstrap class="Tarantool\PhpUnit\Attribute\AttributeExtension">
        <arguments>
            <string>tcp://%env(TARANTOOL_HOST)%:%env(TARANTOOL_PORT)%</string>
        </arguments>
    </bootstrap>
</extensions>

Trait Composition: Mix RequestExpectations and PreparedStatementExpectations for comprehensive request tracking.
PHPUnit 10 config: Use the new <extensions> block and <bootstrap class="..."> syntax; the old <listeners> section is gone.

Gotchas and Tips

Pitfalls

Attribute Parsing:
- Issue: #[Lua] / #[Sql] attributes fail silently if the Tarantool server is unreachable.
- Fix: Use try-catch blocks or mock the client entirely for offline testing:
```
$mockClient = $this->createDummyClient();
```
Version Constraints:
- Issue: #[RequiresTarantool] may misinterpret version strings (e.g., 2.3 vs. 2.3.0).
- Fix: Use strict constraints like ^2.3.0 and verify with composer validate.
Mocking Quirks:
- Issue: TestDoubleClient may not handle custom request types (e.g., CALL2).
- Fix: Extend TestDoubleClientBuilder or use getMockBuilder() for unsupported types.
Upgrade from 0.2.x:
- Issue: Existing @lua, @sql, and @requires docblock annotations no longer work after upgrading to v0.3.0.
- Fix: Rewrite them as PHP 8 attributes. Also update phpunit.xml: PHPUnit 10 removed <listeners> in favor of <extensions>, and <coverage> schema changed. Run composer require phpunit/phpunit:^10 and fix composer constraints for PHP 8.2+.

Debugging

Enable Verbose Logging: PHPUnit 10 no longer supports <listeners>; use <extensions> and --debug to inspect attribute processing:
```
vendor/bin/phpunit --debug
```
Check Expectation Failures: Use verifyExpectations() in a #[After] (PHPUnit 10 attribute) hook to catch unmet request expectations:
```
use PHPUnit\Framework\Attributes\After;

#[After]
public function verify(): void
{
    $this->verifyExpectations();
}
```
PHPUnit 10 schema errors: When upgrading, run vendor/bin/phpunit --migrate-configuration to auto-convert the old phpunit.xml to the PHPUnit 10 format.

Extension Points

Custom Attributes: Extend the package's attribute base classes to add Tarantool-specific requirements (e.g., #[RequiresSpace('users')]):

use Tarantool\PhpUnit\Attribute\Requirement;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
class RequiresSpace extends Requirement
{
    public function __construct(private readonly string $space) {}
    public function check(): bool { /* ... */ }
}

Dynamic Client Configuration: Override getClient() to inject dependencies (e.g., custom packers):

protected function getClient(): Client {
    return new Client('tcp://localhost:3301', [
        'packer' => new CustomPacker(),
    ]);
}

Test Data Fixtures: Combine attribute-based setup with PHPUnit lifecycle hooks for hybrid initialization:

use PHPUnit\Framework\Attributes\Before;

#[Before]
protected function truncate(): void
{
    $this->client->eval('box.space.users:truncate()');
}

Performance Tips

Mock Heavy Tests: Use TestDoubleClient to avoid real Tarantool I/O in CI pipelines.

Batch Attributes: Repeat #[Lua] / #[Sql] attributes on the same method to minimize connection overhead:

#[Lua('box.space.users:create()')]
#[Lua("box.space.users:format({{name = 'string'}})")]
public function testSetup(): void { /* ... */ }

Phpunit Extras Laravel Package