Phpunit Extras Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require --dev tarantool/phpunit-extras
   

2. Extend Tarantool\PhpUnit\TestCase (or use the AnnotationExtension in phpunit.xml):

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

3. First Use Case: Test a Lua operation with pre-execution setup:

   /**
    * @lua box.schema.space.create('test_space', {if_not_exists = true})
    */
   public function testSpaceCreation() {
       $this->assertTrue($this->client->spaceExists('test_space'));
   }
   

Implementation Patterns

Workflows

1. Pre-Test Setup: Use @lua/@sql annotations to initialize test data:

   /**
    * @sql INSERT INTO users (id, name) VALUES (1, 'Alice')
    * @lua box.space.users:select{1}
    */
   public function testUserFetch() {
       $user = $this->client->select('users', 1);
       $this->assertEquals('Alice', $user['name']);
   }
   

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

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

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

   public function testErrorHandling() {
       $mockClient = $this->getTestDoubleClientBuilder()
           ->shouldHandle(
               RequestTypes::EVALUATE,
               TestDoubleFactory::createErrorResponse('Error')
           )
           ->build();
   
       $this->expectException(TarantoolException::class);
       $mockClient->eval('box.error()');
   }
   

4. Version-Specific Tests: Skip tests for unsupported Tarantool versions:

   /**
    * @requires Tarantool ^2.3.0
    */
   public function testNewFeature() {
       // 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 AnnotationExtension in phpunit.xml to use dynamic Tarantool endpoints:

  <extension class="Tarantool\PhpUnit\Annotation\AnnotationExtension">
      <arguments><string>tcp://%env(TARANTOOL_HOST)%:%env(TARANTOOL_PORT)%</string></arguments>
  </extension>
  

• Trait Composition: Mix RequestExpectations and PreparedStatementExpectations for comprehensive request tracking.

Gotchas and Tips

Pitfalls

1. Annotation Parsing:

   • Issue: @lua/@sql annotations fail silently if the Tarantool server is unreachable.
   • Fix: Use try-catch blocks or mock the client entirely for offline testing:

     $mockClient = $this->createDummyClient();
     

2. Version Constraints:

   • Issue: @requires Tarantool 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.

3. Mocking Quirks:

   • Issue: TestDoubleClient may not handle custom request types (e.g., CALL2).
   • Fix: Extend TestDoubleClientBuilder or use getMockBuilder() for unsupported types.

Debugging

• Enable Verbose Logging: Configure PHPUnit to show annotation processing:

  <phpunit ...>
      <listeners>
          <listener class="Tarantool\PhpUnit\Annotation\AnnotationListener" />
      </listeners>
  </phpunit>
  

• Check Expectation Failures: Use verifyExpectations() in @after methods to catch unmet request expectations.

Extension Points

1. Custom Annotations: Extend rybakit/phpunit-extras to add Tarantool-specific requirements (e.g., @requires spaceExists):

   class SpaceExistsRequirement extends AbstractRequirement {
       public function check(): bool { /* ... */ }
   }
   

2. 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(),
       ]);
   }
   

3. Test Data Fixtures: Combine @lua/@sql with setUp() for hybrid initialization:

   public function setUp(): 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 Annotations: Group @lua/@sql annotations to minimize connection overhead:

  /**
   * @lua box.space.users:create()
   * @lua box.space.users:format({{name = 'string'}})
   */