Last indexed: 7 March 2026 (96fbab)

PHPUnit Configuration and CI/CD

This document describes the PHPUnit testing configuration and CI/CD infrastructure for the Hypervel framework. It covers the test suite organization, GitHub Actions workflows, integration test setup, and local development configuration.

For information about HTTP testing utilities and request mocking, see HTTP Testing and Request Mocking. For process testing facilities, see Process Testing.

Overview

Hypervel's testing infrastructure uses PHPUnit for unit and integration tests, executed via GitHub Actions workflows. The system supports testing across multiple PHP versions (8.2-8.4) and Swoole versions (5.1.6, 6.0.2), with dedicated integration test jobs for external services like Meilisearch and Typesense.

Test Suite Organization

The test suite is organized as a monorepo test structure covering all 23 framework components. The PHPUnit configuration defines test discovery patterns, exclusions, and runtime settings.

PHPUnit Configuration File

The phpunit.xml.dist1-29 file configures the test environment:

Configuration	Value	Purpose
Bootstrap	`tests/bootstrap.php`	Loads environment and autoloader
Test Suite Name	"Hypervel Packages Test Suite"	Identifies the test collection
Test Directory	`./tests`	Root directory for test discovery
Test Pattern	`*Test.php` suffix	Files matching this pattern are included
Excluded Paths	Prompts, Sentry, Horizon	Components excluded from standard runs
Memory Limit	1024M	Maximum memory allocation
Process Isolation	Disabled	Tests run in shared process

Diagram: Test Suite Organization and Configuration

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

Test Bootstrap Process

The tests/bootstrap.php1-23 file initializes the test environment:

Autoloader Loading: Requires Composer's autoloader from vendor/autoload.php
Environment File Loading: Uses Dotenv to load .env if present for local development
Unsafe Immutable Mode: Creates Dotenv instance with createUnsafeImmutable() to allow overrides

This bootstrap approach enables local developers to configure integration tests via a .env file while CI environments use workflow-level environment variables.

Sources: tests/bootstrap.php1-23 .env.example1-17

GitHub Actions CI/CD Pipeline

The CI/CD infrastructure uses GitHub Actions with three separate workflows for comprehensive testing coverage.

Main Test Workflow

The .github/workflows/tests.yml1-116 defines three parallel jobs:

Diagram: GitHub Actions Workflow Structure

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

Test Matrix Configuration

The linux_tests job uses a strategy matrix to test across multiple PHP and Swoole combinations:

PHP Version	Swoole Version	Container Image
8.2	5.1.6	`phpswoole/swoole:5.1.6-php8.2`
8.3	5.1.6	`phpswoole/swoole:5.1.6-php8.3`
8.4	6.0.2	`phpswoole/swoole:6.0.2-php8.4`

The workflow executes these steps for each matrix combination:

Checkout: Uses actions/checkout@v4 to clone the repository
Install Dependencies: Runs composer install --prefer-dist -n -o with unlimited memory
Code Style Check: Executes php-cs-fixer fix --dry-run --diff to validate coding standards
PHPUnit Execution: Runs phpunit -c phpunit.xml.dist --exclude-group integration to execute non-integration tests

Sources: .github/workflows/tests.yml8-39

Integration Test Jobs

Integration tests run in separate jobs with dedicated service containers:

Diagram: Integration Test Service Architecture

Meilisearch Integration

The .github/workflows/tests.yml41-79 configures Meilisearch testing:

Service Container: getmeili/meilisearch:latest exposed on port 7700
Environment Variables:
- RUN_MEILISEARCH_INTEGRATION_TESTS=true - Enables test execution
- MEILISEARCH_HOST=meilisearch - Service hostname within Docker network
- MEILISEARCH_PORT=7700 - Service port
- MEILISEARCH_KEY=secret - Master key for authentication
Health Check: Monitors /health endpoint with 10s intervals, 5s timeout, 5 retries
PHPUnit Group: --group meilisearch-integration isolates these tests

Typesense Integration

The .github/workflows/tests.yml81-115 configures Typesense testing:

Service Container: typesense/typesense:27.1 exposed on port 8108
Environment Variables:
- RUN_TYPESENSE_INTEGRATION_TESTS=true - Enables test execution
- TYPESENSE_HOST=typesense - Service hostname
- TYPESENSE_PORT=8108 - Service port
- TYPESENSE_API_KEY=secret - API key for authentication
- TYPESENSE_PROTOCOL=http - Protocol selection
PHPUnit Group: --group typesense-integration isolates these tests

Sources: .github/workflows/tests.yml41-115

Static Analysis Workflow

The .github/workflows/static-analysis.yml1-40 runs PHPStan for type checking:

Diagram: Static Analysis Workflow Structure

The workflow runs two separate PHPStan analyses:

Standard analysis with phpstan.neon.dist
Type-specific analysis with phpstan.types.neon.dist

Both analyses run with unlimited memory allocation (--memory-limit=-1).

Sources: .github/workflows/static-analysis.yml1-40

Environment Configuration

