PHPackages                             tarantool/phpunit-extras - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. tarantool/phpunit-extras

ActiveLibrary[Testing & Quality](/categories/testing)

tarantool/phpunit-extras
========================

A collection of helpers for PHPUnit to ease testing Tarantool libraries.

v0.2.1(3y ago)277.5k↑23%12MITPHPPHP ^7.2.5|^8CI failing

Since May 7Pushed 3w ago2 watchersCompare

[ Source](https://github.com/tarantool-php/phpunit-extras)[ Packagist](https://packagist.org/packages/tarantool/phpunit-extras)[ GitHub Sponsors](https://github.com/rybakit)[ RSS](/packages/tarantool-phpunit-extras/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (7)Versions (15)Used By (2)

PHPUnit Extras
==============

[](#phpunit-extras)

[![Quality Assurance](https://github.com/tarantool-php/phpunit-extras/workflows/QA/badge.svg)](https://github.com/tarantool-php/phpunit-extras/actions?query=workflow%3AQA)[![Telegram](https://camo.githubusercontent.com/fcbb762172f6027f3e2f84b45d2f561a6c730200c819552f3cf384015c3c782f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54656c656772616d2d6a6f696e253230636861742d626c75652e737667)](https://t.me/tarantool_php)

A collection of helpers for [PHPUnit](https://phpunit.de/) to ease testing [Tarantool](https://www.tarantool.io/en/developers/) libraries. It is based on [rybakit/phpunit-extras](https://github.com/rybakit/phpunit-extras), please refer to this package for more documentation.

Table of contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Annotations](#annotations)
    - [Processors](#processors)
        - [Lua](#lua)
        - [Sql](#sql)
    - [Requirements](#requirements)
        - [LuaCondition](#luacondition)
        - [TarantoolVersion](#tarantoolversion)
- [Expectations](#expectations)
    - [Requests](#requests)
    - [Prepared statements](#prepared-statements)
- [Mocking](#mocking)
- [Testing](#testing)
- [License](#license)

Installation
------------

[](#installation)

```
composer require --dev tarantool/phpunit-extras
```

Annotations
-----------

[](#annotations)

Besides the annotations provided by the package `rybakit/phpunit-extras`, the library is shipped with annotations specific to Tarantool. The easiest way to enable them is by inheriting your test classes from `Tarantool\PhpUnit\TestCase`:

```
use Tarantool\Client\Client;
use Tarantool\PhpUnit\TestCase;

final class MyTest extends TestCase
{
    protected function getClient() : Client
    {
        // TODO: Implement getClient() method.
    }

    // ...
}
```

Another option is to register an extension called `AnnotationExtension`:

```

```

By default, the extension assumes that the Tarantool server you are going to connect to is available on `127.0.0.1:3301`. You can customize the default settings by specifying either a [DSN string](https://github.com/tarantool-php/client#dsn-string) or an [array of options](https://github.com/tarantool-php/client#array-of-options)as extension configuration values:

```

        tcp://127.0.0.1:3301/?socket_timeout=10

```

or

```

                tcp://127.0.0.1:3301

                10

```

On top of that, the configuration values can resolve environment variables, which might be useful if you need to share the same settings with a Tarantool instance file or any other script:

```

        tcp://%env(TARANTOOL_HOST)%:%env(TARANTOOL_PORT)%

```

Once the annotations are configured, you can start using them:

### Processors

[](#processors)

#### Lua

[](#lua)

Allows executing Lua code before running a test.

*Example:*

```
/**
 * @lua tube:put('kick_me')
 * @lua tube:bury(0)
 */
public function testKickReleasesBuriedTask() : void
{
    // ...
}
```

#### Sql

[](#sql)

Allows executing SQL statements before running a test (requires Tarantool 2.0+).

*Example:*

```
/**
 * @sql DROP TABLE IF EXISTS foobar
 * @sql CREATE TABLE foobar (id INTEGER PRIMARY KEY, name VARCHAR(50))
 * @sql INSERT INTO foobar VALUES (1, 'A'), (2, 'B')
 */
public function testExecuteQueryFetchesAllRows() : void
{
    // ...
}
```

### Requirements

[](#requirements)

Requirements allow skipping tests based on preconditions.

#### LuaCondition

[](#luacondition)

*Format:*

```
@requires luaCondition

```

where `` is an arbitrary lua expression that should be evaluated to a Boolean value.

*Example:*

```
/**
 * @requires luaCondition box.session.user() ~= 'guest'
 */
public function testChangeUserPassword() : void
{
    // ...
}
```

#### TarantoolVersion

[](#tarantoolversion)

*Format:*

```
@requires Tarantool

```

where `` is a composer-like version constraint. For details on supported formats, please see the Composer [documentation](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints).

*Example:*

```
/**
 * @requires Tarantool ^2.3.2
 */
public function testPrepareCreatesPreparedStatement() : void
{
    // ...
}
```

> *If you're interested in how to create and register your own annotations and requirements, please refer to the `rybakit/phpunit-extras` [README](https://github.com/rybakit/phpunit-extras).*

Expectations
------------

[](#expectations)

### Requests

[](#requests)

To test that your code sends (or does not send) certain requests, the following methods are available:

- `TestCase::expectRequestToBeCalled(int $count) : void`
- `TestCase::expectRequestToBeCalledAtLeast(int $count) : void`
- `TestCase::expectRequestToBeCalledAtMost(int $count) : void`
- `TestCase::expectRequestToBeCalledOnce() : void`
- `TestCase::expectRequestToBeCalledAtLeastOnce() : void`
- `TestCase::expectRequestToBeCalledAtMostOnce() : void`
- `TestCase::expectRequestToBeNeverCalled() : void`
- `TestCase::expectNoRequestToBeCalled() : void`

where `` is the name of the request, for example `Call`, `Insert`, etc. These methods are part of the `Tarantool\PhpUnit\TestCase` class, but they can also be enabled through a trait:

```
use PHPUnit\Framework\TestCase;
use PHPUnitExtras\Expectation\Expectations as BaseExpectations;
use Tarantool\Client\Client;
use Tarantool\PhpUnit\Expectation\RequestExpectations;

final class MyTest extends TestCase
{
    use BaseExpectations;
    use RequestExpectations;

    protected function getClient() : Client
    {
        // TODO: Implement getClient() method.
    }

    /**
     * @after
     */
    protected function verifyTestCaseExpectations() : void
    {
        $this->verifyExpectations();
    }

    // ...
}
```

*Example:*

```
public function testGetSpaceIsCached() : void
{
    $this->client->flushSpaces();

    $this->expectSelectRequestToBeCalledOnce();
    $this->client->getSpace('test_space');
    $this->client->getSpace('test_space');
}
```

### Prepared statements

[](#prepared-statements)

In order to assert prepared statement allocations, use the `Tarantool\PhpUnit\Expectation\PreparedStatementExpectations` trait, which contains the following methods:

- `expectPreparedStatementToBe(int $count) : void`
- `expectPreparedStatementToBeAtLeast(int $count) : void`
- `expectPreparedStatementToBeAtMost(int $count) : void`
- `expectPreparedStatementToBeOnce() : void`
- `expectPreparedStatementToBeNever() : void`
- `expectPreparedStatementToBeAtLeastOnce() : void`
- `expectPreparedStatementToBeAtMostOnce() : void`

where `` is either `Allocated` or `Deallocated`.

*Example:*

```
public function testCloseDeallocatesPreparedStatement() : void
{
    $stmt = $this->client->prepare('SELECT ?');

    $this->expectPreparedStatementToBeDeallocatedOnce();
    $stmt->close();
}
```

To enable all the above expectation methods in one go, use the `Tarantool\PhpUnit\Expectation\Expectations` trait, or extend the `Tarantool\PhpUnit\TestCase` class.

Mocking
-------

[](#mocking)

The library provides several helper classes to create test doubles for the [Tarantool Сlient](https://github.com/tarantool-php/client)to avoid sending real requests to the Tarantool server. For the convenience of creating such objects, add the trait `TestDoubleClient` to your test class:

```
use PHPUnit\Framework\TestCase;
use Tarantool\PhpUnit\Client\TestDoubleClient;

final class MyTest extends TestCase
{
    use TestDoubleClient;

    // ...
}
```

> *If your test cases extend the `Tarantool\PhpUnit\TestCase` class, this step is not needed because the trait is already included in that class.*

A dummy client object can be created as follows:

```
public function testFoo() : void
{
    $dummyClient = $this->createDummyClient();

    // ...
}
```

To simulate specific scenarios, such as establishing a connection to a server or returning specific responses in a specific order from the server, use the facilities of the `TestDoubleClientBuilder` class. For example, to simulate the `PING` request:

```
use Tarantool\Client\Request\PingRequest;
use Tarantool\PhpUnit\TestCase;

final class MyTest extends TestCase
{
    public function testFoo() : void
    {
        $mockClient = $this->getTestDoubleClientBuilder()
            ->shouldSend(new PingRequest())
            ->build();

        // ...
    }

    // ...
}
```

Another example, sending two `EVALUATE` requests and returning a different response for each:

```
use Tarantool\Client\RequestTypes;
use Tarantool\PhpUnit\Client\TestDoubleFactory;
use Tarantool\PhpUnit\TestCase;

final class MyTest extends TestCase
{
    public function testFoo() : void
    {
        $mockClient = $this->getTestDoubleClientBuilder()
            ->shouldSend(
                RequestTypes::EVALUATE,
                RequestTypes::EVALUATE
            )->willReceive(
                TestDoubleFactory::createResponseFromData([2]),
                TestDoubleFactory::createResponseFromData([3])
            )->build();

        // ...
    }

    // ...
}
```

The above example can be simplified to:

```
$mockClient = $this->getTestDoubleClientBuilder()
    ->shouldHandle(
        RequestTypes::EVALUATE,
        TestDoubleFactory::createResponseFromData([2]),
        TestDoubleFactory::createResponseFromData([3])
    )->build();
```

Besides, the builder allows setting custom `Connection` and `Packer` instances:

```
$stubClient = $this->getMockClientBuilder()
    ->willUseConnection($myConnection)
    ->willUsePacker($myPacker)
    ->build();
```

Testing
-------

[](#testing)

Before running tests, the development dependencies must be installed:

```
composer install
```

Then, to run all the tests:

```
vendor/bin/phpunit
vendor/bin/phpunit -c phpunit-extension.xml
```

License
-------

[](#license)

The library is released under the MIT License. See the bundled [LICENSE](LICENSE) file for details.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance62

Regular maintenance activity

Popularity33

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~74 days

Recently: every ~90 days

Total

13

Last Release

1351d ago

PHP version history (3 changes)v0.1.0PHP ^7.1

v0.1.3PHP ^7.1|^8

v0.2.0PHP ^7.2.5|^8

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/533861?v=4)[Eugene Leonovich](/maintainers/rybakit)[@rybakit](https://github.com/rybakit)

---

Top Contributors

[![rybakit](https://avatars.githubusercontent.com/u/533861?v=4)](https://github.com/rybakit "rybakit (55 commits)")

---

Tags

phpunitphpunit-assertionsphpunit-extensionphpunit-extrasphpunit-utiltarantoolphpunitmockingannotationsassertionsextensionsexpectationstarantool

###  Code Quality

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tarantool-phpunit-extras/health.svg)

```
[![Health](https://phpackages.com/badges/tarantool-phpunit-extras/health.svg)](https://phpackages.com/packages/tarantool-phpunit-extras)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)[kimai/kimai

Kimai - Time Tracking

4.8k9.0k1](/packages/kimai-kimai)[rybakit/phpunit-extras

Custom annotations and expectations for PHPUnit.

4780.7k1](/packages/rybakit-phpunit-extras)[dg/bypass-finals

Removes final keyword from source code on-the-fly and allows mocking of final methods and classes

57129.2M612](/packages/dg-bypass-finals)[nette/tester

Nette Tester: enjoyable unit testing in PHP with code coverage reporter. 🍏🍏🍎🍏

4957.6M1.7k](/packages/nette-tester)[oro/platform

Business Application Platform (BAP)

645143.5k115](/packages/oro-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)