Getting Started

Minimal Steps to Begin

Install the Package: Add kylekatarnls/multi-tester as a dev dependency in your Laravel package:
```
composer require kylekatarnls/multi-tester --dev
```
Initialize Configuration: Create a .multi-tester.yml file in your project root and add a dependency to test (e.g., laravel/framework):
```
vendor/bin/multi-tester --add=laravel/framework
```
This generates a default config entry for the package.
Run Tests: Execute tests against the configured dependencies:
```
vendor/bin/multi-tester
```
Verify Output: Check the terminal for test results. Use -v or --verbose for detailed logs:
```
vendor/bin/multi-tester --verbose
```

First Use Case: Testing Against Laravel Core

Scenario: You’re developing a Laravel service provider (my-package/laravel-service) and want to ensure compatibility with Laravel 11.x before releasing.

Add Laravel as a Dependency:
```
vendor/bin/multi-tester --add=laravel/framework:11.*
```
This configures multi-tester to use the latest 11.x version of Laravel.
Customize Commands (Optional): Update .multi-tester.yml to use Laravel’s Travis CI commands:
```
laravel/framework:11.*:
  travis
```
Run Tests:
```
vendor/bin/multi-tester
```
This clones Laravel 11.x, replaces your package in its vendor/ directory with your local version, installs dependencies, and runs its tests.

Key Files to Know

.multi-tester.yml: Central configuration file listing dependencies and test commands.
vendor/bin/multi-tester: CLI entry point for running tests.
composer.json: Your package’s metadata (used to identify your package for replacement).

Implementation Patterns

Workflow: Daily Development Cycle

Develop Locally: Work on your Laravel package (e.g., my-package/laravel-auth) as usual.
Add/Update Dependencies: Use --add to include new dependencies or update versions in .multi-tester.yml:
```
vendor/bin/multi-tester --add=spatie/laravel-permission:2.*
```
Run Tests on Save: Integrate multi-tester into your IDE’s "Save Actions" or use a script to run it automatically:
```
# Add to package.json scripts (if using npm)
"scripts": {
  "test:multi": "php vendor/bin/multi-tester"
}
```
CI Integration: Add a multi-tester job to your GitHub Actions or Travis CI pipeline (see Travis section below).

Integration Tips for Laravel Packages

1. Handling Laravel-Specific Dependencies

Laravel Framework: Use laravel/framework:11.* to test against the latest stable version.
Laravel Add-ons: Test against popular packages like spatie/laravel-permission, tightenco/ziggy, or laravel/breeze.
Version Pinning: Specify exact versions (e.g., laravel/framework:11.0.0) for critical dependencies.

Example .multi-tester.yml:

laravel/framework:11.*
  travis
spatie/laravel-permission:2.*
  travis

2. Custom Test Commands

Override default test commands for Laravel-specific setups:

my-package/laravel-service:
  install: composer install --prefer-dist --no-interaction
  script: php artisan test --env=testing

3. Parallel Testing

Use stop_on_failure: false in .multi-tester.yml to run tests in parallel (faster for multiple dependencies):

config:
  stop_on_failure: false

4. Testing Multiple PHP Versions

Leverage multi-tester with Docker or CI environments to test against PHP 8.1–8.3:

laravel/framework:11.*:
  install: docker-compose run --rm laravel-test composer install
  script: docker-compose run --rm laravel-test vendor/bin/phpunit

5. Travis CI Integration

Add a matrix job to your .travis.yml:

matrix:
  include:
    - php: 8.2
      env: MULTITEST='on'
script:
  - if [ "$MULTITEST" = "on" ]; then vendor/bin/multi-tester; fi;

6. GitHub Actions Integration

Use a workflow file (.github/workflows/multi-tester.yml):

name: Multi-Tester
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install --prefer-dist --no-interaction
      - run: vendor/bin/multi-tester

Laravel-Specific Patterns

Testing Against Laravel’s `vendor/` Structure

multi-tester automatically replaces your package in the vendor/ directory of the target project. For Laravel packages, this means:

Your package’s src/ directory is symlinked or copied into the target’s vendor/ folder.
Autoloading is preserved (thanks to Composer’s replace support in v2.6.1+).

Handling Laravel’s `composer.json` Quirks

Replace Key: If your package uses replace in its composer.json, multi-tester respects this (tested in v2.6.1+).
Autoload: Ensure your composer.json has correct autoload and autoload-dev sections for seamless integration.

Testing with Laravel’s Artisan Commands

Use custom scripts to run Laravel-specific tests:

laravel/framework:11.*:
  script: php artisan test --env=testing --coverage

Gotchas and Tips

Pitfalls and Debugging

1. Package Not Found

Issue: multi-tester fails with "Package not found" for a dependency.
Fix: Ensure the package exists on Packagist (e.g., laravel/framework vs. my-private/package).

Workaround: Use a direct clone URL if the package isn’t on Packagist:

my-private/package:
  clone: git clone https://github.com/my-org/my-private-package.git .

2. Permission Denied

Issue: multi-tester fails with permission errors when cloning or installing.
Fix: Run multi-tester with sudo (not recommended) or adjust directory permissions:
```
chmod -R 755 ./vendor
```
Better Fix: Use a dedicated directory outside your project root:
```
config:
  directory: ../multi-tester-workspace
```

3. Composer Install Failures

Issue: Dependencies fail to install in the target project.
Debug: Use --verbose to see the exact Composer command:
```
vendor/bin/multi-tester --verbose
```

Fix: Customize the install command to match the target project’s needs:

laravel/framework:11.*:
  install: composer install --prefer-dist --no-interaction --optimize-autoloader

4. Test Script Failures

Issue: Tests fail silently or with unclear errors.
Debug: Check the target project’s vendor/bin/phpunit configuration or use a custom script:
```
laravel/framework:11.*:
  script: vendor/bin/phpunit --debug
```

5. Network Timeouts

Issue: Cloning or installing hangs due to network issues.
Fix: Use a mirror or VPN, or increase timeouts:
```
config:
  timeout: 300 # 5 minutes
```

6. Git Detach Warnings

Issue: Warnings about detached HEAD states after testing.

Fix: Use --detach in clone commands (enabled by default in v2.5.0+):

my-package:
  clone: git clone --detach https://github.com/my-org/my-package.git .

Configuration Quirks

1. Default Values

clone: Falls back to Packagist’s Git URL if omitted.
install: Defaults to `composer install --no

Multi Tester Laravel Package