Architecture Overview

Purpose and Scope

This document explains the high-level architecture of the Hypervel Testbench system, detailing how the core components interact to provide a testing foundation for Hypervel/Hyperf applications. The architecture is organized into distinct layers, each with specific responsibilities in the test lifecycle.

For installation and initial setup procedures, see Installation and Setup. For a minimal working example, see Quick Start Guide. For detailed documentation of individual components, see TestCase: Core Testing Foundation, Configuration Provider System, and Testing Traits and Concerns.

Architectural Layers

The testbench architecture is organized into five primary layers, each serving a distinct purpose in the testing infrastructure:

Layer 1: Package Definition

The package is defined through composer.json, which specifies dependencies and autoloading configuration. This layer establishes the testbench as a consumable package.

Key Dependencies:

• hypervel/framework ^0.3 - Provides Laravel-like APIs on top of Hyperf
• phpunit/phpunit ^10.0.7 - Test execution framework
• mockery/mockery ^1.6.10 - Mocking capabilities
• Multiple Hyperf framework components (database, redis, http-server, etc.)

Layer 2: Core Testing Infrastructure

Three critical components form the testing infrastructure foundation:

Component	File	Importance	Purpose
TestCase	src/TestCase.php	11.69	Base test class, manages test lifecycle and application bootstrapping
ConfigProviderRegister	src/ConfigProviderRegister.php	8.17	Manages 45+ configuration providers from Hyperf and Hypervel ecosystems
Bootstrapper	src/Bootstrapper.php	0.11	One-time environment initialization and YAML configuration loading

Layer 3: Testing Concerns (Traits)

Three traits extend TestCase functionality through composition:

Trait	File	Importance	Purpose
HandlesRoutes	src/Concerns/HandlesRoutes.php	8.00	Route definition with web middleware grouping
CreatesApplication	src/Concerns/CreatesApplication.php	4.00	Service provider and alias registration
HandlesDatabases	src/Concerns/HandlesDatabases.php	2.00	Database migration management

Layer 4: Workbench Environment

A self-contained sample application located in the workbench/ directory, providing:

• Configuration files (config/app.php, config/database.php, etc.)
• Models (app/Models/User.php)
• Migrations (database/migrations/)
• Factories, controllers, views, and routes

Layer 5: Framework Foundation

Integration with Hypervel and Hyperf frameworks provides the runtime environment, including coroutine support, dependency injection, and HTTP/console capabilities.

Sources: src/TestCase.php1-110 src/ConfigProviderRegister.php1-88 src/Bootstrapper.php1-146

Core Component Architecture

The following diagram illustrates the relationships between core components using actual class names and file locations:

Diagram: Core Component Structure

Sources: src/TestCase.php28-34 src/TestCase.php69-78 src/Bootstrapper.php21-40

Configuration Provider System

The ConfigProviderRegister class serves as a central registry for framework configuration providers. It manages providers from both the Hyperf and Hypervel ecosystems.

Diagram: Configuration Provider Architecture

Provider Categories:

The 45+ providers are organized into functional categories:

Category	Hyperf Providers	Hypervel Providers
Core	Di, Framework, Engine	Foundation, Config
HTTP	HttpServer, HttpMessage	Router, Http, Cookie, Session
Database	DbConnection, Database\SQLite, ModelListener, Paginator	-
Caching	Redis, Pool	Cache, Redis
Messaging	-	Queue, Broadcasting, Notifications, Mail
Security	-	Auth, Encryption, Hashing, JWT
Developer Tools	Command, ExceptionHandler, Signal	Console, Log, Validation
Infrastructure	Dispatcher, Event, Process, Serializer, Server, Memory	Bus, Event, Dispatcher, Translation, ObjectPool

Sources: src/ConfigProviderRegister.php11-57 src/ConfigProviderRegister.php59-87

Test Lifecycle Architecture

The testbench implements a sophisticated lifecycle with one-time initialization separated from per-test setup and teardown.

Diagram: Test Lifecycle Flow

Key Lifecycle Methods:

Method	File Location	Execution	Purpose
Bootstrapper::bootstrap()	src/Bootstrapper.php21-40	Once per test run	Load YAML config, define BASE_PATH, generate .env
TestCase::setUp()	src/TestCase.php38-58	Before each test	Create application, setup routes/database
createApplication()	src/TestCase.php69-78	Per test	Instantiate Application, bind contracts
defineEnvironment()	src/TestCase.php63-67	Per test	Register providers and aliases
TestCase::tearDown()	src/TestCase.php80-88	After each test	Cleanup database, reset queue callbacks

