Weave Code
Behat Nelmio Describer Laravel Package
macpaw/behat-nelmio-describer
A Behat extension that hooks into NelmioApiDocBundle to automatically describe and validate JSON responses in your scenarios. Instead of hand-writing assertions, it compares API output against your existing Nelmio documentation, keeping tests concise and your docs honest.
Bundle for adding sample responses behat test nelmio to api doc
Frequently asked questions about Behat Nelmio Describer
- Does macpaw/behat-nelmio-describer work with Laravel?
- No, not natively. It is a Symfony bundle that registers through Symfony's bundle system and hooks NelmioApiDocBundle's describer pipeline, while Laravel has no bundle registry or equivalent native hook point. Laravel teams can reuse the capture-then-inject idea, but the package is not a drop-in dependency for a Laravel app.
- How do I install macpaw/behat-nelmio-describer?
- In a Symfony application you install it with Composer, enable the bundle in bundles.php, configure Behat, and have NelmioApiDocBundle running with describers. There is no Laravel service provider, so installation in a Laravel app is not supported. Check the Composer constraints in v2.0.1 before assuming PHP or Symfony compatibility.
- Can I use this package with Pest or PHPUnit instead of Behat?
- No. The extension is built around Behat contexts and scenario hooks, not PHPUnit or Pest. Laravel projects using Pest would need a separate adapter around Scribe or Scramble rather than this package.
- What Laravel alternatives exist for generating API docs from tests?
- Scribe, Scramble, and l5-swagger are the common Laravel options for API documentation. None of them uses Nelmio describers, so the equivalent is a custom example resolver that reads recorded fixtures and feeds them into your doc generator. That keeps the real-examples idea without the Symfony coupling.
- Which Symfony, PHP, and NelmioApiDocBundle versions are supported?
- v2.0.1 is a compatibility patch that adds Symfony 7.0 support, so the practical target is a modern Symfony line rather than the older 4/5 era. Read the exact PHP and NelmioApiDocBundle floors from composer.json rather than assuming them. If you need Symfony 6.4 or 7.x only, confirm the constraint diff from v2.0.0 to v2.0.1.
- Is macpaw/behat-nelmio-describer actively maintained?
- Treat it as minimally maintained. The repository has around 2 stars, 0 dependents, a single-contributor release cadence, and one Symfony 7 compatibility PR; the evaluation also flags a discrepancy around its previous archived status that should be verified. A recent release is not the same as renewed stewardship. For critical use, vendor-fork it or port the pattern.
- Does it capture request payloads, response payloads, or both, and does it redact sensitive data?
- The design captures sample request and response payloads during Behat runs and injects them into Nelmio's describer pipeline. The evaluation notes an open question about whether both request and response are captured or responses only, and it does not identify a documented redaction mechanism. Review captured fixtures for auth headers, tokens, and fixture-borne PII before committing generated docs.
- What are the production risks of using this package?
- Runtime production risk is low because the package operates at test and documentation time and never enters the request path. The real risks are CI reliability and documentation accuracy, especially if captured payloads contain secrets or personal data. Keep it out of production dependencies and scan generated artifacts.
- How much work is it to port this pattern to Laravel?
- Expect roughly a 3 to 10 developer-day port, with about half a day to audit the repository and diff v2.0.0 to v2.0.1. The implementation is a 200 to 400 LOC adapter that captures fixtures and injects examples into the doc generator you actually run. Then wire it into CI and add redaction checks.
- Can it validate JSON responses against Nelmio documentation in Behat scenarios?
- Yes, the package is intended for documentation-aware API assertions: it compares API output against your existing Nelmio documentation instead of hand-written assertions. That keeps feature specs and docs aligned and reduces duplication. The capability remains Symfony and Behat specific and does not translate directly to Laravel's PHPUnit or Pest stack.
Weaver
How can I help you explore Laravel packages today?