Testing Framework and Strategy

Purpose and Scope

This document details the testing framework, test suite organization, and testing strategies used in the laravel-boost-phpstorm-copilot package. It covers the Pest PHP testing framework, Orchestra Testbench integration, feature test coverage, architecture tests, and test execution procedures.

For code quality standards and linting configuration, see Code Style and Quality Standards. For CI/CD automation of tests, see CI/CD Pipeline.

---

Testing Stack Overview

The package uses a modern PHP testing stack built on Pest PHP with Orchestra Testbench for Laravel environment simulation.

Core Testing Dependencies

Package	Version	Purpose
pestphp/pest	^4.0	Primary testing framework providing expressive syntax
pestphp/pest-plugin-laravel	^4.0	Laravel-specific Pest assertions and utilities
phpunit/phpunit	^12.0	Underlying test runner used by Pest
orchestra/testbench	^10.0	Lightweight Laravel environment for testing packages
mockery/mockery	^1.6	Mocking framework for dependencies

Test Stack Architecture

Sources: composer.json tests/Pest.php1-20 tests/TestCase.php1-22

---

Test Suite Organization

The test suite is organized into two primary categories: feature tests and architecture tests, configured through PHPUnit XML and Pest configuration files.

Directory Structure

tests/
├── ArchTest.php # Architecture constraint tests
├── Feature/ # Feature test suite
│ ├── PhpStormCopilotTest.php
│ └── PhpStormCopilotServiceProviderTest.php
├── Pest.php # Pest configuration
└── TestCase.php # Base test case class

PHPUnit Configuration

The phpunit.xml file defines the test suite structure and environment settings:

• Test Suites: Single Feature suite containing all feature tests phpunit.xml7-11
• Bootstrap: Uses vendor/autoload.php for class autoloading phpunit.xml4
• Environment: Sets APP_ENV=testing and provides a test APP_KEY phpunit.xml12-15
• Coverage Source: Includes src/ directory for code coverage analysis phpunit.xml16-20

Pest Configuration

The tests/Pest.php file configures Pest-specific behavior:

• Test Case Binding: Binds all tests in Feature/ to Tests\TestCase tests/Pest.php16
• Architecture Presets: Applies php() and security() presets (ignoring assert) tests/Pest.php18-19

Test Suite Mapping

Sources: phpunit.xml1-22 tests/Pest.php1-20 tests/TestCase.php1-22

---

Feature Test Coverage

Feature tests validate the core functionality of the PhpStormCopilot agent and PhpStormCopilotServiceProvider.

PhpStormCopilot Agent Tests

The tests/Feature/PhpStormCopilotTest.php file contains 18 test cases covering agent behavior across multiple scenarios.

Basic Configuration Tests

Test	Purpose	Lines
PhpStormCopilot returns correct name	Validates name() returns 'phpstorm-copilot'	8-13
PhpStormCopilot returns correct display name	Validates displayName() returns full name	15-20
PhpStormCopilot returns correct MCP config key	Validates mcpConfigKey() returns 'servers'	22-27

Platform Detection Tests

Test	Purpose	Lines
system detection config has paths for Darwin	Validates macOS plugin detection paths	29-37
system detection config has paths for Windows	Validates Windows plugin detection paths	39-47
project detection config checks for copilot-instructions.md	Validates project file detection	49-57

Path Resolution Tests

Test	Purpose	Lines
returns absolute PHP_BINARY path	Validates getPhpPath() returns PHP_BINARY	59-64
returns absolute artisan path	Validates getArtisanPath() returns absolute path ending with 'artisan'	66-75
paths remain absolute regardless of forceAbsolutePath parameter	Validates absolute path behavior is consistent	77-90

WSL Command Transformation Tests

Nine tests validate the transformMcpCommandForWsl() method across different command scenarios:

Test Scenario	Expected Behavior	Lines
Sail with relative path (./vendor/bin/sail)	Wraps with wsl.exe --cd {base_path()}	92-109
Sail with absolute path	Normalizes to relative Sail path	111-128
Sail with Windows-style path	Converts to relative Sail path	130-147
WSL without Sail (pre-wrapped wsl.exe)	Passes through without modification	149-164
Direct PHP path (absolute)	Wraps with wsl.exe --cd {base_path()}	166-183
Relative PHP path (php)	Wraps with wsl.exe --cd {base_path()}	185-202

PhpStormCopilot Test Coverage Map

Sources: tests/Feature/PhpStormCopilotTest.php1-203

Service Provider Registration Tests

The tests/Feature/PhpStormCopilotServiceProviderTest.php file validates Laravel Boost framework integration.

Agent Registration Test

This test verifies:

1. The service provider successfully registers the agent with Laravel Boost
2. The agent is accessible via the key 'phpstorm-copilot'
3. The registered class is PhpStormCopilot::class

Sources: tests/Feature/PhpStormCopilotServiceProviderTest.php1-14

Test Case Base Class

The Tests\TestCase class extends Orchestra\Testbench\TestCase and provides package-specific configuration:

