Installation and Setup

Purpose and Scope

This document guides you through installing the Hypervel Testbench package and configuring your testing environment. It covers package installation via Composer, running the testbench-sync utility to set up the workbench environment, and understanding the resulting directory structure and configuration files.

For information about writing tests using the testbench infrastructure, see Quick Start Guide. For details about the testbench.yaml configuration options, see Testbench Configuration.

Prerequisites

The Hypervel Testbench package requires the following dependencies:

Dependency	Version Constraint	Purpose
PHP	^8.2	Runtime environment
hypervel/framework	^0.3	Application framework layer
phpunit/phpunit	^10.0.7	Testing framework
mockery/mockery	^1.6.10	Mocking library
symfony/yaml	^7.3	YAML configuration parser
vlucas/phpdotenv	^5.6.1	Environment variable loading

The hypervel/framework dependency transitively includes the Hyperf framework components needed for infrastructure services.

Sources: composer.json22-29

Package Installation

Installation Workflow

Sources: composer.json30-35 composer.json44-46

Install via Composer

Install the testbench package as a development dependency in your project:

This installs the package and registers two PSR-4 autoload namespaces:

• Hypervel\Testbench\ maps to the src/ directory containing core testbench classes
• Workbench\App\ maps to the workbench/app/ directory containing workbench template files

The installation also registers the testbench-sync binary script, making it available via:

Or as a Composer script:

Sources: composer.json30-35 composer.json44-49

Environment Synchronization

Running testbench-sync

The testbench-sync utility copies the workbench template files from the installed package into your project directory. This creates a working test environment with example application structure, configuration files, and test fixtures.

Basic Usage:

By default, this creates a testbench/ directory in your project root.

Custom Directory:

This creates the workbench in a directory named my-workbench instead.

Sources: bin/testbench-sync11-12 composer.json47-48

File Synchronization Process

Sources: bin/testbench-sync8-9 bin/testbench-sync15-23 bin/testbench-sync25-37

The synchronization process performs two main operations:

1. Copy testbench.yaml to project root

   • Source: vendor/hypervel/testbench/testbench.yaml
   • Destination: ./testbench.yaml

2. Copy workbench directories to target directory

   • app/ - Application classes (controllers, models, providers, commands)
   • config/ - Configuration files for all services
   • database/ - Migrations and model factories
   • lang/ - Localization files
   • routes/ - Route definitions (web, API, console)
   • resources/ - View templates

Sources: bin/testbench-sync8-9 bin/testbench-sync15-23 bin/testbench-sync25-37

Implementation Details

The testbench-sync script implements file copying using the following logic:

Sources: bin/testbench-sync1-40

The script:

1. Resolves the current working directory as the project root
2. Loads dependencies via vendor/autoload.php
3. Uses Hypervel\Filesystem\Filesystem for file operations
4. Accepts an optional first argument specifying the target directory name (defaults to testbench)
5. Recursively copies all files from source directories to target, preserving directory structure
6. Uses ensureDirectoryExists() to create parent directories as needed

Sources: bin/testbench-sync4-6 bin/testbench-sync11-23

Post-Installation Directory Structure

After running testbench-sync, your project will have the following structure:

Sources: bin/testbench-sync15-37

Key Directories

Directory	Purpose	Key Files
testbench/app/	Application classes	Providers/WorkbenchServiceProvider.php, Models/User.php, Console/Commands/DummyCommand.php
testbench/config/	Service configuration	app.php, database.php, auth.php, session.php, cors.php, queue.php, logging.php
testbench/database/	Database schema and factories	migrations/*.php, factories/UserFactory.php
testbench/routes/	Route definitions	web.php, api.php, console.php
testbench/resources/	View templates	views/welcome.blade.php
testbench/lang/	Localization files	en/validation.php, en/pagination.php

Sources: bin/testbench-sync16-37

Runtime Artifacts

The workbench directory will generate additional files and directories during test execution. These should not be committed to version control:

Path	Type	Generated By	Purpose
testbench/.env	File	Bootstrapper	Environment configuration
testbench/composer.lock	File	Composer (if used)	Dependency lock file
testbench/runtime/	Directory	Hyperf runtime	Logs, cache, compiled files
testbench/public/vendor/	Directory	Asset publishing	Published vendor assets

These paths are automatically cleaned up by the testbench purge system after tests complete.

Sources: testbench.yaml13-19 .gitignore1-3

Configuration File

testbench.yaml Structure

The testbench.yaml file in your project root configures the test environment. This file is copied from the package during synchronization and can be customized for your project needs.

Sources: testbench.yaml1-20

Configuration Sections

The default testbench.yaml contains four main sections:

1. Providers Section

Lists additional service providers to register beyond the 45+ framework providers. The WorkbenchServiceProvider registers routes, commands, and other workbench-specific services.

2. Environment Section

Defines environment variables to include in the generated .env file. These override defaults from configuration files.

3. Workbench Discovery Section

Controls automatic discovery of routes and commands. When set to false, these features must be manually registered in service providers. This is useful for testing environments where you want explicit control over loaded components.

4. Purge Section

Specifies files and directories to delete after test execution. This ensures a clean state for subsequent test runs and prevents test artifacts from accumulating.

Sources: testbench.yaml1-20

For detailed configuration options, see Testbench Configuration.

Verification

After installation and synchronization, verify your setup:

1. Check Directory Structure

Ensure the workbench directory exists with expected subdirectories:

2. Verify testbench.yaml

Confirm the configuration file exists in project root:

3. Check PSR-4 Autoloading

The following namespaces should be registered:

• Hypervel\Testbench\ - Core testbench classes (from vendor)
• Workbench\App\ - Your workbench application classes

Verify in composer.json or by running:

Sources: composer.json30-35

4. Inspect Workbench Service Provider

The WorkbenchServiceProvider should exist at:

testbench/app/Providers/WorkbenchServiceProvider.php

This provider is automatically registered via the providers section in testbench.yaml.

Sources: testbench.yaml1-2

Next Steps

After completing installation and setup:

1. Write Your First Test - See Quick Start Guide for a hands-on tutorial creating basic tests

2. Understand Core Components - Review Core Testing Infrastructure to learn about TestCase, Bootstrapper, and ConfigProviderRegister

3. Configure Services - Explore Configuration Management to customize database, authentication, session, and other service settings

4. Use Test Data - Learn about Database and Model Testing for migrations, factories, and model configuration

5. Customize Workbench - See Workbench Environment to understand service providers, routes, commands, and views

The testbench environment is now ready for writing and executing tests against the Hypervel framework.

Sources: composer.json1-51 testbench.yaml1-20 bin/testbench-sync1-40