Testing Guide

Overview

The test suite is split into two levels:

Unit tests use stub implementations of core interfaces (NullCore, NullBatch, NullBulkItemsReader) and never make HTTP calls. Integration tests connect to a real Bitrix24 portal via an incoming webhook.

Requirements

• Docker and Docker Compose
• A Bitrix24 portal with an incoming webhook that has the required scopes enabled
• tests/.env.local file (see below)

Environment setup

The Makefile loads tests/.env (committed defaults) and then merges tests/.env.local (local overrides, git-ignored).

Create tests/.env.local:

BITRIX24_WEBHOOK=https://your-portal.bitrix24.com/rest/1/your-webhook-token/

Optional fields (defaults are set in tests/.env):

INTEGRATION_TEST_LOG_LEVEL=100   # Monolog level (100 = DEBUG)
LOGS_FILE=sdk.log
INTEGRATION_TEST_OPEN_LINE_CODE= # required for IMOpenLines integration tests

Running tests

Unit tests

make test-unit

Runs the unit_tests PHPUnit suite inside Docker. No portal required.

Integration tests (by scope)

Each integration suite maps to a specific Bitrix24 API scope. Run the one you need:

make test-integration-scope-crm
make test-integration-scope-lists
make test-integration-calendar-event
make test-integration-calendar-resource
make test-integration-im-open-lines-config
make test-integration-im-open-lines-crm-chat
make test-integration-im-open-lines-session
make test-integration-im-open-lines-operator
make test-integration-landing-page
make test-integration-landing-syspage
make test-integration-landing-repo
make test-integration-landing-demos
make test-integration-landing-role
make test-integration-sale-basket-property
make test-integration-sale-cashbox-handler
make test-integration-sale-cashbox
make test-integration-sale-delivery
make test-integration-sale-delivery-extra-service
make test-integration-sale-payment-item-basket
make test-integration-sale-payment-item-shipment
make test-integration-sale-property-relation
make test-integration-legacy-task
make test-integration-main-eventlog

Run a single test class

docker-compose run --rm php-cli vendor/bin/phpunit tests/Integration/Services/CRM/Deal/Service/DealTest.php

Run a single test method

docker-compose run --rm php-cli vendor/bin/phpunit tests/Integration/Services/CRM/Deal/Service/DealTest.php --filter testAdd

Result-item annotation tests

If a service returns an entity from get and/or list, add a separate integration test file dedicated to result-item phpdoc annotation validation.

These tests must validate both:

• completeness: all system fields returned by fields()->getFieldsDescription() are present in the result-item annotations
• type mapping: annotated field types match the Bitrix24 field types through the shared custom assertions in tests/CustomAssertions/CustomBitrix24Assertions.php

Use one dedicated annotation test file per result-item class. Keep it separate from CRUD and use-case tests so annotation regressions stay isolated and easy to spot.

Recommended naming convention:

• file/class suffix: AnnotationsTest
• examples: TaskItemResultAnnotationsTest.php, DealItemResultAnnotationsTest.php
• test method names: testAllSystemFieldsAnnotated, testAllSystemFieldsHasValidTypeAnnotation

When the remote API returns field codes in a naming style different from the SDK result-item properties, normalize the field keys in the test before calling the shared assertions.

Code quality

Run all linters in sequence:

make lint-all

Individual linters:

Architectural layer enforcement (Deptrac)

Deptrac statically analyses PHP use imports and enforces that classes only depend on layers they are allowed to.

Layer rules

Configuration

Rules live in deptrac.yaml at the project root. The skip_violations section records pre-existing violations that have not been fixed yet. Each entry carries a TODO comment describing the required refactoring.

Rule: never add a new entry to skip_violations to silence a freshly introduced violation — fix the import instead.

Running

make lint-deptrac          # check only

Deptrac is also included in make lint-all, so it runs as part of the full quality gate.

Reading the output

Adding a new skip_violation

Only allowed for violations that existed before your change. Add an entry to deptrac.yaml → skip_violations with a TODO comment:

skip_violations:
  Bitrix24\SDK\Core\MyClass:
    # TODO: move FooInterface to Core so Core does not depend on Infrastructure
    - Bitrix24\SDK\Infrastructure\FooInterface

Full make targets reference

Docker

Composer

Lint

Tests — unit

Tests — integration (CRM)

Tests — integration (Lists)

Tests — integration (IMOpenLines)

Tests — integration (Calendar)

Tests — integration (Landing)

Tests — integration (Sale)

Tests — integration (Tasks)

Tests — integration (Main)

Test structure

