Sulu Behat Bundle Laravel Package

Getting Started

v2.0.0 is a hard fork in behaviour: the package now targets Sulu 3 only and rebuilds the Page, Article and Snippet contexts around Sulu's own content structure. If you are still on Sulu 2, stay on the 1.x line — do not attempt a partial upgrade.

1. Require the new major and the underlying argument bundle:

   composer require --dev elbformat/sulu-behat-context:^2.0
   

   This pulls in elbformat/symfony-behat-bundle:^1.6, which is what now resolves step arguments from tables, YAML or JSON.
2. Register the contexts you actually need in behat.yml (Page, Article, Snippet). Only enable the ones your suite uses — the Article/Snippet contexts assume Sulu content structures that may not exist in every project.
3. Run vendor/bin/behat --definitions (or --dry-run) first. This is the fastest way to see the reworked step signatures and confirm which of your existing steps no longer resolve.
4. First use case to validate: create a page with an explicit _webspaceKey and locale, then a child page using _parentSlug. That single scenario exercises the three headline features (webspace, locale, parent resolution) and will surface most configuration problems immediately.

Where to look first: the reworked Page Context for parent/webspace handling, and the symfony-behat-bundle changelog for the argument-loading syntax, since that is now the extension point for anything non-trivial.

Implementation Patterns

Parent resolution via _parentSlug / _parentId. The old "as child of :parentId" step is gone. Express the relationship as a field on the page table instead:

Given there is a "default-page" page
  | _webspaceKey | default       |
  | locale       | en            |
  | url          | /default-page |

And there is a "default-page" page
  | _parentSlug | /default-page       |
  | url         | /default-page/child |

Prefer _parentSlug in feature files — it reads as intent and survives fixture renumbering. Reserve _parentId for cases where you are deliberately asserting against a known seeded ID.

Always pin webspace and locale. With multi-webspace support, implicit defaults become a source of flaky, order-dependent tests. Set _webspaceKey and locale on the root page of each scenario and let children inherit visually via the parent link. Treat them as required fields in your team's convention, not optional extras.

Move large fixtures out of Gherkin tables. The new argument layer accepts YAML and JSON, which is the right home for anything beyond ~5 columns or reused across scenarios. Keep short, readable tables inline; externalise page trees, article taxonomies and snippet blocks. This also makes fixtures diffable and reviewable.

Compose scenarios from context responsibilities. Page Context for structure and hierarchy, Article Context for editorial content, Snippet Context for reusable blocks. Build a page skeleton first, then attach articles/snippets — this mirrors how Sulu actually stores content and keeps failures attributable to one context.

Integration tip: because arguments are now fetched through the shared bundle, any custom step you write should use the same argument-resolution mechanism rather than hand-rolling table parsing. That keeps custom steps consistent with the shipped ones and future-proof against further changes in the argument layer.

Gotchas and Tips

• Sulu 2 support is dropped, not deprecated. There is no compatibility shim. Pin ^1.x explicitly in composer.json if you cannot upgrade Sulu yet, otherwise a composer update will happily resolve you into a broken suite.
• The child-page step removal is silent at author time. Old features will fail at runtime with undefined-step errors, not at parse time. Grep your feature files for as child of before upgrading and convert every occurrence — the new form requires both _parentSlug/_parentId and a full url, which is easy to get subtly wrong (a mismatched url produces a page in the wrong place rather than an error).
• Contexts are explicitly not feature-complete. The release notes say "solid base", which means gaps are expected rather than bugs. Before filing an issue, check whether the step exists at all; be prepared to write a local custom context for missing coverage and keep it isolated so it can be deleted once upstream catches up.
• Watch the argument file paths. YAML/JSON arguments are resolved by the bundle, so relative paths are relative to wherever Behat is invoked from, not the feature file. Use paths anchored to the project root and verify in CI, where the working directory often differs from local runs.
• Form bundle is optional and matrix-tested. If your suite conditionally includes form-related steps, mirror the upstream matrix locally (with and without the form bundle) — a green local run without the bundle tells you nothing about the CI leg that has it enabled.
• Debugging parent/locale issues: dump the resolved webspace key and locale for the failing page first. Most "page not found in context" failures in the new structure trace back to a missing _webspaceKey/locale on the parent rather than to the step itself.
• Extension point: when a context is incomplete, extend the shipped context class and add steps rather than editing vendor code; the argument-resolution API from symfony-behat-bundle:^1.6 is the supported seam for doing so.