Testbench Configuration (testbench.yaml)

This document describes the structure and configuration options available in testbench.yaml, the primary configuration file for the Hypervel Testbench environment. The YAML file controls service provider registration, environment variables, workbench discovery settings, and cleanup rules.

For information about the bootstrapping process that loads this configuration, see Bootstrapper Lifecycle. For details about workbench application configuration files (app.php, database.php, etc.), see Application Configuration and subsequent sections.

Configuration File Purpose

The testbench.yaml file serves as the central configuration for the testbench environment. It is loaded once per test run by the Bootstrapper class during the one-time initialization phase. The configuration controls:

• Which service providers are registered in the test application
• Environment variables written to the generated .env file
• Workbench feature discovery settings (routes, commands)
• Files and directories to purge after test execution

Sources: testbench.yaml1-20 src/Bootstrapper.php80-96

Configuration File Structure

The testbench.yaml file contains four top-level sections, each serving a distinct purpose in the test environment configuration:

Sources: testbench.yaml1-20 src/Bootstrapper.php21-145

Providers Section

The providers section specifies an array of fully-qualified service provider class names to register in the test application. These providers supplement the default Hyperf and Hypervel providers managed by ConfigProviderRegister.

Configuration Format

Processing Flow

The providers are embedded in a generated composer.lock file at src/Bootstrapper.php56-78 which the Hypervel framework reads during application initialization. This allows testbench to simulate package provider registration without modifying actual composer files.

Provider Registration Details

Configuration Key	Type	Purpose	Default
providers	array<string>	Service provider class names	[]

The specified providers are added to the extra.hypervel.providers array in the generated composer.lock at src/Bootstrapper.php65 This follows the Hypervel package discovery convention.

Sources: testbench.yaml1-2 src/Bootstrapper.php56-78

Environment Variables Section

The env section defines environment variables that are written to a .env file in the workbench base path. Each entry is a string in KEY=VALUE format.

Configuration Format

Environment File Generation

The .env file is generated by src/Bootstrapper.php98-108 using the following process:

1. Extract the env array from the loaded configuration
2. Join array entries with PHP_EOL line separator
3. Write content to BASE_PATH/.env using Filesystem::replace()

Environment Variable Rules

Aspect	Behavior
Format	Each entry must be a complete KEY=VALUE string
Quoting	Values with spaces should be quoted (e.g., "Hypervel Testbench")
File Location	Written to {BASE_PATH}/.env
Regeneration	Regenerated on every test run during bootstrap
Cleanup	Automatically purged after tests if listed in purge.files

Sources: testbench.yaml4-5 src/Bootstrapper.php98-108

Workbench Discovery Section

The workbench section controls feature discovery and base path configuration for the workbench environment. It contains two sub-sections: discovers and an optional hypervel path override.

Discovery Configuration Format

Discovery Features

The discovers object controls automatic registration of workbench features:

Feature	Type	Purpose	Default in testbench.yaml
web	boolean	Auto-register routes from routes/web.php	false
api	boolean	Auto-register routes from routes/api.php	false
commands	boolean	Auto-register console commands	false

These discovery settings prevent the testbench from automatically loading workbench routes and commands during testing, allowing test classes to explicitly define only the routes they need via the HandlesRoutes trait (see HandlesRoutes Trait).

Base Path Configuration

The base path resolution occurs at src/Bootstrapper.php27-32:

1. Determine $workingPath from TESTBENCH_WORKING_PATH constant or package root
2. Check if config['hypervel'] is set in the YAML
3. Use custom path if specified, otherwise default to {$workingPath}/workbench
4. Define BASE_PATH constant with the resolved path

Sources: testbench.yaml7-11 src/Bootstrapper.php27-32

Purge Rules Section

The purge section defines files and directories to automatically delete after test execution completes. This cleanup ensures the testbench environment remains stateless between test runs.

Purge Configuration Format

Cleanup Mechanism

The purge mechanism is registered at src/Bootstrapper.php119-145 using PHP's register_shutdown_function. When the test process terminates:

1. The shutdown function iterates over purge.files array
2. For each file, checks if BASE_PATH/{file} exists
3. Deletes the file using Filesystem::delete()
4. Then iterates over purge.directories array
5. For each directory, checks if BASE_PATH/{directory} exists
6. Deletes the directory recursively using Filesystem::deleteDirectory()

Purge Configuration Options

Section	Type	Purpose	Path Resolution
files	array<string>	Individual file paths to delete	Relative to BASE_PATH
directories	array<string>	Directory paths to recursively delete	Relative to BASE_PATH

Common Purge Targets

Sources: testbench.yaml13-19 src/Bootstrapper.php119-145

File Location and Loading

The Bootstrapper uses a flexible file location strategy to find the configuration file, checking multiple possible filenames and locations.

File Search Strategy

The loading logic at src/Bootstrapper.php80-96 follows this algorithm:

1. Create a LazyCollection with three filename candidates:

   • testbench.yaml
   • testbench.yaml.example
   • testbench.yaml.dist

2. Map each candidate to full path using join_paths($workingPath, $file)

3. Filter to only files that exist via is_file($file)

4. Select the first existing file

5. If found, parse using Symfony\Component\Yaml\Yaml::parseFile()

6. If not found, configuration remains empty

File Location Behavior

Configuration File	Priority	Use Case
testbench.yaml	1st	Primary configuration file
testbench.yaml.example	2nd	Example/template for package developers
testbench.yaml.dist	3rd	Distributed template for package consumers

This fallback mechanism allows packages to ship with example configurations that users can copy and customize.

Sources: src/Bootstrapper.php80-96

Configuration Access

The loaded configuration is stored in a static property and accessible via the Bootstrapper::getConfig() method at src/Bootstrapper.php42-45 This allows other components to access configuration values during test execution.

Configuration Array Structure

Sources: src/Bootstrapper.php17 src/Bootstrapper.php42-45

Complete Configuration Example

Below is a comprehensive example demonstrating all available configuration options:

Sources: testbench.yaml1-20

Bootstrap Integration

The following diagram illustrates how testbench.yaml configuration integrates with the bootstrap process:

The bootstrap sequence at src/Bootstrapper.php21-40 executes in this order:

1. Load Configuration: Parse testbench.yaml and store in static property
2. Resolve Base Path: Determine workbench base path from workbench.hypervel or default
3. Define Constants: Set BASE_PATH and SWOOLE_HOOK_FLAGS
4. Generate Environment: Create .env file from env array
5. Generate Composer Lock: Create composer.lock with providers configuration
6. Register Purge Handler: Set up shutdown function for cleanup
7. Initialize ClassLoader: Configure class loading with TestScanHandler

Sources: src/Bootstrapper.php21-40