Phpspec Skip Example Extension Laravel Package

Getting Started

Install the package with Composer:

composer require --dev graham-campbell/phpspec-skip-example-extension:^5.1  

Then enable it in phpspec.yml at your project root:

extensions:  
    Akeneo\SkipExampleExtension: ~  

Begin using @require annotations in your spec classes to conditionally skip entire specs when dependencies (classes/interfaces) are missing — especially useful in polyfills, optional bridges, or multi-version compatibility suites.

Implementation Patterns

• Conditional Spec Execution: Apply @require Some\Class or @require SomeInterface at the class level to skip the entire spec if the dependency is unavailable. This avoids test failures in environments lacking optional components (e.g., Laravel vs Symfony bridges).
• Spec Organization: Use in test suites for optional integrations (e.g., Doctrine DBAL drivers, cache adapters) to prevent noise in CI when a given dependency is not installed.
• Continuous Workflow Integration: Combine with phpspec run --format progress to get clear skip indicators (e.g., S for skipped) without breaking the build pipeline. Ideal in monorepos where different components are tested conditionally.
• Extensibility Hook: Though not officially documented beyond @require, future extensions could leverage similar annotation parsing—code relies on Akeneo\SkipExampleExtension namespace, suggesting backward-compatible expansion paths.

Gotchas and Tips

• Namespace Trap: The extension is enabled using Akeneo\SkipExampleExtension, not GrahamCampbell\… — double-check phpspec.yml to avoid silent no-op.
• Class Existence Only: @require only checks if the class/interface exists; it does not verify version, trait availability, or runtime capabilities. Add runtime guards separately if needed.
• Silent Skipping: Skipped specs show as S in default progress format, but may be missed in verbose outputs — run with --format pretty to see skip reasons (Skipped: requirement 'Foo\Bar' not satisfied).
• Version Warning: Last updated in 2021; verify compatibility with newer PhpSpec versions (tested with PhpSpec ≤ 7.x, notPhpSpec 8+). Consider pinning versions in CI.
• Local Debugging: If specs aren’t skipping as expected, run phpspec run --strict-exit-code and inspect the full output — PHP fatal errors (e.g., interface not found) will fail fast, bypassing the annotation. Ensure autoloading is correct before @require logic triggers.