VOOZH about

URL: https://deepwiki.com/stefanak-michal/php-bolt-driver/8.2-unit-and-protocol-testing

⇱ Unit and Protocol Testing | stefanak-michal/php-bolt-driver | DeepWiki

Loading...
Loading...
Last indexed: 14 February 2026 (a283bd)
Menu

Unit and Protocol Testing

Purpose and Scope

This page documents the unit and protocol testing infrastructure for the PHP Bolt driver. These tests verify protocol message serialization, state management, and protocol-specific behavior without requiring a live database connection. The tests use mock connections to validate that each protocol version correctly implements the Bolt specification.

For full-stack integration tests with real database connections, see Integration Testing. For CI/CD infrastructure and cross-version matrix testing, see CI/CD Pipeline and Cross-Version Testing.

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

Test Architecture Overview

Protocol tests are organized in the tests/protocol/ directory, with one test class per protocol version. These tests inherit from ProtocolLayer, which provides mocking infrastructure to simulate connection I/O without actual network communication.



Sources: tests/protocol/V1Test.php15 tests/protocol/V3Test.php15 tests/protocol/V4Test.php15 tests/TestLayer.php12


Mock Connection Infrastructure


The ProtocolLayer base class provides a sophisticated mocking system that eliminates the need for actual network connections during protocol testing.


Mock Connection Mechanism




Key Components:
































ComponentPurposeUsage
mockConnection()Creates a mock IConnection implementationCalled in test setup to provide protocol with non-networked I/O
self::$readArrayArray of pre-configured responsesContains [signature, content] tuples that mock reads from database
self::$writeBufferArray capturing serialized messagesValidates that protocol correctly serializes messages to PackStream format
checkFailure()Helper method for FAILURE responsesVerifies error structure and signature


Sources: tests/protocol/V1Test.php29-44 tests/protocol/V3Test.php29-45


Protocol Message Test Patterns


Each protocol test follows a consistent pattern: set up mock responses, invoke a protocol method, verify the response signature, and check state transitions.


Standard Test Pattern




Example: V1 INIT Message Test


tests/protocol/V1Test.php27-60 demonstrates the standard pattern:


    

  1. 

    Setup Mock Responses - self::$readArray contains expected responses:
    

      

    • [0x70, (object)[]] - SUCCESS response
      • 

    • [0x7F, (object)['message' => ..., 'code' => ...]] - FAILURE response
      • 

    

    2. 

  2. 

    Setup Expected Writes - self::$writeBuffer contains hex-encoded expected serialization
    

    3. 

  3. 

    Set Initial State - $cls->serverState = ServerState::CONNECTED
    

    4. 

  4. 

    Invoke Method - $cls->init('bolt-php', $auth)
    

    5. 

  5. 

    Verify Response - assertEquals(Signature::SUCCESS, ...)
    

    6. 

  6. 

    Verify State Transition - assertEquals(ServerState::READY, $cls->serverState)
    

    7. 



Sources: tests/protocol/V1Test.php27-60


Protocol-Specific Test Coverage


Each protocol version test class validates version-specific messages and behaviors. The following table summarizes key test methods:

























































ProtocolTest ClassKey Methods Tested
V1V1Testinit(), run(), pullAll(), discardAll(), reset(), ackFailure()
V2V2TestInherits V1 behavior, no additional methods
V3V3Testhello(), run(), begin(), commit(), rollback(), goodbye()
V4V4Testpull(), discard() (with streaming parameters)
V4.1V4_1Testhello() (with additional metadata)
V4.2V4_2TestConstructor only (no new messages)
V4.3V4_3Testroute() (cluster routing)
V4.4V4_4Testroute() (with database parameter)
V6V6TestConstructor validation


Sources: tests/protocol/V1Test.php17-211 tests/protocol/V3Test.php17-218 tests/protocol/V4Test.php17-96 tests/protocol/V4_3Test.php17-59


V1 Protocol Testing Example


The V1 protocol test demonstrates foundational message handling:




Key Test: testRun()


tests/protocol/V1Test.php65-102 validates three scenarios:


    

  1. 

    SUCCESS Scenario:
    

      

    • Initial state: ServerState::READY
      • 

    • Query: 'RETURN 1'
      • 

    • Expected response: Signature::SUCCESS
      • 

    • Expected state: ServerState::STREAMING
      • 

    

    2. 

  2. 

    FAILURE Scenario:
    

      

    • Initial state: ServerState::READY
      • 

    • Query: 'not a CQL'
      • 

    • Expected response: Signature::FAILURE
      • 

    • Expected state: ServerState::FAILED
      • 

    

    3. 

  3. 

    IGNORED Scenario:
    

      

    • Initial state: ServerState::INTERRUPTED
      • 

    • Query: 'not a CQL'
      • 

    • Expected response: Signature::IGNORED
      • 

    • Expected state: ServerState::INTERRUPTED (no change)
      • 

    

    4. 



Sources: tests/protocol/V1Test.php65-102


V3 Transaction Testing


The V3 protocol introduced explicit transaction management. tests/protocol/V3Test.php115-201 validates BEGIN, COMMIT, and ROLLBACK messages:




Transaction Test Pattern tests/protocol/V3Test.php115-141:


testBegin():
 - Set state: READY
 - Call: begin()
 - Verify: SUCCESS → TX_READY
 - Verify: FAILURE → FAILED
 - Verify: IGNORED → INTERRUPTED (no change)



Sources: tests/protocol/V3Test.php115-201