tests/
├── Unit/
│   ├── Application/        # Application layer unit tests
│   ├── Core/               # Core (HTTP client, batch, credentials) unit tests
│   ├── Filters/            # Filter unit tests
│   ├── Infrastructure/     # Infrastructure unit tests
│   ├── OpenApi/            # OpenAPI unit tests
│   ├── Services/           # Service unit tests (mirrors src/Services/)
│   └── Stubs/              # Null/stub implementations (see below)
├── Integration/
│   ├── Core/               # Core integration tests
│   ├── Legacy/             # Legacy API v1 integration tests
│   └── Services/           # Service integration tests (mirrors src/Services/)
├── CustomAssertions/       # Shared assertion traits
├── Builders/               # Test builder helpers
├── Application/            # Application-level test helpers
├── ApplicationBridge/      # Webhook bridge for app-mode tests
├── bootstrap.php           # PHPUnit bootstrap (loads .env files)
├── .env                    # Default environment variables (committed)
└── .env.local              # Local overrides with your webhook (git-ignored)

Patterns

Unit test pattern

#[CoversClass(MyService::class)]
class MyServiceTest extends TestCase
{
    private MyService $service;

    #[\Override]
    protected function setUp(): void
    {
        $this->service = new MyService(
            new NullCore(),   // no HTTP calls
            new NullBatch(),
            new NullLogger()
        );
    }

    #[Test]
    #[DataProvider('myDataProvider')]
    public function testSomeBehavior(string $input, string $expected): void
    {
        $this->assertEquals($expected, $this->service->process($input));
    }

    public static function myDataProvider(): Generator
    {
        yield 'case description' => ['input', 'expected'];
    }
}

Key conventions:

• Use #[CoversClass] so coverage reports are accurate
• Use #[DataProvider] for table-driven tests
• Prefer createMock() (strict MockObject) when you need to assert calls; use createStub() when you only need return values

Integration test pattern

class MyServiceTest extends TestCase
{
    use CustomBitrix24Assertions;

    private MyService $service;

    #[\Override]
    public function setUp(): void
    {
        $this->service = Factory::getServiceBuilder()->getMyService();
    }

    #[\Override]
    public function tearDown(): void
    {
        // clean up entities created during the test
    }

    public function testAdd(): void
    {
        $result = $this->service->add(['TITLE' => 'Test']);
        $this->assertGreaterThan(0, $result->getId());
    }
}

Key conventions:

• Call Factory::getServiceBuilder() (or Factory::getCore()) in setUp()
• Clean up created records in tearDown() to keep the portal tidy
• Use CustomBitrix24Assertions for domain-specific assertions

Contract tests

Abstract base classes enforce interface contracts across implementations:

abstract class AbstractRepositoryInterfaceTest extends TestCase
{
    abstract protected function getRepository(): MyRepositoryInterface;

    public function testFind(): void { /* shared contract assertion */ }
}

class ConcreteRepositoryTest extends AbstractRepositoryInterfaceTest
{
    protected function getRepository(): MyRepositoryInterface
    {
        return Factory::getServiceBuilder()->getConcreteRepository();
    }
}

Stubs

Located in tests/Unit/Stubs/, these implement core interfaces without making any HTTP calls:

Custom assertions

tests/CustomAssertions/CustomBitrix24Assertions.php is a trait providing domain-specific assertions:

• assertBitrix24AllResultItemFieldsAnnotated(array $fieldCodesFromApi, string $resultItemClassName) — verifies that every field returned by the API is documented in the result item's PHPDoc [@property](https://github.com/property) annotations. Use this in integration tests after fetching a real entity to catch undocumented fields.

Troubleshooting

PHPUnit can't write to var/ or log files

The container runs as www-data. Fix permissions with:

docker-compose run --rm php-cli chown -R www-data:www-data /var/www/html/var/

PHPStan cache errors after a rebase or major refactor

Clear the cache manually:

docker-compose run --rm php-cli vendor/bin/phpstan clear-result-cache

Integration tests fail with 401 / "Wrong webhook"

Your webhook has expired or was revoked. Generate a new incoming webhook in Bitrix24 (Settings → Developer resources → Incoming webhook) and update tests/.env.local.

Integration tests fail with "scope not available"

The webhook user does not have the required scope enabled. Edit the webhook in Bitrix24 and enable the missing scope (e.g., crm, lists, imopenlines).

lint-deptrac reports new violations after adding a class

A new class depends on a layer it is not allowed to use. Fix the import — do not add it to skip_violations. Check deptrac.yaml → ruleset for what each layer is allowed to import.

lint-deptrac fails with vendor/bin/deptrac: not found

Deptrac is not installed. Run:

make composer-install