Test Architecture and Organization

This document details the test infrastructure architecture for the PHP Bolt Protocol Client library, including the test class hierarchy, mock connection patterns, validation approaches, and organizational principles. For information about specific test suites and CI/CD pipelines, see CI/CD Pipeline and Cross-Version Testing. For integration testing details, see Integration Testing.

Purpose and Scope

The testing architecture provides a layered foundation for validating protocol implementations, message serialization, state transitions, and cross-version compatibility. The design emphasizes:

• Code reuse through abstract base classes and trait patterns
• Mock-based unit testing for protocol validation without database dependencies
• State machine validation ensuring correct ServerState transitions
• Binary serialization verification validating PackStream encoding/decoding
• Protocol version compatibility testing across Bolt versions 1 through 6

Test Class Hierarchy

The test infrastructure uses a three-layer inheritance model that progressively adds capabilities from generic test utilities to protocol-specific validation methods.

Sources: tests/TestLayer.php1-111 tests/protocol/V1Test.php1-213 tests/protocol/V3Test.php1-219

TestLayer Base Class

The TestLayer abstract class tests/TestLayer.php12-110 provides foundational utilities used across all test types. It extends PHPUnit's TestCase and establishes two primary capabilities:

Environment Configuration

The setUpBeforeClass() method tests/TestLayer.php14-29 reads environment variables and populates global configuration:

Environment Variable	Global Variable	Purpose
GDB_USERNAME	$GLOBALS['NEO_USER']	Database username
GDB_PASSWORD	$GLOBALS['NEO_PASS']	Database password
GDB_HOST	$GLOBALS['NEO_HOST']	Database host
GDB_PORT	$GLOBALS['NEO_PORT']	Database port

This allows CI/CD pipelines to configure test connections via environment variables without modifying test code.

Unified Authentication: sayHello()

The sayHello() method tests/TestLayer.php37-60 abstracts protocol-specific authentication patterns:

This pattern enables test code to authenticate against any protocol version without conditional logic at the call site.

Protocol Version Detection: getCompatibleBoltVersion()

The getCompatibleBoltVersion() method tests/TestLayer.php69-109 queries Neo4j's HTTP discovery API to determine the appropriate Bolt protocol version:

Neo4j Version	Bolt Version
≥ 2025.10	6
≥ 5.26	5.8
≥ 5.23	5.6
≥ 5.13	5.4
≥ 5.9	5.3
≥ 5.7	5.2
≥ 5.5	5.1
≥ 5.0	5
≥ 4.4	4.4
≥ 4.3	4.3

This method enables integration tests to dynamically select compatible protocol versions based on the running database instance.

Sources: tests/TestLayer.php1-111

ProtocolLayer and Mock Connection Pattern

The ProtocolLayer abstract class extends TestLayer and provides the core infrastructure for protocol unit testing through mock connections. While the class file is not shown in the provided sources, its usage is evident throughout protocol test files.

Mock Connection Architecture

Protocol tests use a mock connection that operates on static buffers rather than real network I/O:

Read Array Format

The self::$readArray static property tests/protocol/V1Test.php29-32 defines server responses as signature-content pairs:

Each array element is a tuple where:

• First element: Response signature byte (e.g., 0x70 = SUCCESS, 0x7F = FAILURE)
• Second element: Response content as object or array

Write Buffer Format

The self::$writeBuffer static property tests/protocol/V1Test.php33-44 contains expected hexadecimal representations of serialized messages:

Each hex string represents PackStream-encoded data chunks. Tests validate that protocol implementations generate exactly these byte sequences when sending messages.

Sources: tests/protocol/V1Test.php17-60

Test Organization and Naming Conventions

Protocol test classes follow consistent naming and organizational patterns:

File Structure

tests/
├── protocol/
│ ├── ProtocolLayer.php # Base for protocol tests
│ ├── V1Test.php # Bolt v1 tests
│ ├── V2Test.php # Bolt v2 tests
│ ├── V3Test.php # Bolt v3 tests
│ ├── V4Test.php # Bolt v4 tests
│ ├── V4_1Test.php # Bolt v4.1 tests
│ ├── V4_2Test.php # Bolt v4.2 tests
│ ├── V4_3Test.php # Bolt v4.3 tests
│ ├── V4_4Test.php # Bolt v4.4 tests
│ ├── V5_1Test.php # Bolt v5.1 tests
│ ├── V5_2Test.php # Bolt v5.2 tests
│ ├── V5_3Test.php # Bolt v5.3 tests
│ └── V6Test.php # Bolt v6 tests
├── structures/
│ ├── StructureLayer.php # Base for structure tests
│ ├── v1/ # v1 structure tests
│ ├── v4_3/ # v4.3 structure tests
│ ├── v5/ # v5 structure tests
│ └── v6/ # v6 structure tests
└── TestLayer.php # Base for all tests

Test Method Naming

Each protocol test class follows a standard method structure:

