Testing

This document provides an overview of the testing philosophy, test organization, and coverage strategy employed by the php-bolt-driver library. The testing infrastructure ensures compatibility across multiple database systems (Neo4j, Memgraph, NornicDB) and protocol versions (Bolt 1-6) using a comprehensive matrix testing approach.

For detailed information about specific testing layers, see:

• Test architecture and organization: Test Architecture and Organization
• Unit and protocol testing: Unit and Protocol Testing
• Integration testing: Integration Testing
• CI/CD pipeline details: CI/CD Pipeline and Cross-Version Testing

Testing Philosophy

The php-bolt-driver library employs a multi-dimensional testing strategy that validates functionality across:

• Multiple database systems: Neo4j (versions 4.4 through 2025), Memgraph, and NornicDB
• Multiple PHP versions: PHP 8.2, 8.3, 8.4, and 8.5
• Multiple protocol versions: Bolt 1 through Bolt 6
• Multiple connection types: Socket, StreamSocket, and PStreamSocket with SSL/TLS variants

The testing approach separates concerns into unit tests (no database required) and integration tests (requiring live database connections), enabling rapid feedback during development while ensuring comprehensive end-to-end validation.

Sources: README.md35-43 phpunit.xml1-27

Test Suite Organization

Test Suite Composition Table

Suite Name	Purpose	Database Required	Test Files Included
Neo4j	Full integration testing with Neo4j	Yes (Neo4j)	BoltTest.php, PerformanceTest.php, connection/, error/, packstream/, structures/
NoDatabase	Unit tests for core logic	No	protocol/, helpers/FileCacheTest.php
Memgraph	Memgraph-specific compatibility tests	Yes (Memgraph)	MemgraphTest.php
NornicDB	NornicDB-specific compatibility tests	Yes (NornicDB)	NornicDBTest.php

Sources: phpunit.xml3-22

Test Execution Flow

Sources: tests/BoltTest.php19-204 tests/TestLayer.php

Coverage Matrix

The library tests against an extensive matrix of database and PHP version combinations to ensure broad compatibility:

Neo4j Version Coverage

Neo4j Version	PHP Versions Tested	Workflow File	Jobs per Run
4.4	8.2, 8.3, 8.4, 8.5	neo4j.4.4.yml	4
5.4, 5.6, 5.8, 5.12, 5.22, 5.25, 5.26	8.2, 8.3, 8.4, 8.5	neo4j.5.yml	28 (7 versions × 4 PHP)
2025.09, 2025	8.2, 8.3, 8.4, 8.5	neo4j.2025.yml	8 (2 versions × 4 PHP)

Total Neo4j test jobs per CI run: 40 combinations

Alternative Database Coverage

Database	Version	PHP Versions	Workflow File
Memgraph	Latest	8.5	memgraph.yml
NornicDB	Latest	8.5	nornicdb.yml

Unit Test Coverage (No Database)

PHP Versions	Workflow File	Purpose
8.2, 8.3, 8.4, 8.5	no-db.yml	Protocol logic, PackStream serialization, cache operations

Sources: .github/workflows/neo4j.4.4.yml1-51 .github/workflows/neo4j.5.yml1-51 .github/workflows/neo4j.2025.yml1-51 .github/workflows/memgraph.yml1-37 .github/workflows/nornicdb.yml1-40 .github/workflows/no-db.yml1-35

Test Categories

Sources: phpunit.xml3-22

Key Test Files and Their Roles

Core Integration Tests

tests/BoltTest.php

Primary integration test file covering:

• Connection establishment with different socket types (tests/BoltTest.php19-37)
• SSL/TLS configuration with Aura cloud instance (tests/BoltTest.php39-57)
• Authentication flow via sayHello helper (tests/BoltTest.php59-73)
• Query execution with run() and pull() (tests/BoltTest.php78-90)
• Result discarding with discard() (tests/BoltTest.php95-105)
• Transaction management: begin, commit, rollback (tests/BoltTest.php111-143)
• Routing message support for cluster topology (tests/BoltTest.php148-160)
• Connection reset functionality (tests/BoltTest.php165-171)
• Large message chunking (>65KB) (tests/BoltTest.php178-203)

tests/PerformanceTest.php

Validates memory-efficient handling of large datasets using generator patterns for 50,000+ record result sets.

Sources: tests/BoltTest.php1-204 README.md164-165

Database-Specific Tests

tests/MemgraphTest.php

Memgraph compatibility suite testing:

• Connection with scheme 'none' authentication (tests/MemgraphTest.php36-50)
• Basic data type round-trip (null, bool, int, float, string, list, dictionary) (tests/MemgraphTest.php58-83)
• Transaction rollback verification (tests/MemgraphTest.php89-121)
• Temporal structures: Duration, Date, LocalTime, LocalDateTime (tests/MemgraphTest.php130-152)

tests/NornicDBTest.php

NornicDB compatibility suite testing:

• Bolt 4.4.4 protocol version (tests/NornicDBTest.php33)
• No-authentication scheme (tests/NornicDBTest.php36)
• Query parameter handling (tests/NornicDBTest.php48-71)
• Transaction semantics (tests/NornicDBTest.php77-108)
• Graph structures: Node, Relationship, Path (tests/NornicDBTest.php115-160)

Sources: tests/MemgraphTest.php1-153 tests/NornicDBTest.php1-177

Test Environment Configuration

Tests rely on global variables defined in phpunit.xml and optionally overridden via environment variables:

Variable	Default (phpunit.xml)	CI Override	Purpose
NEO_USER	neo4j	GDB_USERNAME env var	Database username
NEO_PASS	nothing123	GDB_PASSWORD env var	Database password
NEO_HOST	Set by test context	Service hostname	Database host address
NEO_PORT	Set by test context	Service port (7687)	Database Bolt port

Sources: phpunit.xml23-26 .github/workflows/neo4j.5.yml47-50

CI Trigger Conditions

All GitHub Actions workflows execute when:

• Pull requests are opened, synchronized, or reopened
• Pull requests transition to ready-for-review state
• Target branch is master
• Pull request is not in draft mode

Draft pull requests are automatically skipped to conserve CI resources:

Sources: .github/workflows/neo4j.5.yml3-6 .github/workflows/neo4j.5.yml10

Test Execution Commands

The library provides multiple test execution modes depending on development needs:

Run all Neo4j integration tests:

Run unit tests without database:

Run database-specific compatibility tests:

Run specific test class:

Sources: .github/workflows/neo4j.5.yml46-50 .github/workflows/no-db.yml33-34

Testing Supported Ecosystems

The library validates compatibility with multiple graph database systems implementing the Bolt protocol:

Database	Bolt Compatibility Documentation	Test Coverage
Neo4j	bolt-compatibility	Versions 4.4-2025
Memgraph	bolt-compatibility	Latest version
Amazon Neptune	bolt-compatibility	Not actively tested
NornicDB	Community contribution	Latest version
DozerDB	Community support	Not actively tested
ONgDB	Community support	Not actively tested
LadybugDB	Via bolt4rs wrapper	Not actively tested

Systems marked "Not actively tested" are supported by the protocol implementation but lack dedicated CI jobs. Neo4j, Memgraph, and NornicDB receive continuous validation.

Sources: README.md35-43