Phpspec Skip Example Extension Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev pamil/phpspec-skip-example-extension
   

   Register the extension in your phpspec.yml:

   extensions:
       PhpSpecSkipExampleExtension: ~
   

2. First Use Case Annotate a spec method with @skip to exclude it from execution:

   use PhpSpecSkipExampleExtension\Annotation\Skip;
   
   class MySpec extends ObjectBehavior
   {
       /**
        * @skip
        */
       public function it_should_be_skipped()
       {
           // This spec will not run
       }
   }
   

3. Where to Look First

   • Annotations: Check src/Annotation/Skip.php for annotation syntax.
   • Configuration: Review phpspec.yml for extension settings.
   • CLI Output: Run phpspec run to see skipped specs marked in output.

Implementation Patterns

Workflow Integration

1. Conditional Skipping Use annotations for temporary exclusions (e.g., flaky tests, WIP features):

   /**
    * @skip("Database connection issues")
    */
   public function it_queries_the_database()
   {
       // ...
   }
   

2. Group Skipping Skip entire spec classes with @skip on the class docblock:

   /**
    * @skip("Deprecated API")
    */
   class DeprecatedSpec extends ObjectBehavior
   {
       // All methods skipped
   }
   

3. CI/CD Integration Combine with --filter to run only non-skipped specs:

   phpspec run --filter="~@skip"
   

Best Practices

• Document Skips: Include reasons in annotations (e.g., @skip("Needs refactor")).
• Version Control: Track skipped specs in phpspec.yml or a dedicated file (e.g., SKIPPED_SPEC.md).
• Automate: Use a script to generate a list of skipped specs:

  phpspec run --format=pretty | grep -E "@skip"
  

Gotchas and Tips

Pitfalls

1. Annotation Parsing

   • Issue: Annotations with spaces or special characters may fail. Fix: Use quotes: @skip("reason with spaces").
   • Debug: Enable PhpSpec’s verbose mode (phpspec run -v) to check parsing.

2. Caching

   • Issue: Skipped specs may persist in cached results. Fix: Clear PhpSpec cache (phpspec clear-cache) or run with --no-cache.

3. IDE Support

   • Issue: Some IDEs (e.g., PHPStorm) may not recognize @skip as a valid annotation. Fix: Add @mixin or @method annotations for IDE compatibility:

     /**
      * @skip
      * @mixin
      */
     

Debugging Tips

• Check Extension Load: Verify the extension is registered in phpspec.yml and not overridden.
• Log Output: Enable PhpSpec’s debug mode (phpspec run -d) to inspect extension behavior.
• Test Isolation: Run a single skipped spec to confirm exclusion:

  phpspec run --spec=path/to/SpecWithSkip
  

Extension Points

1. Custom Annotations Extend the package by creating a subclass of Skip (e.g., @wip, @todo) and register it in phpspec.yml:

   extensions:
       App\CustomSkipExtension: ~
   

2. Dynamic Skipping Override the extension’s logic to skip specs programmatically (e.g., based on environment variables):

   // In a custom extension class
   public function skipExample(Example $example)
   {
       if (getenv('SKIP_DB_TESTS')) {
           return true;
       }
       return parent::skipExample($example);
   }
   

3. Integration with Other Tools

   • PHPUnit: Use tools like phpunit-polyfills to bridge skipped specs between PhpSpec and PHPUnit.
   • Git Hooks: Automatically skip specs in PRs with labels (e.g., skip: true).