Integration Testing

Purpose and Scope

Integration testing validates the php-bolt-driver library's behavior against live graph database instances. These tests verify end-to-end functionality including connection management, protocol message exchange, data serialization/deserialization, and structure handling across multiple database versions and implementations.

This page covers integration test organization, structure tests for graph/temporal/spatial types, connection timeout handling, performance validation with large datasets, and database-specific test suites. For test architecture and the TestLayer hierarchy, see Test Architecture and Organization. For protocol message validation without database dependencies, see Unit and Protocol Testing. For CI/CD matrix testing strategy, see CI/CD Pipeline and Cross-Version Testing.

---

Integration Test Suite Organization

The integration test suite is organized in phpunit.xml3-22 with multiple test suites targeting different capabilities:

Test Suite	Purpose	Key Tests
Neo4j	Full integration testing against Neo4j	Structure tests, connection tests, performance tests
NoDatabase	Protocol-level tests without database	Protocol message handlers, cache tests
Memgraph	Memgraph-specific compatibility	Basic structure validation
NornicDB	NornicDB-specific compatibility	Graph structures, transactions

Sources: phpunit.xml3-22

---

Structure Integration Tests

Structure tests validate bidirectional serialization of graph, temporal, and spatial types across protocol versions. These tests execute Cypher queries to create structures in the database and verify the unpacked PHP objects match expected properties.

Graph Structure Testing

Graph structure tests create nodes, relationships, and paths in transactions (rolled back to avoid pollution) and verify structure properties:

Node Structure Test:

tests/structures/v1/StructuresTest.php236-257 demonstrates node testing:

Key validations:

• Instance type: Node, Relationship, UnboundRelationship, Path
• Property id matches ID() function result
• Property element_id matches elementId() for v5+ (see tests/structures/v5/StructuresTest.php68-70)
• Labels, properties, and relationship type correctness
• Node reference consistency in relationships

Version-specific differences:

Protocol Version	Structure Namespace	Key Differences
V1-V4.4	\Bolt\protocol\v1\structures	Only id field
V5+	\Bolt\protocol\v5\structures	Both id and element_id fields

Sources: tests/structures/v1/StructuresTest.php236-371 tests/structures/v5/StructuresTest.php55-139

Temporal and Spatial Structure Testing

Temporal structures (Date, DateTime, Duration, LocalDateTime, LocalTime, Time) and spatial structures (Point2D, Point3D) support bidirectional packing. Tests verify round-trip serialization:

Example from tests/structures/v1/StructuresTest.php76-106:

Temporal structures tested:

• Date: tests/structures/v1/StructuresTest.php76-106
• Duration: tests/structures/v1/StructuresTest.php112-139
• LocalDateTime: tests/structures/v1/StructuresTest.php159-192
• LocalTime: tests/structures/v1/StructuresTest.php198-231
• Time: tests/structures/v1/StructuresTest.php377-412

Spatial structures tested:

• Point2D: tests/structures/v1/StructuresTest.php292-315
• Point3D: tests/structures/v1/StructuresTest.php320-343

Sources: tests/structures/v1/StructuresTest.php76-412 tests/structures/v5/StructuresTest.php1-141 tests/structures/v4_3/StructuresTest.php1-67

Bytes Structure Testing

The Bytes structure enables binary data storage. Testing validates round-trip serialization through database storage:

tests/structures/v1/StructuresTest.php417-437 creates a node with binary data, retrieves it, and verifies equality:

Sources: tests/structures/v1/StructuresTest.php417-437 tests/packstream/v1/BytesTest.php1-59

---

Connection Integration Tests

Connection tests validate timeout behavior, error recovery, and connection type implementations against live databases.

Connection Type Testing

tests/BoltTest.php19-37 validates the Socket connection implementation:

Tested connection implementations:

• Socket: Requires sockets extension
• StreamSocket: Standard PHP streams, supports SSL
• PStreamSocket: Persistent connections with cache

Sources: tests/BoltTest.php19-37 tests/BoltTest.php59-73

Timeout Behavior and Recovery

tests/connection/ConnectionTest.php1-126 validates timeout handling with multiple scenarios:

Test scenarios:

Test Method	Timeout	Query Duration	Expected Outcome
testMillisecondTimeout	1.5 seconds	~10+ seconds	ConnectionTimeoutException
testSecondsTimeout	1 second	~10+ seconds	ConnectionTimeoutException
testLongNoTimeout	200 seconds	150 seconds	Success (no timeout)
testTimeoutRecoverAndReset	1.5 seconds	~10+ seconds	Timeout, reset fails, reconnect succeeds

Key implementation from tests/connection/ConnectionTest.php78-119:

Sources: tests/connection/ConnectionTest.php1-126

---

Performance Testing with Large Datasets

Performance tests validate memory efficiency and throughput when handling large result sets using the generator-based packing interfaces.

50,000 Record Test Architecture

tests/PerformanceTest.php19-63 tests streaming 50,000 records using IPackListGenerator:

Implementation pattern:

Key characteristics:

• Uses RandomDataGenerator implementing IPackListGenerator
• 120-second timeout for long-running operation
• Lock mechanism prevents concurrent execution
• Generator yields data incrementally (no 50K-item array in memory)
• Validates all records received

