Writing Tests

This document provides a comprehensive guide to writing tests for the laravel-boost-copilot-cli package. It covers test organization, Pest framework usage, mocking strategies, and testing patterns specific to this package. For information about setting up the testing environment with Orchestra Testbench, see Testing with Orchestra Testbench.

Test Organization

The package uses Pest 4 as its testing framework and organizes tests in the tests/Feature directory. All tests are feature tests that validate the package's behavior in a realistic Laravel environment.

Test Suite Structure

Sources: tests/Feature/CopilotCliTest.php1-136 tests/Feature/GuidelinesTest.php1-71 phpunit.xml1-22

File Organization

Test File	Purpose	Test Count
CopilotCliTest.php	Tests CopilotCli class methods, environment detection, path conversion, MCP configuration generation	14 tests
GuidelinesTest.php	Tests AI guidelines file existence, content structure, Blade rendering, environment-specific sections	6 tests

The package configuration specifies tests are located in tests/Feature with the APP_ENV set to testing and a predefined APP_KEY for encryption operations.

Sources: phpunit.xml7-11

Using Pest Framework

All tests use Pest 4 syntax with expectation-based assertions. The package follows the patterns outlined in the pest-testing skill.

Basic Test Structure

Tests use the test() function with descriptive names and expectation-based assertions:

Sources: tests/Feature/CopilotCliTest.php8-13

Expectation Syntax

The package uses Pest's fluent expectation API:

Pattern	Example	Purpose
toBe()	expect($value)->toBe('expected')	Exact equality comparison
toBeTrue() / toBeFalse()	expect($result)->toBeTrue()	Boolean assertions
toHaveKey()	expect($array)->toHaveKey('key')	Array key existence
toContain()	expect($array)->toContain('value')	Array/string content
toMatchArray()	expect($config)->toMatchArray([...])	Partial array matching
not->toContain()	expect($str)->not->toContain('text')	Negated assertions

Sources: tests/Feature/CopilotCliTest.php12-136 tests/Feature/GuidelinesTest.php9-71

Testing the CopilotCli Class

Mocking Strategy

Sources: tests/Feature/CopilotCliTest.php9-97

The DetectionStrategyFactory is always mocked because:

• Tests focus on CopilotCli behavior, not detection logic
• Prevents external dependencies from affecting test results
• Tests remain fast and isolated

Example mock setup:

Sources: tests/Feature/CopilotCliTest.php9-10

Testing Configuration Methods

Tests verify that configuration methods return the expected structure:

The toMatchArray() expectation allows partial matching, verifying required keys exist with correct values without requiring exact array equality.

Sources: tests/Feature/CopilotCliTest.php57-69

Testing Environment Detection

The package provides a CopilotCli::fake() static method for testing environment detection:

Sources: tests/Feature/CopilotCliTest.php99-107

The fake() method accepts parameters to simulate different environments:

Parameter	Default	Purpose
testbench	true	Simulates Orchestra Testbench environment
wsl	false	Simulates Windows Subsystem for Linux

Example testing WSL environment:

Sources: tests/Feature/CopilotCliTest.php72

Testing Path Conversion Logic

Sources: tests/Feature/CopilotCliTest.php71-119

Tests verify path conversion in different scenarios:

1. WSL Environment: Converts wsl commands to php
2. Testbench Environment: Converts any command to ./vendor/bin/testbench
3. Sail Environment: Normalizes sail paths to relative form
4. Other Commands: Passes through unchanged

Sources: tests/Feature/CopilotCliTest.php71-97

Testing Blade Templates

Guidelines Rendering Tests

Sources: tests/Feature/GuidelinesTest.php40-70

Testing File Existence

Sources: tests/Feature/GuidelinesTest.php9-13

Testing Content Structure

Tests verify specific sections exist in the guidelines:

Sources: tests/Feature/GuidelinesTest.php15-21

Testing Conditional Rendering

Two tests verify Blade compilation in different environments:

Without Testbench:

With Testbench:

Sources: tests/Feature/GuidelinesTest.php40-70

Test Execution Patterns

Individual Test Execution

Tests use descriptive names that map to specific functionality:

Test Name	Validates
CopilotCli returns correct name	name() returns 'copilot-cli'
CopilotCli returns correct display name	displayName() returns 'GitHub Copilot CLI'
CopilotCli returns correct MCP config path	mcpConfigPath() returns '.github/mcp-config.json'
CopilotCli system detection config uses "command -v" command	System detection configuration structure
CopilotCli project detection config checks for copilot-instructions.md	Project detection file list

Sources: tests/Feature/CopilotCliTest.php8-47

Running Tests

Run the entire feature suite:

Run specific test file:

Run specific test by name:

Sources: phpunit.xml7-11

Testing Best Practices

Type Declarations

All test functions include return type declarations:

Sources: tests/Feature/CopilotCliTest.php8-136 tests/Feature/GuidelinesTest.php9-71

Descriptive Test Names

Test names clearly describe what is being validated:

✅ Good: 'CopilotCli converts wsl command to php' ❌ Poor: 'test path conversion'

Sources: tests/Feature/CopilotCliTest.php71

Chaining Expectations

Use method chaining with and() for multiple assertions on the same value:

Sources: tests/Feature/CopilotCliTest.php35-36

Minimal Test Scope

Each test validates one specific behavior:

Sources: tests/Feature/CopilotCliTest.php49-55

Environment Cleanup

When modifying environment state, tests clean up after themselves:

Sources: tests/Feature/CopilotCliTest.php72-81

Writing New Tests

Test Template

Adding Tests for New Features

When adding new functionality to CopilotCli:

1. Add test in tests/Feature/CopilotCliTest.php
2. Use descriptive test name starting with 'CopilotCli'
3. Mock DetectionStrategyFactory unless testing detection logic
4. Use CopilotCli::fake() when testing environment-specific behavior
5. Chain multiple expectations when testing complex return values

When adding new guidelines sections:

1. Add test in tests/Feature/GuidelinesTest.php
2. Test raw file content with File::get()
3. Test rendered output with Blade::render()
4. Verify conditional sections with and without TESTBENCH_CORE

Sources: tests/Feature/CopilotCliTest.php1-136 tests/Feature/GuidelinesTest.php1-71