Phpspec Skip Example Extension Laravel Package

Getting Started

1. Install the extension as a dev dependency, matching the major version to your PhpSpec version. As of v5.0.0 the package supports PhpSpec 6.0 and 7.0; if you are still on PhpSpec 5.x you need the previous major:

   # PhpSpec 6.x / 7.x
   composer require --dev akeneo/phpspec-skip-example-extension:^5.0
   
   # PhpSpec 5.x and older
   composer require --dev akeneo/phpspec-skip-example-extension:^4.0
   

2. Register it in phpspec.yml. PhpSpec extensions live under the extensions key, keyed by the extension class FQCN. Check the README (or src/) of the installed version for the exact class name before copy-pasting — a major bump can move or rename classes, and a typo here fails silently (the extension simply never loads):

   extensions:
       Akeneo\SkipExampleExtension\Extension\SkipExampleExtension: ~
   

3. Annotate an example you want to skip. Annotations are read from the example's docblock:

   class CalculatorSpec extends ObjectBehavior
   {
       function it_adds_two_numbers()
       {
           $this->add(1, 2)->shouldReturn(3);
       }
   
       /**
        * @skip waiting for the new Money value object
        */
       function it_handles_currency_conversion()
       {
           // not implemented yet
       }
   }
   

4. Run vendor/bin/phpspec run. The annotated example should be reported as skipped rather than executed.

Where to look first: the README of the installed tag for the exact extension FQCN and supported annotations, then the src/ listener that parses annotations and decorates the example runner, and the package's own spec/ directory — it is the most reliable reference for edge cases the README does not cover, and it is also what proves the 6.0/7.0 compatibility claim.

First use case: quarantining a single known-broken or not-yet-implemented example so the suite stays green while the spec (the intent, not the body) stays in the codebase and visible in the report.

Implementation Patterns

• Per-example quarantine. Put @skip on a single it_* method to remove it from execution without deleting the specification. This is the primary supported pattern.
• Skip with a reason. Always write a short justification after the annotation (ticket ID, blocker, date). Six months later the reason matters more than the skip itself:

  /**
   * @skip JIRA-4821 flaky when the clock crosses midnight
   */
  

• Class-level quarantine (verify first). Many implementations also honour the annotation on the spec class docblock, which skips every example in that file. Confirm this against the package's spec/ before relying on it.
• Temporary-pin workflow. Use skip as a pin, not a delete: open a branch, add @skip with a reference, fix the production code in a follow-up commit, remove the annotation in the same PR that fixes it. Reviewers should treat the annotation as a TODO.
• CI reporting hygiene. Skipped examples usually still appear in the totals. Pair the extension with a formatter that surfaces skipped count (--format=progress or a pretty formatter) so skips are visible in CI logs rather than invisible. Optionally grep the output and fail the build above a skip threshold to stop quarantine debt from growing unnoticed.
• Environment-specific specs. Prefer suite-level configuration (phpspec.yml suites with different src_path/spec_path) for environment gating; reserve @skip for examples that are genuinely broken everywhere.
• Pairing with let/letgo. Keep the skipped example's setup meaningful — the spec body should still read as the intended contract even though it never runs, because the next developer will un-skip it and expect the setup to work.
• Legacy-code migration. When writing specs against collaborators that do not exist yet, committing the example with @skip documents the target interface, then the annotation comes off in the implementation PR. It is a lightweight alternative to keeping a spec-ideas.md file.
• Upgrade in lockstep with PhpSpec. v5.0.0 exists precisely to track PhpSpec 6.0/7.0. Upgrade the extension in the same commit as the PhpSpec bump — they are coupled, and a stale extension on a new PhpSpec is one of the silent-failure modes below.
• Fork-friendly extension point. The annotation parser is the extension point if you need custom semantics such as @skipOnWindows or @skipUnlessCi. Fork the listener and register your subclass in phpspec.yml rather than patching vendor code. Since v5.0.0 is the PhpSpec 6/7 branch, target that if your suite has moved forward.

Gotchas and Tips

• Compatibility is version-paired. v5.0.0 adds PhpSpec 6.0 and 7.0 support. Older tags target older PhpSpec. Pin the extension major alongside your PhpSpec major; an incompatible extension typically fails to boot or is silently ignored, not with a clear error.
• Low maintenance, not abandoned. The gap between releases is long (the prior one dated to 2021), so treat it as a small, stable utility: pin it, don't expect rapid fixes, and re-verify on each PhpSpec major. The 5.0.0 release is a good sign but the project is still a thin third-party dependency on a tool that is itself in maintenance mode.
• Registration is silent on failure. A wrong FQCN or wrong YAML indentation produces no warning — you just see the example run normally. Before assuming an annotation bug, confirm the extension is actually loaded by deliberately breaking the class name and checking that nothing changes.
• Re-check the FQCN after a major bump. Class names are part of the public surface and can move between majors. Copy the name from the README of the tag you actually installed, not from an old blog post or a stale lockfile comment.
• Annotation syntax is strict. It must be a real docblock (not // or #), the annotation must be at line start, and the parser is usually a simple regex — @skip inside prose may or may not match depending on the implementation. Do not use @skip() or @Skip.
• Skipped ≠ not constructed. Depending on where the listener hooks into the example lifecycle, the spec's let()/letgo()/constructor may still execute. Do not use @skip as a way to avoid expensive or side-effecting setup; assert on the output rather than assuming nothing ran.
• Skips still count. The example appears in total counts and typically reports as skipped, so --stop-on-failure and exit codes are unaffected. Do not mistake a growing skip count for a healthy suite.
• Do not skip from inside the example body. The annotation is read before execution. For runtime conditions (missing extension, unsupported platform), throw PhpSpec's skipping/pending exception inside the example instead — the annotation is for static, human-decided skips.
• Extension ordering matters. If another extension decorates the example runner or subscribes to the same events, load order in phpspec.yml can change behaviour. Put this extension early if skips are not being honoured.
• Debugging a non-skip. Run vendor/bin/phpspec run <spec>:<example> --format=pretty -v and check that the annotation lands on the method (not inherited from an interface or trait — PhpSpec does not reliably read annotations from traits).
• It is a quarantine tool, not a feature flag. Do not leave @skip in a spec you also run in another suite expecting it to execute; the annotation is unconditional and there is no built-in environment predicate. If you need conditionals, write a small custom listener.
• Exit strategy. For greenfield work, PhpSpec's own PendingException/skipping exception covers most needs without a third-party dependency. Keep this package for legacy suites already standardised on the annotation, and prefer Pest/PHPUnit for new projects — v5.0.0 keeps existing suites viable, it is not a reason to start new ones on PhpSpec 7.