Behat Laravel Package

Getting Started

ibexa/behat is not a standalone test framework you bolt onto any PHP app — it is Ibexa DXP's own Behat bundle: a set of ready-made Behat contexts, Gherkin step definitions, fixtures and configuration profiles that let you write acceptance tests against an installed Ibexa DXP project (Admin UI, REST/headless API, and storefront). Treat it as an extension of your Ibexa install, and expect to spend your first hour reading the four doc files rather than exploring source.

Minimal setup in an existing Ibexa DXP project:

composer require --dev ibexa/behat --no-scripts --no-plugins
composer sync-recipes ibexa/behat --force -v

The sync-recipes step is the important one: it drops the Behat configuration files (behat.yaml, behat_ibexa*.yaml, plus supporting fixtures such as content type definitions and CSV data) into your project. --force overwrites existing files, so if you already have a behat.yaml, back it up or diff first.

Where to look first, in order:

1. doc/getting_started.md — required environment, database assumptions, and how the config files are meant to be wired.
2. doc/running_tests.md — the profiles and command lines Ibexa uses itself.
3. doc/features.md — the catalogue of available Gherkin steps. This is your reference manual; almost every question you will have is answered here.
4. vendor/ibexa/behat/behat_ibexa.yaml and the sibling profile files — the actual suite/profile definitions you are importing.

Then confirm what you have available:

vendor/bin/behat --list-suites
vendor/bin/behat -dl            # list every step definition/pattern
vendor/bin/behat --list-scenarios | head -50

A good first use case: a pure-API smoke test that proves your content model works — create a content type, create an item, publish it, and assert it is visible. That exercise touches the highest-value parts of the bundle (setup/fixture contexts, content contexts, assertions) without dragging Selenium into the picture. Only after that write a @javascript Admin UI scenario, because browser tests are where all the setup cost lives.

Implementation Patterns

Reuse the shipped contexts before writing any PHP. The bundle's core value is that editorial operations are expressed as Gherkin, not as custom step code. You should be able to write a feature like "Editor creates and publishes an article in a folder, an anonymous visitor sees it" almost entirely with provided steps. If you find yourself writing a step definition for something as ordinary as "publish content", check doc/features.md again — it is probably there.

Separate data setup from UI interaction. The dominant pattern is: prepare content, users and roles through API/setup contexts (fast, deterministic), then exercise only the specific behaviour under test through the browser. Scenarios that build their entire world by clicking through the Admin UI are slow and flaky. Reserve UI steps for the assertion and the one interaction you are actually testing.

Organise by suite/profile, not by one giant config. The bundle ships multiple profiles (note behat_ibexa_headless.yaml in the release history alongside Admin UI configuration). Mirror that: an API suite that runs on every commit, and a @javascript suite that runs on a schedule or pre-merge. Tag scenarios (@javascript, plus your own @smoke, @commerce) and drive selection from the tag:

vendor/bin/behat --suite=api
vendor/bin/behat --suite=admin-ui --tags=@smoke

Grow your own contexts by extension, not by fork. Put project-specific step definitions in tests/Behat/Context/ under your own namespace and register them in behat.yaml. Where the shipped contexts expose behaviour you need to tweak, extend the existing context class or compose it, and keep your additions in your own namespace so a composer update of ibexa/behat does not silently erase your work. This is the extension path documented in doc/extending.md; treat that file as the API contract.

Use hooks for the lifecycle, not steps. Cache clearing, fixture loading, user/session setup and teardown belong in Behat hooks (@BeforeSuite, @BeforeScenario, @AfterScenario), not repeated inside feature files. Browser-context hooks are also the right place to capture a screenshot or page source on failure — essential, because a failed Selenium scenario otherwise gives you nothing to debug.

Keep the environment reproducible. Pin the Selenium/browser image (Ibexa's own CI pins a specific SELENIUM_IMAGE tag), run against a database you are willing to destroy, and let the bundle's fixtures define content types rather than hand-editing your dev database. If a scenario only passes on one developer's machine, the fixture set is the usual culprit.

CI shape. Two jobs: a fast PHP/API Behat job with a freshly migrated, fixture-loaded database; and an admin-UI job with Selenium + the full stack behind it. Publish Behat's HTML/JUnit output as artefacts so failures are triaged without a rerun.

Gotchas and Tips

• Version alignment is non-negotiable. Releases ship in parallel lines (e.g. 4.6.x and 5.0.x) matching Ibexa DXP versions. An ibexa/behat branch that is newer than your DXP install will reference field type identifiers, services and config that do not exist — you will see it as "context not found" or config parse failures rather than a clean error message. Pin the minor line to your DXP version.

• Licensing is dual and matters commercially. The package is offered under the Ibexa Business Use Licence (requires a valid DXP subscription) and GPLv2. composer reports NOASSERTION because of the dual declaration — do not read that as "unlicensed", but do get the choice right before shipping it into anything unusual.

• composer sync-recipes --force clobbers your config. Run it once on install, then treat behat.yaml as project source. Re-running it after your project has customised suites/contexts will overwrite them.

• The headless profile no longer imports integrated help (IBX-11133). If you copied an older behat_ibexa_headless.yaml into a project, steps that depended on integrated help will fail; take the updated file instead of patching around it.

• Field type identifiers were rebranded in the 5.0 line (IBX-9947). Gherkin tables referencing ezstring-era names in old features and snippets need updating to the new identifiers when you upgrade. This is the single most common source of "step accepts my table but the content type is wrong" confusion.

• Early database connection initialisation was a real defect (IBX-10534, fixed in 5.0.2 / 4.6.24). If you are on an older patch and see connection errors before any scenario runs — particularly with multiple suites — upgrade rather than debug your parameters.yaml.

• Browser flakiness is mostly waiting. Selenium failures in Ibexa tests are usually the UI not being ready: AJAX-loaded content trees, modals, and slow editors. Prefer the bundle's built-in wait-aware steps over adding sleep() calls in your own definitions; if you must add one, encapsulate it in a single custom step so it is greppable and fixable later.

• Debug recipe. For a single failing scenario:

  vendor/bin/behat --suite=admin-ui features/path/to.feature:42 -f pretty --stop-on-failure -vv
  

  -dl (step definitions) plus -vv output will tell you whether the step matched, matched ambiguously (two definitions, common after you add a custom context), or threw. Ambiguous matches are silent-ish failures that look like logic bugs.

• Extension points worth knowing. Contexts registered in behat.yaml, Behat hooks in your own context classes, and overriding the shipped step definitions through a more specific context. Everything else — services, DI, custom Symfony commands — is outside this bundle's contract and will not survive upgrades cleanly.

• Low ecosystem signal. The public repository is a read-only mirror with negligible external adoption (0 dependents, 1 star). There is no community to consult when a step behaves unexpectedly: your sources of truth are the shipped docs, the shipped feature files, and Ibexa's support channel. Budget for reading the bundle's own .feature files as executable documentation — they are the most reliable specification of how the contexts are intended to be used.