Overview

The hypervel/testbench package provides testing infrastructure for Hypervel/Hyperf applications. It extends PHPUnit with Hypervel-specific bootstrapping, service provider management, and coroutine-aware test execution. The package includes a base TestCase class, configuration management, and a self-contained workbench environment for development and testing.

This page provides a high-level introduction to the package architecture and components. For installation instructions, see page 1.1. For creating tests, see page 1.2. For detailed component documentation, see pages 2-9.

Package Definition and Dependencies

The package is defined in composer.json2-3 as "The testbench package for Hypervel" and requires PHP 8.2+. Key dependencies from composer.json22-28:

Dependency	Version	Purpose
hypervel/framework	^0.3	Laravel-like API layer on Hyperf foundation
phpunit/phpunit	^10.0.7	PHPUnit test execution framework
mockery/mockery	^1.6.10	Mocking and test doubles
symfony/yaml	^7.3	YAML configuration parsing for testbench.yaml
vlucas/phpdotenv	^5.6.1	.env file loading and generation

The package defines two PSR-4 autoload namespaces in composer.json30-34:

Hypervel\Testbench\ → src/ (Core testbench classes)
Workbench\App\ → workbench/app/ (Sample application code)

It also provides the bin/testbench-sync executable in composer.json44-46 for file synchronization.

Sources: composer.json1-51

Ecosystem Position

The testbench operates as a bridge between PHPUnit/Mockery testing tools and the Hypervel/Hyperf frameworks:

Diagram: Testbench in Framework Stack

The testbench extends Hypervel\Foundation\Testing\TestCase from src/TestCase.php28 and adds testbench-specific functionality through the Bootstrapper, ConfigProviderRegister, and three testing traits.

Sources: src/TestCase.php28-34 composer.json22-28

Core Components

The testbench consists of three primary components with importance scores based on edit frequency:

Diagram: Core Component Architecture

Component Roles

Component	File	Role
TestCase	src/TestCase.php28	Base test class managing application lifecycle, coroutine context, and test execution
ConfigProviderRegister	src/ConfigProviderRegister.php9	Static registry of 45+ Hyperf and Hypervel configuration providers
Bootstrapper	src/Bootstrapper.php	One-time environment setup: loads testbench.yaml, generates .env, defines BASE_PATH
HandlesRoutes	src/Concerns/HandlesRoutes.php	Trait providing defineRoutes() and defineWebRoutes() methods for route definition
CreatesApplication	src/Concerns/CreatesApplication.php	Trait providing getPackageProviders() and getPackageAliases() for provider registration
HandlesDatabases	src/Concerns/HandlesDatabases.php	Trait providing defineDatabaseMigrations() for database schema setup

The TestCase class is the most critical component (importance 11.69), followed by ConfigProviderRegister (8.17) and HandlesRoutes (8.00). See page 2 for detailed TestCase documentation, page 3 for ConfigProviderRegister, and page 4 for the testing traits.

Sources: src/TestCase.php28-34 src/ConfigProviderRegister.php9-88

Configuration System

The testbench uses multiple configuration sources that converge during application bootstrapping:

Diagram: Configuration Sources and Flow

Configuration Files

File	Purpose	Loaded By
testbench.yaml	Primary testbench configuration: providers, environment variables, workbench settings	Bootstrapper::bootstrap()
.env	Runtime environment variables (generated from testbench.yaml)	Bootstrapper::bootstrap() via vlucas/phpdotenv
workbench/config/*.php	Application configuration files: app.php, database.php, session.php, etc.	Hypervel\Foundation\Application during boot

See page 6 for comprehensive configuration documentation.

Sources: composer.json22-28 src/TestCase.php40-42

Package Structure

The package is organized into core source code, a workbench environment, and utilities:

Diagram: Package Directory Structure

Core Namespaces

The package defines two PSR-4 autoload namespaces:

1. Hypervel\Testbench\ → src/ - Core testbench infrastructure classes
2. Workbench\App\ → workbench/app/ - Sample application code for testing

The bin/testbench-sync script from composer.json44-46 can copy workbench files to a consumer project for rapid setup.

Sources: composer.json30-34 composer.json44-48

Test Lifecycle Overview

The TestCase class manages a sophisticated test lifecycle with one-time bootstrapping and per-test setup/teardown:

Diagram: Simplified Test Execution Flow

Key lifecycle characteristics:

1. One-Time Bootstrap: Bootstrapper::bootstrap() runs once per test suite via static flag $hasBootstrappedTestbench in src/TestCase.php36-42
2. Per-Test Application: Fresh Hypervel\Foundation\Application instance created in each setUp() via createApplication() in src/TestCase.php69-78
3. Coroutine Context: Setup and teardown operations wrapped in runInCoroutine() for Hyperf compatibility in src/TestCase.php57 and src/TestCase.php83
4. Swoole Cleanup: Timers cleared and coordinators resumed in afterApplicationCreated callback in src/TestCase.php45-50

See page 2.1 for comprehensive test lifecycle documentation.

Sources: src/TestCase.php36-88

Workbench Development Environment

The testbench includes a complete example application in the workbench/ directory. This serves dual purposes:

1. Template Application: The bin/testbench-sync script can copy workbench files to user projects for rapid setup
2. Internal Testing: Provides a working application for testing the testbench itself

Workbench Namespace Structure

The workbench uses the Workbench\App\ namespace registered in composer.json33:

The WorkbenchServiceProvider registers routes and console commands from the workbench directory. See page 5 for detailed workbench documentation.

Sources: composer.json33-34 composer.json44-46

Target Use Cases

The Hypervel Testbench is designed for several specific testing scenarios:

• Unit Testing: Testing individual Hypervel application components in isolation
• Integration Testing: Testing interactions between Hypervel services and Hyperf components
• HTTP Testing: Testing web controllers, middleware, and API endpoints
• Database Testing: Testing models, repositories, and database interactions
• Console Command Testing: Testing Artisan-style console commands and CLI tools
• Authentication Testing: Testing user authentication, authorization, and JWT token handling

For comprehensive configuration options, see Configuration Management. For database-specific testing features, see Database and Model Testing. For details on the isolated development environment, see Workbench Environment.

Sources: composer.json1-51