Running Tests

This page provides practical instructions for executing the test suite during development. For information about test architecture and organization, see Test Architecture and Organization. For details on the CI/CD pipeline, see CI/CD Pipeline and Cross-Version Testing.

Overview

The library uses PHPUnit for testing with a multi-tier strategy that separates tests requiring database connectivity from those that do not. Tests are organized into four primary test suites that can be run independently or together.

Prerequisites

Before running tests, ensure the following are installed:

• PHP 8.2 or higher
• Composer dependencies installed via composer install
• Required PHP extensions: mbstring, sockets (optional, for Socket connection class)
• Database service (Neo4j, Memgraph, or NornicDB) if running integration tests

Sources: README.md45-54 phpunit.xml1-27

PHPUnit Configuration

The test configuration is defined in phpunit.xml at the project root. This file specifies four test suites, each targeting different testing scenarios:

Sources: phpunit.xml3-22

Running Test Suites

NoDatabase Test Suite

The NoDatabase test suite runs without requiring a database connection. It validates protocol message construction, state transitions, and utility classes using mocked connections.

This suite includes:

• Protocol version tests (V1Test, V2Test, V3Test, V4Test, V4_1Test, V4_2Test, V4_3Test, V4_4Test) from tests/protocol/
• Cache implementation tests from tests/helpers/FileCacheTest.php

These tests execute quickly and do not require external dependencies, making them ideal for rapid development iteration.

Sources: phpunit.xml12-15 .github/workflows/no-db.yml31-32

Neo4j Test Suite

The Neo4j test suite executes integration tests against a live Neo4j database. This suite requires:

• Neo4j server running on localhost or specified host
• Valid credentials configured via environment variables

The suite validates:

• Connection establishment (Socket, StreamSocket)
• Query execution and result streaming
• Transaction management
• Structure serialization
• Large data chunking
• SSL/TLS connectivity (including Neo4j Aura)

Sources: phpunit.xml4-11 tests/BoltTest.php1-205 .github/workflows/neo4j.5.yml44-48

Memgraph Test Suite

The Memgraph test suite tests compatibility with Memgraph database, which implements a subset of the Bolt protocol.

This suite requires a Memgraph instance running on 127.0.0.1:7687 and validates:

• Connection with authentication scheme none
• Basic data type handling
• Transaction support
• Temporal structures (Duration, Date, LocalTime, LocalDateTime)

Sources: phpunit.xml16-18 tests/MemgraphTest.php1-154 .github/workflows/memgraph.yml33-34

NornicDB Test Suite

The NornicDB test suite tests compatibility with NornicDB, an emerging graph database.

This suite requires NornicDB running on 127.0.0.1:7687 and uses protocol version 4.4.4 with authentication scheme none.

Sources: phpunit.xml19-21 tests/NornicDBTest.php1-137 .github/workflows/nornicdb.yml36-37

Environment Variables and Configuration

The test suite uses environment variables and PHPUnit configuration variables to customize test execution:

Variable	Purpose	Default	Scope
NEO_HOST	Neo4j server hostname	127.0.0.1	Neo4j suite
NEO_PORT	Neo4j server port	7687	Neo4j suite
NEO_USER	Neo4j username	neo4j	Neo4j suite
NEO_PASS	Neo4j password	nothing123	Neo4j suite
BOLT_ANALYTICS_OPTOUT	Disable analytics tracking	(not set)	All suites

Default Values in phpunit.xml

The configuration file provides default credentials for Neo4j:

Sources: phpunit.xml23-26 tests/BoltTest.php24-33 README.md288-290

Test Execution Flow

Sources: phpunit.xml1-27 tests/BoltTest.php59-73 tests/protocol/V1Test.php17-22

Running Specific Tests

Single Test File

To run a specific test file:

Single Test Method

To run a single test method within a class:

Test Methods with Dependencies

Some tests use PHPUnit's @depends annotation to share state. For example, BoltTest::testHello() establishes a connection that subsequent tests reuse:

When running dependent tests, PHPUnit automatically executes the dependency first.

Sources: tests/BoltTest.php59-90 tests/BoltTest.php75-90

Test Class Hierarchy

The test suite uses inheritance to share mock infrastructure:

• TestLayer: Base class for integration tests, provides helper methods for connecting to databases
• ProtocolLayer: Base class for protocol tests, provides mocking infrastructure for testing without database
• Integration test classes (BoltTest, MemgraphTest, NornicDBTest): Extend TestLayer
• Protocol test classes (V1Test, V3Test, etc.): Extend ProtocolLayer

Sources: tests/BoltTest.php17 tests/protocol/V1Test.php15 tests/protocol/V3Test.php15

Debugging Tests

Enable Debug Output

The library provides a debug mode that prints binary communication in hexadecimal format:

This can be enabled at the beginning of a test method to see the raw protocol messages exchanged.

Sources: README.md93

Verbose PHPUnit Output

For detailed test execution information:

Test Markers

PHPUnit supports test markers for organizing test execution:

• @large: Marks tests that are slow or resource-intensive (e.g., testChunking)
• @depends: Creates test dependencies to share state

Sources: tests/BoltTest.php174 tests/BoltTest.php76

Common Test Patterns

Mocked Connection for Protocol Tests

Protocol version tests use ProtocolLayer::mockConnection() to create test connections that read/write from predefined buffers:

The mock connection validates that the protocol writes expected bytes and returns configured responses.

Sources: tests/protocol/V1Test.php170-187

Integration Test Pattern

Integration tests follow a standard pattern:

1. Establish connection
2. Authenticate (hello/logon)
3. Execute operations
4. Validate responses
5. Clean up (goodbye/reset)

Sources: tests/BoltTest.php59-73 tests/BoltTest.php78-90

Testing with Transactions

Transaction tests validate rollback behavior by creating nodes within a transaction, rolling back, and verifying the node doesn't exist:

Sources: tests/BoltTest.php111-143 tests/MemgraphTest.php89-121

Test Coverage by Protocol Version

The protocol test suite validates all supported 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	(inherits V1)
V3Test	3.0	HELLO, BEGIN, COMMIT, ROLLBACK, GOODBYE
V4Test	4.0	Parameterized PULL, DISCARD
V4_1Test	4.1	(inherits V4)
V4_2Test	4.2	(inherits V4)
V4_3Test	4.3	ROUTE message
V4_4Test	4.4	Enhanced ROUTE with database parameter

Sources: tests/protocol/V1Test.php1-212 tests/protocol/V3Test.php1-219 tests/protocol/V4Test.php1-97 tests/protocol/V4_3Test.php1-60