Environment Variables in PHPUnit

The phpunit.xml.dist21-28 sets default environment variables:

Variable	Default Value	Purpose
`RUN_BLOCKING_TESTS`	`false`	Controls execution of blocking tests (e.g., sleep operations)
`APP_ENV`	`testing`	Sets application environment to testing mode
`error_reporting`	`-1`	Reports all PHP errors
`display_errors`	`on`	Enables error display
`display_startup_errors`	`on`	Shows startup errors

Local Development Configuration

The .env.example1-17 provides a template for local integration test configuration:

# Meilisearch Integration Tests
RUN_MEILISEARCH_INTEGRATION_TESTS=false
MEILISEARCH_HOST=127.0.0.1
MEILISEARCH_PORT=7700
MEILISEARCH_KEY=secret

# Typesense Integration Tests
RUN_TYPESENSE_INTEGRATION_TESTS=false
TYPESENSE_HOST=127.0.0.1
TYPESENSE_PORT=8108
TYPESENSE_API_KEY=secret
TYPESENSE_PROTOCOL=http

Developers copy this to .env and configure service endpoints for local testing. The .env file is excluded from version control via .gitignore8-11

Sources: .env.example1-17 phpunit.xml.dist21-28 .gitignore8-11

Test Execution Commands

Standard Test Suite

Execute all non-integration tests:

This command runs all tests except those marked with the integration group annotation.

Integration Tests

Execute specific integration test groups:

Meilisearch tests:

Typesense tests:

Code Style Validation

Check code style compliance:

The --dry-run flag prevents modifications, while --diff displays proposed changes.

Sources: .github/workflows/tests.yml38-115

Test Group Organization

Diagram: Test Group Organization and Execution

Test groups are defined using PHPUnit's @group annotation in test class or method docblocks. The framework uses this grouping to:

Separate Fast and Slow Tests: Integration tests requiring external services are isolated
Enable Selective Execution: Run only relevant tests for specific changes
Optimize CI Pipeline: Parallel execution of independent test groups

Sources: phpunit.xml.dist1-29 .github/workflows/tests.yml39-115

Test Isolation and Coroutine Support

The test infrastructure supports coroutine-based testing through the RunTestsInCoroutine trait, as demonstrated in tests/Process/ProcessTest.php7-23 This trait enables:

Coroutine Context: Tests run within Swoole coroutines, matching production behavior
Context Isolation: Each test has isolated coroutine context for request-scoped data
Async Operations: Tests can validate asynchronous operations without blocking

Process isolation is disabled in phpunit.xml.dist6 to improve test performance, relying instead on proper cleanup between tests.

Sources: tests/Process/ProcessTest.php7-23 phpunit.xml.dist6

Skip CI Mechanism

Both test and static analysis workflows support commit message flags to skip execution:

[skip ci] - Skips all CI workflows
[ci skip] - Alternative skip flag

The condition is checked at .github/workflows/tests.yml10 and .github/workflows/static-analysis.yml10:

This mechanism allows developers to bypass CI for documentation-only changes or work-in-progress commits.

Sources: .github/workflows/tests.yml10 .github/workflows/static-analysis.yml10

Composer Configuration for Tests

Test execution requires Composer dependencies installed with specific flags:

Flag	Purpose
`COMPOSER_MEMORY_LIMIT=-1`	Removes memory limit for dependency resolution
`--prefer-dist`	Downloads distribution packages instead of cloning repositories
`-n`	Non-interactive mode (no prompts)
`-o`	Optimizes autoloader for production-like performance

This configuration ensures consistent dependency resolution across local and CI environments.

Sources: .github/workflows/tests.yml34 .github/workflows/static-analysis.yml34

Container Image Strategy

The CI/CD pipeline uses official PHP-Swoole Docker images:

PHP Version	Swoole Version	Image Tag
8.2	5.1.6	`phpswoole/swoole:5.1.6-php8.2`
8.3	5.1.6	`phpswoole/swoole:5.1.6-php8.3`
8.4	6.0.2	`phpswoole/swoole:6.0.2-php8.4`

The images include:

Pre-compiled Swoole extension
All required PHP extensions
Alpine Linux base for minimal size
Ready-to-use PHP CLI environment

Integration test jobs use PHP 8.4 with Swoole 6.0.2 (.github/workflows/tests.yml62-97) as the reference environment for external service compatibility.

Sources: .github/workflows/tests.yml23-97

Test Result Artifacts

The workflows produce several artifacts:

PHPUnit Output: Test execution results, assertions, and failures
Code Coverage (if enabled): Coverage reports in various formats
PHP-CS-Fixer Diff: Proposed style fixes for non-compliant code
PHPStan Analysis: Type errors and code quality issues

Results are displayed in the GitHub Actions UI with job-level status indicators and detailed logs for each step.

Sources: .github/workflows/tests.yml1-116 .github/workflows/static-analysis.yml1-40

Refresh this wiki

URL: https://deepwiki.com/hypervel/components/11.1-phpunit-configuration-and-cicd