Method Pattern	Purpose	Example
test__construct()	Instantiate protocol	Returns protocol instance
testInit() / testHello()	Authentication	Tests connection setup
testRun()	Query execution	Tests RUN message
testPullAll() / testPull()	Result fetching	Tests streaming
testDiscardAll() / testDiscard()	Result discarding	Tests discard
testBegin()	Transaction start	Tests BEGIN
testCommit()	Transaction commit	Tests COMMIT
testRollback()	Transaction rollback	Tests ROLLBACK
testReset()	Connection reset	Tests RESET
testAckFailure()	Error acknowledgment	Tests ACK_FAILURE (v1)
testGoodbye()	Connection close	Tests GOODBYE (v3+)
testRoute()	Cluster routing	Tests ROUTE (v4.3+)
testLogon() / testLogoff()	Split auth	Tests LOGON/LOGOFF (v5+)

Sources: tests/protocol/V1Test.php17-212 tests/protocol/V3Test.php17-218

The @depends Annotation Pattern

Protocol tests use PHPUnit's @depends annotation to establish test execution order and share protocol instances across test methods. This pattern reduces test execution time by avoiding redundant protocol instantiation.

Dependency Chain

Implementation Example

The constructor test tests/protocol/V1Test.php17-22 creates and returns the protocol instance:

Subsequent tests declare the dependency tests/protocol/V1Test.php24-27:

This pattern ensures:

1. Protocol is instantiated once per test class
2. Tests can be executed in any order (no implicit dependencies)
3. Each test receives a fresh protocol instance in a known state
4. Reduced test suite execution time

Sources: tests/protocol/V1Test.php17-27 tests/protocol/V3Test.php17-27

Test Validation Patterns

Protocol tests validate three primary aspects: message serialization, response handling, and state transitions.

Message Serialization Validation

Tests verify that protocol methods generate correct binary output by checking against self::$writeBuffer tests/protocol/V1Test.php33-50:

The hexadecimal strings represent PackStream-encoded chunks that would be written to the socket. This validates that the Packer correctly serializes method parameters.

Response Handling Validation

Tests configure self::$readArray with various response scenarios and validate protocol behavior tests/protocol/V1Test.php52-60:

SUCCESS Response

FAILURE Response

IGNORED Response

State Transition Validation

Tests validate that ServerState transitions occur correctly based on message types and responses tests/protocol/V1Test.php88-101:

Initial State	Message	Response	Final State
CONNECTED	init()	SUCCESS	READY
CONNECTED	init()	FAILURE	DEFUNCT
READY	run()	SUCCESS	STREAMING
READY	run()	FAILURE	FAILED
INTERRUPTED	run()	IGNORED	INTERRUPTED
STREAMING	pullAll()	SUCCESS	READY
STREAMING	discardAll()	SUCCESS	READY
FAILED	ackFailure()	SUCCESS	READY
FAILED	reset()	SUCCESS	READY

The checkFailure() Helper

The checkFailure() method (defined in ProtocolLayer, implementation not shown) validates FAILURE response structure:

Sources: tests/protocol/V1Test.php27-101 tests/protocol/V3Test.php27-110

Multi-Scenario Testing Pattern

Most protocol test methods validate three scenarios: success, failure, and interrupted states. This pattern ensures robust error handling.

Standard Test Structure

Example: testRun()

The testRun() method tests/protocol/V1Test.php65-102 demonstrates this pattern:

This ensures each message type is validated against all possible server response scenarios.

Sources: tests/protocol/V1Test.php65-102 tests/protocol/V3Test.php70-110

Protocol Version Coverage

The test suite provides comprehensive coverage across all Bolt protocol versions:

Test Class	Protocol Version	Key Features Tested
V1Test	1.0	INIT, RUN, PULL_ALL, DISCARD_ALL, RESET, ACK_FAILURE
V2Test	2.0	Same as V1 (V2 is identical to V1)
V3Test	3.0	HELLO, BEGIN, COMMIT, ROLLBACK, GOODBYE
V4Test	4.0	PULL, DISCARD (with parameters)
V4_1Test	4.1	Enhanced HELLO
V4_2Test	4.2	No new messages (bug fixes only)
V4_3Test	4.3	ROUTE (basic routing)
V4_4Test	4.4	ROUTE (enhanced with db parameter)
V5_1Test	5.1	Split authentication (HELLO + LOGON)
V5_2Test	5.2	LOGOFF
V5_3Test	5.3	Additional features
V6Test	6.0	Vector structures, TELEMETRY

Minimal Test Classes

Some protocol versions have minimal test classes tests/protocol/V2Test.php15-24 that only test construction:

This indicates that:

1. The protocol version has no unique messages beyond its parent
2. Implementation is verified through inheritance
3. Constructor test ensures proper instantiation and dependency injection

Sources: tests/protocol/V2Test.php1-24 tests/protocol/V4_2Test.php1-24 tests/protocol/V6Test.php1-23

Integration with Unpacker

Protocol tests indirectly validate the Unpacker class by consuming unpacked responses. The mock connection's read() method uses a real Unpacker instance to convert binary data from self::$readArray into PHP values.

The Unpacker src/packstream/v1/Unpacker.php32-42 converts binary PackStream format to PHP structures:

• Signature extraction via getSignature() src/packstream/v1/Unpacker.php47-50
• Structure instantiation using signature lookup tables src/packstream/v1/Unpacker.php123-156
• Recursive unpacking for nested structures src/packstream/v1/Unpacker.php68-116

This integration validates both protocol message handling and serialization correctness.

Sources: src/packstream/v1/Unpacker.php1-294 tests/protocol/V1Test.php29-32