Testing Infrastructure

This document describes the testing framework and utilities built into Hypervel. It covers PHPUnit configuration, GitHub Actions CI/CD workflows, HTTP client testing utilities with request faking and stubbing, and process testing capabilities. For information about monitoring production systems, see Telescope Monitoring System.

---

PHPUnit Configuration and Test Execution

PHPUnit Setup

Hypervel uses PHPUnit as its testing framework with configuration defined in phpunit.xml.dist1-30 The configuration specifies:

• Bootstrap file: tests/bootstrap.php loads environment variables from .env if present
• Test suite: All *Test.php files in the tests/ directory, excluding Prompts, Sentry, and Horizon subdirectories
• Process isolation: Disabled (processIsolation="false") for performance
• Test environment: APP_ENV set to testing
• Memory limit: 1024M for test execution
• Error reporting: Full display of deprecations, warnings, and notices

The bootstrap file tests/bootstrap.php1-23 loads the Composer autoloader and optionally loads environment variables from a .env file for local integration testing.

Test Bootstrap Sequence

Sources: phpunit.xml.dist1-30 tests/bootstrap.php1-23

GitHub Actions CI/CD Pipeline

The framework uses GitHub Actions to run tests across multiple PHP and Swoole versions. The workflow is defined in .github/workflows/tests.yml1-116

CI/CD Test Matrix

Job Name	PHP Versions	Swoole Versions	Purpose
linux_tests	8.2, 8.3, 8.4	5.1.6, 5.1.6, 6.0.2	Unit tests, code style checks
meilisearch_integration_tests	8.4	6.0.2	Meilisearch search engine integration
typesense_integration_tests	8.4	6.0.2	Typesense search engine integration

The main test job runs:

1. PHP CS Fixer: Code style validation with vendor/bin/php-cs-fixer fix --dry-run --diff
2. PHPUnit: Unit tests with vendor/bin/phpunit -c phpunit.xml.dist --exclude-group integration

GitHub Actions Workflow Architecture

Sources: .github/workflows/tests.yml1-116

Integration Tests

Integration tests are isolated in separate CI/CD jobs with dedicated service containers. They are controlled by environment variables:

• Meilisearch: Requires RUN_MEILISEARCH_INTEGRATION_TESTS=true with configuration for host, port, and API key
• Typesense: Requires RUN_TYPESENSE_INTEGRATION_TESTS=true with configuration for host, port, API key, and protocol

The .env.example1-17 file provides a template for local integration testing configuration. Tests are skipped by default when these environment variables are false or absent.

Sources: .github/workflows/tests.yml41-80 .github/workflows/tests.yml81-116 .env.example1-17 tests/bootstrap.php17-22

---

HTTP Testing and Request Mocking

HTTP Client Factory Fake Mode

The Hypervel\HttpClient\Factory class provides comprehensive testing utilities for faking HTTP requests. When fake() is called, the factory intercepts all HTTP requests and returns stubbed responses instead of making real network calls.

HTTP Client Testing Architecture

Sources: src/http-client/src/Factory.php183-224 src/http-client/src/Factory.php311-317

Request Stubbing Patterns

The factory supports multiple stubbing patterns:

1. Basic Fake (Default 200 OK)

2. URL Pattern Matching

3. Status Code Shorthand

4. Body Shorthand

5. Callback with Request Inspection

Sources: tests/HttpClient/HttpClientTest.php76-83 tests/HttpClient/HttpClientTest.php508-528 tests/HttpClient/HttpClientTest.php99-127

Response Sequences

ResponseSequence provides ordered responses for repeated requests to the same endpoint:

Sources: src/http-client/src/ResponseSequence.php1-133

Example Usage:

Sources: tests/HttpClient/HttpClientTest.php859-893 tests/HttpClient/HttpClientTest.php895-908

Assertion Methods

The factory provides PHPUnit-style assertions for verifying HTTP requests:

Method	Description
assertSent(callable)	Assert a request matching the callback was sent
assertSentInOrder(array)	Assert requests were sent in specific order
assertNotSent(callable)	Assert no request matching the callback was sent
assertNothingSent()	Assert no requests were sent
assertSentCount(int)	Assert exact number of requests sent
assertSequencesAreEmpty()	Assert all ResponseSequence instances are depleted

Assertion Example:

The recorded(callable) method returns a Collection of request/response pairs, allowing custom filtering:

Sources: src/http-client/src/Factory.php311-382 tests/HttpClient/HttpClientTest.php524-528 tests/HttpClient/HttpClientTest.php726-742

Preventing Stray Requests

The preventStrayRequests() method throws an exception if any request is made without a matching fake:

This ensures all HTTP calls in tests are explicitly mocked, preventing accidental real network requests during testing.

Sources: src/http-client/src/Factory.php263-286 src/http-client/src/PendingRequest.php139-140

Request Inspection

The Request class provides methods for inspecting faked requests:

• url(): Get the full URL
• method(): Get HTTP method (GET, POST, etc.)
• hasHeader(key, value): Check for specific headers
• body(): Get raw request body
• data(): Get parsed form/JSON data
• isJson(), isForm(), isMultipart(): Check content type
• Array access: $request['field'] accesses parsed data

Sources: src/http-client/src/Request.php1-279 tests/HttpClient/HttpClientTest.php524-528

---

Process Testing

Process Factory Fake Mode

Similar to HTTP client testing, the Hypervel\Process\Factory class provides a fake mode for testing process execution without running actual system commands.

Process Testing Architecture

Sources: tests/Process/ProcessTest.php175-186 tests/Process/ProcessTest.php232-249

Fake Response Patterns

1. Basic Fake (Default Success)

2. Custom Output

3. Exit Code Shorthand

4. Pattern Matching

5. Multi-line Commands

Sources: tests/Process/ProcessTest.php175-186 tests/Process/ProcessTest.php231-249 tests/Process/ProcessTest.php335-349 tests/Process/ProcessTest.php209-229

Process Sequences

Process sequences work like HTTP response sequences, returning different results for repeated command executions:

Use dontFailWhenEmpty() to return empty results instead of throwing:

Sources: tests/Process/ProcessTest.php351-370 tests/Process/ProcessTest.php372-391

Process Result Description

The describe() method provides a fluent API for building complex fake results:

Sources: tests/Process/ProcessTest.php295-306 tests/Process/ProcessTest.php327-333

Process Pool Testing

Process pools can be faked individually or globally:

Named processes can be accessed by key:

Sources: tests/Process/ProcessTest.php64-84 tests/Process/ProcessTest.php127-143

Preventing Stray Processes

Similar to HTTP testing, preventStrayProcesses() ensures all processes are explicitly faked:

Sources: tests/Process/ProcessTest.php414-430 tests/Process/ProcessTest.php432-448

Exception Throwing in Fakes

Fakes can throw exceptions to simulate process failures:

Sources: tests/Process/ProcessTest.php462-472

---

Test Isolation and Coroutine Safety

All test utilities in Hypervel respect coroutine isolation. The RunTestsInCoroutine trait can be used to ensure tests run within coroutine contexts when needed:

This ensures that tests accurately reflect production behavior where requests are handled in separate coroutines with isolated contexts.

Sources: tests/Process/ProcessTest.php23