Key responsibilities:

• Sets app['env'] to 'testing' tests/TestCase.php12-15
• Registers PhpStormCopilotServiceProvider for all tests tests/TestCase.php17-20
• Provides Laravel application instance without full framework overhead

Sources: tests/TestCase.php1-22

---

Architecture Tests

Architecture tests enforce code quality constraints across the entire codebase using Pest's architecture testing capabilities.

Defined Architecture Rules

The tests/ArchTest.php file defines three critical architecture constraints:

1. Strict Types Declaration

Enforces that all files in the Revolution\Laravel\Boost namespace declare strict_types=1 at the top of the file. This ensures type safety and prevents implicit type coercion.

Lines: tests/ArchTest.php5-7

2. No Debugging Functions

Prohibits the use of debugging functions (dd(), dump(), var_dump(), print_r(), die()) anywhere in the codebase, preventing accidental commits of debugging code.

Lines: tests/ArchTest.php9-11

3. Avoid Final Classes

Ensures classes in the Revolution\Laravel\Boost namespace are not marked as final, allowing package users to extend the package's classes if needed.

Lines: tests/ArchTest.php13-16

Architecture Test Enforcement Flow

Sources: tests/ArchTest.php1-17 tests/Pest.php18-19

Architecture Presets

In addition to custom architecture rules, Pest presets are applied in tests/Pest.php:

• PHP Preset (arch()->preset()->php()): Enforces standard PHP best practices tests/Pest.php18
• Security Preset (arch()->preset()->security()->ignoring('assert')): Enforces security constraints, ignoring assert() function tests/Pest.php19

Sources: tests/Pest.php1-20

---

Running Tests

Command-Line Execution

Tests can be executed using Composer scripts or vendor binaries.

Run All Tests

This executes the complete test suite including feature tests and architecture tests.

Run Specific Test Suites

Run Individual Tests

Test Execution Options

Option	Purpose	Example
--filter	Run tests matching pattern	vendor/bin/pest --filter="WSL"
--coverage	Generate coverage report	vendor/bin/pest --coverage
--bail	Stop on first failure	vendor/bin/pest --bail
--parallel	Run tests in parallel	vendor/bin/pest --parallel

Test Execution Flow

Sources: composer.json phpunit.xml1-22 tests/Pest.php1-20

---

Test Coverage Strategy

Coverage Scope

Code coverage analysis is configured to include the src/ directory phpunit.xml16-20

Current Test Coverage

The test suite provides comprehensive coverage across:

PhpStormCopilot Agent Class

• ✓ Basic configuration methods (name(), displayName(), mcpConfigKey())
• ✓ Platform detection configuration (systemDetectionConfig(), projectDetectionConfig())
• ✓ Path resolution (getPhpPath(), getArtisanPath())
• ✓ WSL command transformation (transformMcpCommandForWsl())
• ✓ Multiple Sail and WSL command scenarios

PhpStormCopilotServiceProvider

• ✓ Laravel Boost agent registration via Boost::registerAgent()

Architecture Constraints

• ✓ Strict types declaration enforcement
• ✓ Debug function prohibition
• ✓ Final class prohibition
• ✓ PHP and security preset rules

Coverage Gaps and Testing Philosophy

The package follows a pragmatic testing approach:

1. Feature tests focus on critical public API methods that define agent behavior
2. Architecture tests enforce code quality constraints
3. Integration testing relies on Orchestra Testbench for Laravel environment simulation
4. Mocking strategy isolates the PhpStormCopilot agent from DetectionStrategyFactory dependencies

Note: The WithWSL trait methods (isWSL(), installMcpViaWsl()) are tested indirectly through integration with the PhpStormCopilot agent, as they require actual WSL environment detection which is challenging to mock reliably in unit tests. These methods are validated through manual testing and CI/CD workflows (see CI/CD Pipeline).

Sources: tests/Feature/PhpStormCopilotTest.php1-203 tests/Feature/PhpStormCopilotServiceProviderTest.php1-14 tests/ArchTest.php1-17

---

Testing Best Practices

Test Structure

All feature tests follow a consistent structure:

1. Arrange: Mock dependencies (typically DetectionStrategyFactory)
2. Act: Instantiate PhpStormCopilot and call methods
3. Assert: Use Pest's fluent expect() syntax for validation

Example from tests/Feature/PhpStormCopilotTest.php8-13:

Mocking Strategy

The test suite uses Mockery for dependency isolation:

• DetectionStrategyFactory is mocked in all PhpStormCopilot tests to prevent actual environment detection
• This ensures tests are deterministic and do not depend on the actual execution environment

Test Naming Conventions

Test names follow a descriptive, sentence-like format:

• PhpStormCopilot returns correct name
• transformMcpCommandForWsl handles Sail with relative path
• PhpStormCopilotServiceProvider registers code environment

This provides self-documenting test descriptions that appear in test output.

Sources: tests/Feature/PhpStormCopilotTest.php1-203 tests/Feature/PhpStormCopilotServiceProviderTest.php1-14