Workbench Environment

Purpose and Scope

The workbench environment is a self-contained sample application that serves as both a reference implementation and a testing substrate for the Hypervel Testbench itself. This page provides an overview of the workbench's structure, configuration, and discovery mechanisms. For detailed information about specific workbench components, see:

• Workbench structure and service provider details: 8.1
• Models and authentication examples: 8.2
• HTTP routes and controllers: 8.3
• Console commands: 8.4
• Exception handling and views: 8.5

For information about configuring the workbench via testbench.yaml, see Configuration Management and specifically Testbench Configuration.

What is the Workbench Environment

The workbench environment is a complete Laravel-like application structure located in the workbench/ directory. It contains all standard application components: models, controllers, migrations, factories, views, routes, and configuration files. This environment serves two primary functions:

1. Self-Testing: The testbench uses the workbench to test its own functionality, ensuring that the testing framework itself works correctly
2. Reference Implementation: Developers can examine the workbench to understand how to structure their own package tests

Unlike a typical Laravel application, the workbench is not meant to be deployed or run independently. It exists solely within the testing context, bootstrapped by the TestCase class during test execution.

Sources: Architecture overview from high-level diagrams

Workbench Directory Structure

The workbench follows a standard Laravel-style directory structure:

Directory Breakdown:

Directory	Purpose	Key Files
app/	Application logic	Models, Controllers, Providers, Exception Handlers
config/	Configuration files	app.php, database.php, session.php, cors.php, auth.php
database/	Database artifacts	Migrations, Factories, Seeders
routes/	Route definitions	web.php, api.php, console.php
resources/	Views and localization	Blade templates, language files
public/	Public assets	Static files (empty in workbench)
storage/	Runtime storage	Logs, cache (managed by testbench)

Sources: testbench.yaml1-20 Architecture overview from high-level diagrams

Configuration via testbench.yaml

The workbench environment is configured through the testbench.yaml file at the repository root. This configuration file controls provider registration, environment variables, discovery behavior, and cleanup rules.

Configuration Structure

Configuration Sections:

Section	Purpose	Values in Workbench
providers	Service providers to register	WorkbenchServiceProvider
env	Environment variables to set	APP_NAME="Hypervel Testbench"
workbench.discovers	Controls route/command auto-discovery	All disabled by default (false)
purge.files	Files to clean up after tests	.env, composer.lock
purge.directories	Directories to clean up after tests	runtime, public/vendor

The workbench.discovers section is particularly important: it controls whether the WorkbenchServiceProvider automatically loads route files and console commands. By default, all discovery is disabled to prevent interference with individual test cases that may define their own routes via the HandlesRoutes trait (see 4.1).

Sources: testbench.yaml1-20

Discovery Mechanism and WorkbenchServiceProvider

The WorkbenchServiceProvider implements a conditional discovery system that respects the testbench.yaml configuration:

WorkbenchServiceProvider Implementation

The provider reads configuration and conditionally loads resources:

Web Route Discovery workbench/app/Providers/WorkbenchServiceProvider.php17-20:

• Checks $config['web'] ?? false
• If enabled, registers workbench/routes/web.php with RouteFileCollector

API Route Discovery workbench/app/Providers/WorkbenchServiceProvider.php22-25:

• Checks $config['api'] ?? false
• If enabled, registers workbench/routes/api.php with RouteFileCollector

Console Command Discovery workbench/app/Providers/WorkbenchServiceProvider.php27-29:

• Checks $config['commands'] ?? false
• If enabled, requires workbench/routes/console.php

This design allows tests to selectively enable workbench routes when needed while preventing unintended route registration in most test scenarios.

Sources: workbench/app/Providers/WorkbenchServiceProvider.php1-32 testbench.yaml7-11

Workbench Configuration Retrieval

The Bootstrapper::getConfig() method provides access to the parsed testbench.yaml configuration:

The configuration is loaded once during the bootstrap phase and cached statically, allowing service providers and other components to access it via Bootstrapper::getConfig() without repeatedly parsing the YAML file.

Sources: workbench/app/Providers/WorkbenchServiceProvider.php15

Integration with TestCase

The workbench integrates with the testbench's core TestCase class through several mechanisms:

Provider Registration testbench.yaml2:

