Composer Test Scenarios Laravel Package

Getting Started

Start by installing the package via Composer in your project:

composer require --dev greg-1-anderson/composer-test-scenarios

Then, add a composer-test-scenarios.json (or .dist) file to your project root. This JSON file defines sets of dependency variations (e.g., different versions of a critical package, PHP version constraints, or optional extension availability). The simplest first use case is testing compatibility across multiple versions of a single dependency—such as symfony/console—to catch regressions early.

Implementation Patterns

Typical workflows involve defining scenario matrices in composer-test-scenarios.json, such as:

• Version pinning tests: Test composer require foo/bar:~2.0 vs ~3.0 without manually editing composer.json.
• Optional extension testing: Define scenarios with and without ext-redis, ext-imagick, etc., to verify fallback behavior.
• PHP version compatibility: Combine with CI tools (e.g., GitHub Actions) to run separate composer install and test runs per scenario.

Example snippet:

{
  "scenarios": [
    {
      "name": "symfony 5",
      "require": {"symfony/console": "^5.4"}
    },
    {
      "name": "symfony 6",
      "require": {"symfony/console": "^6.3"}
    }
  ]
}

Run scenarios locally via vendor/bin/composer-test-scenarios run, or integrate into your CI pipeline with commands like composer test-scenarios:run --scenario=symfony6.

Gotchas and Tips

• Composer lock regeneration: Scenarios may regenerate composer.lock for each run—ensure your CI caches only the final state, or use --no-lock if appropriate.
• Error output collisions: When running many scenarios in parallel, stdout/stderr can interleave. Use --verbose or output to separate logs per scenario.
• Scenario naming: Avoid spaces/special chars in scenario names; stick to alphanumeric + hyphens/underscores to prevent shell or CI tool issues.
• Override behavior: require, require-dev, and config can be overridden—replace and conflict cannot. Always double-check in composer.json afterward.
• Extension support: To test with optional extensions, use "config": {"ext-redis": "*"} } in a scenario to require it (not suggest it). Be aware some extensions don’t install cleanly in non-linux environments.