Testing with Orchestra Testbench

This page covers the test infrastructure used to develop and verify this package: the Testbench configuration file, the workbench directory layout, and the TestCase base class that bootstraps the package for all feature tests.

For information about the individual test files and what each covers, see Writing Feature Tests. For architectural constraints enforced via Pest, see Architecture Tests. For environment-specific behavior of CopilotCli when TESTBENCH_CORE is defined at runtime, see Environment Detection and Adaptation.

---

Role of Orchestra Testbench

Because this is a Laravel package (not a full application), there is no bootstrap/app.php or full Laravel project to run tests against. Orchestra Testbench provides a minimal Laravel application host so the package's service provider, facades, and Artisan commands can be exercised in isolation.

The two key artefacts that wire everything together are:

File	Purpose
testbench.yaml	Declares the Laravel version, providers, migrations, seeders, and build steps
tests/TestCase.php	Base PHPUnit class that extends Orchestra\Testbench\TestCase and registers the package provider

---

testbench.yaml Configuration

testbench.yaml1-34

The file is read by vendor/bin/testbench at startup. Each section controls a distinct aspect of the synthetic Laravel environment.

Laravel version pin

@testbench resolves to the Laravel version bundled with the installed orchestra/testbench release. This avoids hard-coding a version number in the config.

Database and migrations

Migrations are loaded from workbench/database/migrations/. The seeder entry point is Workbench\Database\Seeders\DatabaseSeeder. Both are part of the workbench/ directory tree described below.

Build steps

These steps execute in order during vendor/bin/testbench workbench:build (or when install: true triggers them automatically on boost:install):

Step	Effect
asset-publish	Publishes assets declared in assets:
create-sqlite-db	Creates the SQLite database file referenced by DB_DATABASE
db-wipe	Drops all tables to ensure a clean state
migrate-fresh	Runs all migrations against the blank database

Discover flags

These flags tell Testbench which workbench sub-directories to scan and auto-load:

Flag	Resolved path
web: true	workbench/routes/web.php
api: true	workbench/routes/api.php
commands: true	Artisan commands under workbench/
factories: true	workbench/database/factories/
components: false	Blade components — not used
views: false	Blade views — not used

Storage sync

Bi-directional sync keeps the application's storage/ and workbench/storage/ directories consistent during local development runs.

Sources: testbench.yaml1-34

---

Workbench Directory Structure

The workbench/ directory provides the fixture-level application context that Testbench uses. Its layout mirrors a conventional Laravel application subdirectory:

Diagram: Workbench directory tree mapped to Testbench discovery flags

Sources: testbench.yaml1-34

---

tests/TestCase.php — Package Bootstrap

tests/TestCase.php1-21

All feature tests extend Tests\TestCase, which itself extends Orchestra\Testbench\TestCase. Two methods configure the bootstrapped application:

getPackageProviders()

This tells Testbench to register CopilotCliServiceProvider when the synthetic Laravel app boots. Without this, Boost::registerAgent() is never called and the CopilotCli agent is unavailable during tests.

defineEnvironment()

Sets APP_ENV to testing inside the container, ensuring any environment-sensitive code behaves consistently.

Diagram: Bootstrap chain from Pest to the package

Sources: tests/TestCase.php1-21 tests/Pest.php1-19

---

tests/Pest.php — Global Test Configuration

tests/Pest.php1-19

This file applies two global settings that affect every test in the suite.

Test case binding

All files inside tests/Feature/ automatically inherit Tests\TestCase as their PHPUnit test case, including the Testbench bootstrapping described above. There is no per-test uses() declaration required.

Arch presets

These enable Pest's built-in PHP and security architectural rule sets globally. The security preset is applied with assert ignored because Pest itself uses assert internally. These interact with the explicit arch() calls in tests/ArchTest.php; see Architecture Tests for details.

Sources: tests/Pest.php1-19

---

SQLite Database Setup

The create-sqlite-db build step creates a file-based SQLite database. Because testbench.yaml does not declare a DB_DATABASE path explicitly, Testbench defaults to creating testbench.sqlite in the package root (or the path declared in workbench/.env if present). The subsequent db-wipe + migrate-fresh steps ensure a clean schema for every full rebuild.

During a normal test run (without invoking workbench:build manually), the database file from the last build is reused. Individual tests should use Laravel's RefreshDatabase trait or database transactions if they need isolation.

---

Environment Detection During Tests

When tests run under vendor/bin/testbench, the constant TESTBENCH_CORE is defined by the Testbench core library. This constant propagates into two important places:

1. CopilotCli::convertCommandToPhpPath() — causes the MCP server command to resolve to ./vendor/bin/testbench with args ['boost:mcp'] rather than php artisan boost:mcp. See CopilotCli Agent Class.

2. .ai/guidelines/copilot-cli.blade.php — the @if(defined('TESTBENCH_CORE')) block renders an additional warning that not all MCP tools are available in a package development context. See Guidelines and Instructions.

Diagram: TESTBENCH_CORE constant influence paths

Sources: .ai/guidelines/copilot-cli.blade.php11-21 .github/copilot-instructions.md74-90

---

Summary

Configuration point	File	Key setting
Testbench environment config	testbench.yaml	laravel: '@testbench', SQLite build steps, discover flags
Package provider registration	tests/TestCase.php	getPackageProviders returns [CopilotCliServiceProvider::class]
Feature test binding	tests/Pest.php	uses(Tests\TestCase::class)->in('Feature')
Global arch presets	tests/Pest.php	arch()->preset()->php(), arch()->preset()->security()
Workbench DB	workbench/database/migrations/	Migrations run via migrate-fresh build step