Sources: tests/PerformanceTest.php1-64 tests/packstream/v1/generators/RandomDataGenerator.php

Generator-Based Packing Tests

tests/packstream/v1/PackerTest.php188-227 validates generator interfaces for both lists and dictionaries:

List generator test:

Dictionary generator test:

Generator interfaces:

• IPackListGenerator: Yields sequential values
• IPackDictionaryGenerator: Yields key-value pairs

Sources: tests/packstream/v1/PackerTest.php188-227 README.md161-165

---

Database-Specific Test Suites

Database-specific test suites validate compatibility with alternative Bolt implementations beyond Neo4j.

NornicDB Integration Tests

tests/NornicDBTest.php1-177 validates NornicDB compatibility with basic graph operations:

Key differences from Neo4j tests:

Feature	NornicDB Test	Neo4j Test
Authentication	scheme: 'none'	scheme: 'basic' with credentials
Protocol version	Fixed 4.4.4	Version negotiation
Structure validation	Basic properties only	Includes element_id for v5+

Test coverage:

1. Connection: tests/NornicDBTest.php22-40 - Socket connection, V4.4 handshake, scheme='none' authentication
2. Query execution: tests/NornicDBTest.php47-71 - Parameter passing, field mapping
3. Transactions: tests/NornicDBTest.php77-108 - begin/rollback, node creation verification
4. Relationship structures: tests/NornicDBTest.php115-130 - Relationship unpacking
5. Path structures: tests/NornicDBTest.php137-160 - Path with nodes, relationships, indices

Sources: tests/NornicDBTest.php1-177

Memgraph Test Suite

tests/MemgraphTest.php (referenced in phpunit.xml16-18) validates Memgraph-specific compatibility. The test suite follows a similar structure to NornicDB tests, verifying basic structure unpacking and query execution.

Sources: phpunit.xml16-18

---

Transaction and State Management Tests

Integration tests validate explicit transaction handling and server state transitions through message sequences.

Transaction Rollback Test

tests/BoltTest.php111-143 validates transaction rollback prevents data persistence:

Implementation:

Sources: tests/BoltTest.php111-143

Message Pipelining and Response Consumption

tests/BoltTest.php78-90 demonstrates pipelining and response ordering:

Response sequence pattern:

Order	Message Type	Content
1	SUCCESS (RUN)	{'fields': [...]}
2	RECORD	[value1, value2, ...]
3	SUCCESS (PULL)	{'has_more': false, ...}

Sources: tests/BoltTest.php78-105

---

Serialization Integration Tests

Serialization tests validate PackStream encoding/decoding with live database round-trips.

Comprehensive Type Testing

tests/packstream/v1/PackerTest.php and tests/packstream/v1/UnpackerTest.php test all PackStream types:

Tested types:

Type	Packer Test	Unpacker Test	Size Variants
null	tests/packstream/v1/PackerTest.php37-47	tests/packstream/v1/UnpackerTest.php39-51	-
boolean	tests/packstream/v1/PackerTest.php52-71	tests/packstream/v1/UnpackerTest.php56-70	-
integer	tests/packstream/v1/PackerTest.php76-95	tests/packstream/v1/UnpackerTest.php75-90	TINY, INT_8, INT_16, INT_32, INT_64
float	tests/packstream/v1/PackerTest.php100-113	tests/packstream/v1/UnpackerTest.php95-112	FLOAT_64
string	tests/packstream/v1/PackerTest.php118-138	tests/packstream/v1/UnpackerTest.php118-145	0, 10, 200, 60K, 200K chars
list	tests/packstream/v1/PackerTest.php143-156	tests/packstream/v1/UnpackerTest.php151-164	0, 10, 200, 60K, 200K items
dictionary	tests/packstream/v1/PackerTest.php170-183	tests/packstream/v1/UnpackerTest.php176-198	0, 10, 200, 20K, 70K pairs

String size testing pattern:

Sources: tests/packstream/v1/PackerTest.php1-229 tests/packstream/v1/UnpackerTest.php1-201

---

Test Execution Pattern

Integration tests follow a consistent execution pattern leveraging the TestLayer base class:

Standard test initialization:

Key patterns:

• testInit() returns AProtocol instance
• Dependent tests receive protocol as parameter
• @depends testInit annotation ensures proper execution order
• Transaction-based tests use begin() and rollback() to avoid pollution
• Environment variables from phpunit.xml23-26 provide credentials

Sources: tests/structures/v1/StructuresTest.php43-70 tests/BoltTest.php59-73 tests/TestLayer.php

---

Summary

Integration tests validate php-bolt-driver functionality against live databases through:

1. Structure tests - Bidirectional serialization of graph, temporal, spatial, and binary types
2. Connection tests - Timeout behavior, recovery, and connection type validation
3. Performance tests - Memory-efficient handling of 50,000+ records using generators
4. Database-specific tests - Compatibility validation for NornicDB and Memgraph
5. Transaction tests - Explicit transaction management and state transitions
6. Serialization tests - PackStream encoding/decoding with size variants

All integration tests require live database instances and use the TestLayer base class for consistent setup and authentication. Tests execute in the Neo4j, Memgraph, and NornicDB suites defined in phpunit.xml with matrix testing across multiple database versions via CI/CD workflows (see CI/CD Pipeline and Cross-Version Testing).