• WorkbenchServiceProvider is registered in the providers section
• The Bootstrapper reads this configuration and ensures the provider is registered during application creation

Environment Setup testbench.yaml5:

• Environment variables defined in the env section are written to .env
• The workbench application name is set to "Hypervel Testbench"

Database Integration:

• Workbench migrations (e.g., create_users_table) can be loaded via defineDatabaseMigrations() in tests (see 7.1)
• The HandlesDatabases trait manages migration lifecycle for workbench schema

Route Testing:

• Tests can enable workbench route discovery by modifying the configuration
• Alternatively, tests define routes directly using the HandlesRoutes trait (see 4.1)

Sources: testbench.yaml1-20 Architecture overview from high-level diagrams

Self-Testing Capability

The workbench environment enables the testbench to test itself through a complete, functional application:

Available Test Scenarios:

Component	Workbench Provides	Testbench Tests
Models	Workbench\App\Models\User	ORM functionality, relationships, factories
Migrations	create_users_table	Migration execution, rollback, schema building
Factories	UserFactory	Faker integration, model instantiation
Controllers	ExampleController	HTTP request handling, routing
Views	welcome.blade.php	Blade rendering, localization
Commands	DummyCommand	Console command execution, argument parsing
Authentication	Auth guards, providers	Authentication flow, session management
Exception Handling	Custom Handler	Exception catching, response formatting

This self-testing approach ensures that:

1. The testbench correctly bootstraps a Hypervel application
2. All trait functionality (HandlesRoutes, HandlesDatabases, etc.) works as expected
3. Configuration providers are properly registered
4. Database and migration features function correctly
5. HTTP testing utilities work with real controllers and routes

Sources: Architecture overview from high-level diagrams

File Synchronization with testbench-sync

The bin/testbench-sync utility synchronizes workbench files from the vendor directory to the project root. This is useful when the testbench is installed as a package dependency and developers want to customize the workbench for their own testing needs.

For detailed information about file synchronization, see 5.2.

Sources: Architecture overview from high-level diagrams, testbench.yaml13-19

Purge Configuration

The purge section in testbench.yaml defines cleanup rules for temporary files and directories created during test execution:

Files to Purge testbench.yaml14-16:

• .env: Generated environment file
• composer.lock: Dependency lock file

Directories to Purge testbench.yaml17-19:

• runtime: Hyperf runtime cache, logs, and temporary files
• public/vendor: Compiled vendor assets

These cleanup rules ensure that each test run starts with a clean slate, preventing state pollution between test executions.

Sources: testbench.yaml13-19

Relationship to Test Execution

The workbench is bootstrapped as part of the standard test lifecycle:

The workbench is fully integrated into the test lifecycle, with its components available throughout test execution. Individual tests can override or extend workbench behavior using the extension points provided by TestCase (see 2).

Sources: Architecture overview from high-level diagrams, workbench/app/Providers/WorkbenchServiceProvider.php1-32 testbench.yaml1-20

Extending the Workbench

While the default workbench provides a complete reference implementation, developers can extend it for their own testing needs:

Adding New Components:

1. Create new models, controllers, or commands in workbench/app/
2. Add corresponding routes to workbench/routes/
3. Create migrations in workbench/database/migrations/
4. Enable discovery in testbench.yaml if needed

Customizing Configuration:

1. Modify files in workbench/config/ to adjust application settings
2. Add environment variables to testbench.yaml env section
3. Register additional providers in testbench.yaml providers section

Overriding in Tests:

• Use defineEnvironment() to modify configuration per-test (see 2.4)
• Use getPackageProviders() to add test-specific providers (see 4.2)
• Use defineRoutes() to define test-specific routes (see 4.1)

Sources: Architecture overview from high-level diagrams

Summary

The workbench environment is a critical component of the Hypervel Testbench, providing:

• A self-contained reference application for testing
• Conditional discovery of routes and commands via WorkbenchServiceProvider
• Configuration through testbench.yaml
• Integration with the test lifecycle and cleanup mechanisms
• Examples of models, migrations, controllers, and other Laravel-like components

For detailed exploration of specific workbench components, see the child pages under this section (8.1 through 8.5).

Sources: testbench.yaml1-20 workbench/app/Providers/WorkbenchServiceProvider.php1-32 Architecture overview from high-level diagrams