Testing Infrastructure

This document describes the testing infrastructure for the friendsofhyperf/components monorepo, including the Pest-based testing framework, base test case setup, CI/CD pipeline configuration, and common testing patterns. For information about the CI/CD pipeline workflow details, see CI/CD Pipeline.

Sources: tests/TestCase.php1-47 .github/workflows/tests.yaml1-94

---

Pest Testing Framework

The monorepo uses Pest as its primary testing framework, providing an expressive and elegant syntax for writing tests. Tests are executed with coroutine support and parallel execution capabilities.

Framework Configuration

The test suite is configured to run with the following capabilities:

• Parallel Execution: Tests run in parallel mode using pest --parallel
• Type Coverage: Automated type analysis via composer analyse:types
• Component Groups: Tests organized by component for selective execution

The framework integrates with:

• Mockery for test doubles
• Hyperf's coroutine context for isolation
• Faker for data generation (implicit through dependencies)

Sources: .github/workflows/tests.yaml89-94 tests/TestCase.php22-26

---

Base TestCase Class Architecture

Class Structure and Traits

The TestCase class at tests/TestCase.php22-47 serves as the foundation for all test cases in the monorepo:

Sources: tests/TestCase.php22-26

Initialization and Teardown Flow

The test lifecycle includes automatic mixin registration and container management:

Sources: tests/TestCase.php27-41

Mixin Registration Process

Two critical mixin listeners are executed during test setup:

Mixin Listener	Purpose	Methods Registered
RegisterMixinListener (Macros)	Extends RequestInterface with Laravel-style methods	validate(), collect(), boolean(), date(), enum(), only(), except(), etc.
RegisterMixinListener (FastPaginate)	Adds performance-optimized pagination to Query Builder	fastPaginate(), simpleFastPaginate()

The registration happens at tests/TestCase.php30-31:

This ensures all tests have access to extended functionality without requiring manual setup.

Sources: tests/TestCase.php27-34 src/macros/src/RequestMixin.php1-387

---

CI/CD Testing Matrix

Multi-Version Testing Strategy

The GitHub Actions workflow at .github/workflows/tests.yaml implements comprehensive matrix testing:

Sources: .github/workflows/tests.yaml22-94

Testing Matrix Configuration

Dimension	Values	Total Combinations
PHP Versions	8.1, 8.2, 8.3	3
Swoole Versions	5.1.8, 6.0.2, 6.1.3	3
Operating System	ubuntu-latest	1
Total Test Jobs	9

The workflow includes a retry strategy (max 2 attempts, 10-minute timeout) to handle transient failures.

Sources: .github/workflows/tests.yaml54-63

Service Dependencies

External services required for testing are configured via shell script:

• Redis: Docker container on port 6379 (.travis/setup.services.sh3-10)
• PHP Extensions: redis, pdo, pdo_mysql, bcmath, swoole (.github/workflows/tests.yaml39-41)

Sources: .travis/setup.services.sh1-10 .github/workflows/tests.yaml70-76

---

Test Organization and Component Groups

Directory Structure

Tests are organized by component, mirroring the source structure:

tests/
├── TestCase.php # Base test case
├── Concerns/
│ └── InteractsWithContainer.php # Container trait
├── Helpers/
│ └── HelpersTest.php # Helper function tests
├── Facade/
│ └── FacadeTest.php # Facade pattern tests
├── Macros/
│ ├── HttpServerRequestTest.php # Request macro tests
│ └── HtmlStringTest.php # HTML string tests
├── Tinker/
│ └── TinkerCasterTest.php # Tinker caster tests
├── FastPaginate/
│ └── BuilderTest.php # Fast paginate tests
└── [Other Components]/

Component Test Examples

Each component follows consistent patterns. Here are representative examples:

Helper Functions Testing

Tests at tests/Helpers/HelpersTest.php validate 50+ global helper functions:

test('test ClassNamespace', ...) # class_namespace() function
test('test ObjectGet', ...) # object_get() function
test('test PregReplaceArray', ...) # preg_replace_array() function
test('test filled', ...) # filled() function
test('test blank', ...) # blank() function
test('test literal', ...) # literal() function
test('test transform', ...) # transform() function
test('test rescue', ...) # rescue() function

Tests use datasets for parameterized testing at tests/Helpers/HelpersTest.php39-62

Sources: tests/Helpers/HelpersTest.php1-209

Request Macro Testing

Tests at tests/Macros/HttpServerRequestTest.php verify the 40+ macro methods registered on RequestInterface:

test('test only', ...) # only() macro
test('test isEmptyString', ...) # isEmptyString() macro
test('test getHost', ...) # getHost() macro
test('test getPort', ...) # getPort() macro
test('test getScheme', ...) # getScheme() macro
test('test wantsJson', ...) # wantsJson() macro
test('test fake', ...) # fake() static method
test('test getPsrRequest', ...) # getPsrRequest() macro

Each test uses Mockery to create ServerRequestInterface mocks with predefined behavior.

Sources: tests/Macros/HttpServerRequestTest.php1-180

Global Macro Registration Verification

Tests at tests/FastPaginate/BuilderTest.php14-22 verify macro registration:

Sources: tests/FastPaginate/BuilderTest.php1-23

---

Testing Patterns and Mock Utilities

Mockery Integration

The test suite uses Mockery for creating test doubles. The base TestCase ensures proper cleanup:

Sources: tests/TestCase.php36-41

Context Management Pattern

Tests that interact with HTTP requests use Hyperf's Context API for coroutine-local storage:

Example pattern from tests/Macros/HttpServerRequestTest.php18-21:

Sources: tests/Macros/HttpServerRequestTest.php18-34

Request Faking Pattern

The Request::fake() static method provides a convenient way to create test requests:

Sources: tests/Macros/HttpServerRequestTest.php154-170 src/macros/src/RequestMixin.php125-128

Mock Builder Pattern

Common pattern for creating PSR-7 request mocks with specific behavior:

This pattern is used extensively in tests/Macros/HttpServerRequestTest.php for testing request methods.

Sources: tests/Macros/HttpServerRequestTest.php53-76

Expectation API

Tests use Pest's expectation API for fluent assertions:

Sources: tests/Helpers/HelpersTest.php26-209 tests/Facade/FacadeTest.php21-38

---

Code Quality and Analysis

Static Analysis

The CI pipeline runs two levels of static analysis:

1. PHPStan on source code: composer analyse src (.github/workflows/tests.yaml84)
2. Type Coverage tests: composer analyse:types (.github/workflows/tests.yaml86)

Code Style Enforcement

PHP-CS-Fixer runs on PHP 8.1 to enforce coding standards:

The workflow also validates composer.json normalization for all components:

Sources: .github/workflows/tests.yaml23-49

---

Test Execution Summary

Complete Testing Pipeline

Sources: .github/workflows/tests.yaml1-94

Key Testing Metrics

Metric	Configuration
PHP Version Coverage	8.1, 8.2, 8.3
Swoole Version Coverage	5.1.8, 6.0.2, 6.1.3
Parallel Execution	Enabled
Retry Strategy	2 attempts, 10-minute timeout
Test Isolation	Per-coroutine container
Mock Framework	Mockery
External Services	Redis (Docker)

Sources: .github/workflows/tests.yaml54-94