Test Suite Structure

The test/ directory contains a comprehensive suite of unit and integration tests designed to validate the SDK's core logic and its various transport consumers. The suite utilizes PHPUnit for test execution, donatj/MockWebServer for HTTP interception, and vlucas/phpdotenv for environment configuration.

Test Configuration and Environment

The test environment is orchestrated through a central PHPUnit configuration and environment variables.

PHPUnit Configuration (phpunit.xml)

The phpunit.xml file defines the testing environment, including:

• Bootstrap: Loads vendor/autoload.php to initialize the class autoloader phpunit.xml6
• Test Suites: Defines the analytics-php suite which targets the test directory phpunit.xml30-34
• Coverage: Configured to process files in the lib directory and output Clover reports to build/logs/clover.xml phpunit.xml22-29
• Error Handling: Converts errors, notices, and warnings to exceptions phpunit.xml8-10

Environment Loading (.env)

Tests rely on a .env file located at the project root for sensitive or configurable data like the WRITE_KEY. Each test class typically loads this in its setUpBeforeClass method using Dotenv\Dotenv test/AnalyticsTest.php18-23 test/ConsumerSocketTest.php17-23

Mock Web Server

To avoid hitting production RudderStack endpoints during testing, the suite uses donatj\MockWebServer.

• Initialization: Started in setUpBeforeClass test/AnalyticsTest.php25-26
• Route Mocking: The /v1/batch path is typically mocked to return a 200 OK response test/AnalyticsTest.php27-31
• URL Injection: The mock server's root URL is retrieved via getServerRoot() and passed to the Client as the data_plane_url test/AnalyticsTest.php37-44

Data Flow: Test Environment Setup

Sources: test/AnalyticsTest.php18-44 phpunit.xml1-41

---

Test Classes and Coverage

The test suite is partitioned by the specific component or consumer being validated.

AnalyticsTest

Validates the Rudder static facade. It ensures that calls to Rudder::track, Rudder::identify, etc., are correctly delegated and that input validation (e.g., requiring userId or anonymousId in group calls) functions as expected test/AnalyticsTest.php47-101

Consumer Tests

Each consumer implementation has a corresponding test file to verify its specific transport mechanics:

Test Class	Target Component	Key Validations
ConsumerLibCurlTest	lib/Consumer/LibCurl.php	Synchronous curl execution, request compression test/ConsumerLibCurlTest.php38-213
ConsumerForkCurlTest	lib/Consumer/ForkCurl.php	Async "fire-and-forget" behavior, shell execution safety test/ConsumerForkCurlTest.php37-209
ConsumerSocketTest	lib/Consumer/Socket.php	Raw TCP socket connection, timeout handling, and payload size enforcement test/ConsumerSocketTest.php35-241
ConsumerFileTest	lib/Consumer/File.php	JSON line-delimited logging and integration with the SendBatchFromFile.php utility test/ConsumerFileTest.php56-244

Key Test Utilities

• checkWritten($type): Used in ConsumerFileTest to verify that events are correctly appended to the log file and contain the expected JSON structure test/ConsumerFileTest.php81-90
• __destruct(): Explicitly called in tests to trigger the Consumer::flush() logic, ensuring that queued events are dispatched before the test finishes test/ConsumerSocketTest.php147 test/ConsumerLibCurlTest.php56

Code Entity Mapping: Consumer Testing

Sources: test/ConsumerLibCurlTest.php43-52 test/ConsumerSocketTest.php29-32 test/ConsumerFileTest.php61-70

---

Specialized Test Scenarios

The suite covers several edge cases and error conditions beyond standard event tracking.

Error Handling and Debug Mode

Tests verify that the SDK behaves differently depending on the debug flag:

• Production Mode: Errors should be suppressed unless a custom error_handler is provided test/ConsumerSocketTest.php150-167
• Debug Mode: Errors should trigger the error_handler or throw exceptions immediately to aid development test/ConsumerSocketTest.php169-188

Large Payload Handling

ConsumerSocketTest and ConsumerLibCurlTest include scenarios where payloads exceed the maximum allowed size (e.g., 32KB). These tests ensure the SDK returns false and refuses to enqueue items that would break transport limits test/ConsumerSocketTest.php216-240 test/ConsumerLibCurlTest.php215-244

Request Compression

Tests for LibCurl and ForkCurl consumers specifically validate the compress_request option. They ensure that when enabled, the transport layer correctly handles Gzip compression of the JSON batch test/ConsumerLibCurlTest.php190-213 test/ConsumerForkCurlTest.php186-209

Sequence: Socket Consumer Error Test

Sources: test/ConsumerSocketTest.php216-240 README.md51