V4 Streaming Control Testing


V4 introduced parameterized streaming with pull(n, qid) and discard(n, qid). tests/protocol/V4Test.php27-95 tests these enhancements:


Pull Test Verification tests/protocol/V4Test.php27-60:


    

  • Tests pull(['n' => -1, 'qid' => -1]) (pull all remaining records)
    • 

  • Verifies iterator returns array of responses
    • 

  • Validates STREAMING → READY state transition
    • 

  • Confirms FAILURE and IGNORED handling
    • 



Write Buffer Verification tests/protocol/V4Test.php36-43:


The test validates exact PackStream serialization:


'00 01 b1' # Structure with 1 field
'00 01 3f' # Signature 0x3F (PULL)
'00 01 a2' # Dictionary with 2 entries
'00 02 81 6e' # Key "n"
'00 01 ff' # Value -1
'00 04 83 71 69 64' # Key "qid"
'00 01 ff' # Value -1



Sources: tests/protocol/V4Test.php27-95


V4.3 and V4.4 Routing Tests


Routing messages enable cluster-aware operations. tests/protocol/V4_3Test.php27-57 and tests/protocol/V4_4Test.php27-59 test the route() message:


V4.3 Route Message:




V4.4 Route Message (with database parameter):




Both validate:


    

  • SUCCESS response keeps state READY
    • 

  • FAILURE response transitions to FAILED
    • 

  • IGNORED response maintains INTERRUPTED state
    • 



Sources: tests/protocol/V4_3Test.php27-57 tests/protocol/V4_4Test.php27-59


State Transition Testing


Protocol tests extensively verify the ServerState state machine. Each test method checks state transitions for different response types:




State Transition Patterns:









































































Initial StateMessageResponseFinal State
CONNECTEDinit/helloSUCCESSREADY
CONNECTEDinit/helloFAILUREDEFUNCT
READYrunSUCCESSSTREAMING
READYrunFAILUREFAILED
READYbeginSUCCESSTX_READY
STREAMINGpullAllSUCCESSREADY
TX_READYcommitSUCCESSREADY
FAILEDresetSUCCESSREADY
FAILEDresetFAILUREDEFUNCT
INTERRUPTEDanyIGNOREDINTERRUPTED


Sources: tests/protocol/V1Test.php52-59 tests/protocol/V1Test.php89-101 tests/protocol/V3Test.php128-140


Serialization Verification


Protocol tests validate PackStream serialization by comparing captured write buffers against expected hex-encoded byte sequences.


Write Buffer Verification Pattern




Example: INIT Message Serialization tests/protocol/V1Test.php33-43:




Each hex string represents:


    

  1. Chunk size prefix (first 4 hex digits)
    2. 

  2. PackStream markers (type identifiers)
    3. 

  3. Data content (encoded values)
    4. 



Sources: tests/protocol/V1Test.php33-43 tests/protocol/V4Test.php36-43


Response Deserialization Testing


Tests validate that the Unpacker correctly deserializes mock responses using the self::$readArray structure.


Read Array Structure




Response Signature Mapping:
































HexSignatureMeaning
0x70SUCCESSOperation completed successfully
0x71RECORDResult record data
0x7EIGNOREDMessage ignored due to INTERRUPTED state
0x7FFAILUREOperation failed with error details


Example: PullAll Response Sequence tests/protocol/V1Test.php109-124:




Sources: tests/protocol/V1Test.php109-114 tests/protocol/V4Test.php29-33


Error Handling Verification


Protocol tests include comprehensive error handling validation through the checkFailure() helper method.


Failure Response Testing




Failure Test Pattern tests/protocol/V1Test.php56-59:




Failure Response Structure:




Sources: tests/protocol/V1Test.php56-59 tests/protocol/V3Test.php132-135


Test Dependencies and Execution Flow


PHPUnit @depends annotations ensure tests execute in the correct order and share protocol instances:




Constructor Test Pattern tests/protocol/V1Test.php17-22:




All subsequent tests declare dependency:




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


TestLayer Base Class


The TestLayer class tests/TestLayer.php12-110 provides shared functionality for all tests, both protocol-level and integration tests.


Environment Configuration




Sources: tests/TestLayer.php14-29


Protocol Version Detection Helper


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


Version Mapping Logic:











































































Neo4j VersionBolt Version
>= 2025.106
>= 5.265.8
>= 5.235.6
>= 5.135.4
>= 5.95.3
>= 5.75.2
>= 5.55.1
>= 5.05
>= 4.44.4
>= 4.34.3
>= 4.24.2
>= 4.14.1
>= 4.04
>= 3.53
>= 3.42
< 3.41


Sources: tests/TestLayer.php69-109


Unified Authentication Helper


The sayHello() method tests/TestLayer.php37-60 provides protocol-agnostic authentication:




Sources: tests/TestLayer.php37-60


NoDatabase Test Suite


The phpunit.xml configuration defines a "NoDatabase" suite specifically for protocol tests that don't require a live database connection. This suite can run in isolation, providing fast feedback during development.


Suite Organization:



























SuitePurposeTests
NoDatabaseProtocol and unit teststests/protocol/*Test.php, tests/FileCacheTest.php
Neo4jIntegration teststests/BoltTest.php, connection tests, structure tests
MemgraphMemgraph-specific teststests/MemgraphTest.php


For full suite configuration and CI integration, see Test Architecture and Organization and CI/CD Pipeline and Cross-Version Testing.


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