Workbench Structure and Discovery

Purpose and Scope

This page documents the workbench/ directory structure and the automatic discovery mechanism that controls how workbench routes and commands are loaded into the test environment. The workbench serves as a self-contained sample application used for testing the testbench itself and providing reference implementations for package developers.

For information about using workbench models and authentication, see Models and Authentication. For HTTP routes and controllers, see HTTP Routes and Controllers. For console commands, see Console Commands and Routes. For configuration files within the workbench, see Application Configuration and related configuration pages.

Workbench Directory Structure

The workbench/ directory contains a complete Laravel-style application structure that mirrors what package developers typically create. This structure provides a testing ground for the testbench framework itself and serves as a reference implementation.

Workbench Directory Layout

Directory/File	Purpose
app/Models/	Eloquent models (e.g., User)
app/Http/Controllers/	HTTP controllers for testing routing
app/Providers/	Service providers, including WorkbenchServiceProvider
app/Exceptions/	Custom exception handlers
config/	Application configuration files
database/migrations/	Database migration files
database/factories/	Model factories for test data generation
routes/web.php	Web routes with middleware
routes/api.php	API routes
routes/console.php	Console command definitions
resources/views/	Blade view templates
resources/lang/	Language localization files

Sources: testbench.yaml1-20 workbench/app/Providers/WorkbenchServiceProvider.php1-31

WorkbenchServiceProvider

The WorkbenchServiceProvider is the central service provider for the workbench environment. It is registered in testbench.yaml and handles conditional discovery of routes and console commands based on configuration settings.

The WorkbenchServiceProvider class is located at workbench/app/Providers/WorkbenchServiceProvider.php11-31 and implements the following logic:

1. Configuration Retrieval: Reads the workbench.discover configuration from Bootstrapper::getConfig() workbench/app/Providers/WorkbenchServiceProvider.php15
2. Conditional Web Routes: If web is enabled, adds routes/web.php to the RouteFileCollector workbench/app/Providers/WorkbenchServiceProvider.php17-20
3. Conditional API Routes: If api is enabled, adds routes/api.php to the RouteFileCollector workbench/app/Providers/WorkbenchServiceProvider.php22-25
4. Conditional Console Commands: If commands is enabled, requires routes/console.php workbench/app/Providers/WorkbenchServiceProvider.php27-29

Sources: workbench/app/Providers/WorkbenchServiceProvider.php1-31

Discovery Mechanism

The workbench discovery mechanism is controlled by the workbench.discovers section in testbench.yaml. This configuration determines which workbench resources are automatically loaded during test execution.

Discovery Configuration Options

The workbench.discovers section in testbench.yaml7-11 provides three boolean flags:

Flag	Default	Purpose
web	false	Controls loading of routes/web.php
api	false	Controls loading of routes/api.php
commands	false	Controls loading of routes/console.php

Default Configuration:

All discovery options are disabled by default, meaning the workbench routes and commands are not automatically loaded during tests. This provides clean test isolation where tests must explicitly define their routes using the HandlesRoutes trait (see HandlesRoutes Trait).

Sources: testbench.yaml7-11

Discovery Control Flow

The following diagram shows how discovery settings flow from configuration to actual route loading:

Sources: testbench.yaml7-11 workbench/app/Providers/WorkbenchServiceProvider.php14-30

Enabling Discovery

To enable automatic loading of workbench routes or commands, modify the testbench.yaml configuration:

Example: Enable Web Routes

When web: true is set, the WorkbenchServiceProvider::boot() method will execute:

This adds the web routes to the application's route collection, making them available for HTTP testing.

Example: Enable All Discovery

With all discovery enabled:

• routes/web.php routes are loaded
• routes/api.php routes are loaded
• routes/console.php commands are registered

Sources: testbench.yaml7-11 workbench/app/Providers/WorkbenchServiceProvider.php17-29

Route File Path Resolution

The WorkbenchServiceProvider uses path resolution relative to its own location to find route files:

This resolves to:

• WorkbenchServiceProvider.php is at workbench/app/Providers/
• dirname(__DIR__, 2) goes up two directories to workbench/
• Appends /routes/web.php resulting in workbench/routes/web.php

The same pattern applies for api.php workbench/app/Providers/WorkbenchServiceProvider.php24 and console.php workbench/app/Providers/WorkbenchServiceProvider.php28

Sources: workbench/app/Providers/WorkbenchServiceProvider.php19-29

Integration with Test Lifecycle

The workbench discovery mechanism integrates with the test lifecycle as follows:

Key Points:

1. Discovery Before Test Routes: Workbench discovery occurs during application boot, before test-specific route definitions
2. Additive Behavior: Discovered routes are added to the route collection; they don't replace test-defined routes
3. Per-Test Isolation: Each test gets a fresh application boot, so discovery happens per test
4. Configuration Caching: The testbench.yaml configuration is loaded once by Bootstrapper and cached statically

Sources: workbench/app/Providers/WorkbenchServiceProvider.php14-30

Discovery vs Manual Route Definition

Tests have two options for route availability:

Option 1: Discovery (Automatic)

Enable discovery in testbench.yaml:

Result: All routes in workbench/routes/web.php are automatically available in tests.

Option 2: Manual Definition

Use the HandlesRoutes trait (see HandlesRoutes Trait):

Result: Only explicitly defined routes are available in that specific test.

Recommendation: For most package testing scenarios, keep discovery disabled (false) and use manual route definition. This provides better test isolation and makes test intentions explicit. Enable discovery only when testing the workbench environment itself or when multiple tests need identical route sets.

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

Provider Registration

The WorkbenchServiceProvider itself must be registered in testbench.yaml to function:

This registration at testbench.yaml1-2 ensures the provider is loaded during application bootstrapping. The Bootstrapper reads this configuration and registers all listed providers with the application container.

Without this registration, the discovery mechanism would not function, as the WorkbenchServiceProvider::boot() method would never be called.

Sources: testbench.yaml1-2 workbench/app/Providers/WorkbenchServiceProvider.php1-31