Sources: src/TestCase.php38-58 src/TestCase.php69-78 src/TestCase.php80-88 src/Bootstrapper.php21-40

Bootstrap and Configuration Flow

The Bootstrapper class handles one-time initialization by loading configuration from multiple sources and preparing the environment.

Diagram: Bootstrap Configuration Flow

Configuration Processing:

The Bootstrapper::loadConfigFromYaml() method searches for configuration files in this order:

1. testbench.yaml
2. testbench.yaml.example
3. testbench.yaml.dist

Generated Files:

File	Generator Method	Content Source
workbench/.env	src/Bootstrapper.php98-108	$config['env'] array from YAML
workbench/composer.lock	src/Bootstrapper.php56-78	Mock lock file with provider metadata

Sources: src/Bootstrapper.php21-40 src/Bootstrapper.php56-78 src/Bootstrapper.php80-96 src/Bootstrapper.php98-108

Trait Composition Architecture

The TestCase class uses three traits to modularize functionality, following a trait-based composition pattern.

Diagram: TestCase Trait Composition

Trait Usage in TestCase:

src/TestCase.php30-34 shows the trait composition:

Trait Responsibilities:

Trait	Primary Methods	Called From
CreatesApplication	getPackageProviders(), getPackageAliases(), registerPackageProviders(), registerPackageAliases()	src/TestCase.php63-67 defineEnvironment()
HandlesDatabases	defineDatabaseMigrations(), destroyDatabaseMigrations()	Setup/teardown lifecycle
HandlesRoutes	setUpApplicationRoutes(), defineRoutes(), defineWebRoutes()	src/TestCase.php45-51 afterApplicationCreated callback

Sources: src/TestCase.php30-34 src/TestCase.php45-51 src/TestCase.php63-67

Application Container Integration

The TestCase creates and configures the Application container, binding core contracts and integrating with Hyperf's ApplicationContext.

Diagram: Application Container Setup

Container Bindings:

The src/TestCase.php69-78 createApplication() method performs three critical bindings:

1. Kernel Binding: KernelContract::class → ConsoleKernel::class

   • Enables console command execution in tests

2. Exception Handler Binding: ExceptionHandlerContract::class → ExceptionHandler::class

   • Routes exceptions to workbench's custom handler

3. Global Context: ApplicationContext::setContainer($app)

   • Makes the container globally accessible via Hyperf's context system

Sources: src/TestCase.php69-78

Coroutine Integration Architecture

The testbench integrates with Hyperf's coroutine runtime, ensuring test setup and teardown execute within coroutine context.

Diagram: Coroutine Lifecycle Integration

Coroutine Management:

The testbench ensures compatibility with Hyperf's async operations through:

1. Timer Cleanup: src/TestCase.php46 - Timer::clearAll() prevents timer leaks between tests

2. Coordinator Resume: src/TestCase.php47 - CoordinatorManager::until(Constants::WORKER_EXIT)->resume() ensures worker coordinator is ready

3. Coroutine-Wrapped Execution:

   • Setup: src/TestCase.php57 - runInCoroutine(fn () => $this->setUpTheTestEnvironmentUsingTestCase())
   • Teardown: src/TestCase.php83 - runInCoroutine(fn () => $this->tearDownTheTestEnvironmentUsingTestCase())

Sources: src/TestCase.php45-51 src/TestCase.php57 src/TestCase.php83

Summary

The Hypervel Testbench architecture is organized into five layers, with clear separation of concerns:

1. Package Definition Layer - Declares dependencies and autoloading
2. Core Testing Infrastructure - TestCase, ConfigProviderRegister, Bootstrapper
3. Testing Concerns - Modular traits for routes, providers, and databases
4. Workbench Environment - Self-contained sample application
5. Framework Foundation - Hypervel/Hyperf integration

The system implements key architectural patterns:

• Template Method Pattern - TestCase defines test lifecycle with extension points
• Trait Composition - Modular functionality via traits
• One-Time vs Per-Test Separation - Optimized initialization strategy
• Static Registry Pattern - ConfigProviderRegister as central provider registry
• Coroutine Transparency - Hyperf async operations work seamlessly in synchronous-looking tests

This architecture enables package developers to write standard PHPUnit tests that correctly handle Hypervel/Hyperf's coroutine-based async operations while maintaining clean separation between testing infrastructure and test code.