Debugging Oro Commerce v6.1 Behat Tests

Debugging Flow

Start with the cheapest signal and escalate. Most failures resolve at steps 1-3.

1. Read the failure output and var/log/<env>.log — Behat surfaces "element not found" for what is often a 500 in the app. The real cause lives in the server log, not the Behat stack trace.
2. Re-run with -v / -vv / -vvv — verbose shows the matched step definition, very verbose adds hook execution, debug adds the full step matcher trace. Escalate one level at a time.
3. Capture state — insert And I take screenshot at the suspected failure point. Oro's ScreenshotTrait::takeScreenshot captures cursor position too, except when a browser alert is showing. Drop dump($variable) into Context classes to inspect runtime state.
   • Multi-gate failure? Go breadth-first with ONE diagnostic step, not N sequential runs. When a scenario fails with an opaque "thing missing / empty" symptom and there are several plausible gates (visibility tables + scope + Elasticsearch index + system config + feature flag, etc.), write a single @Then I dump X for :arg step in the Context that queries EVERY plausible culprit in one shot and throws the combined state as a RuntimeException. One 2–4 minute behat cycle then returns all the evidence at once. Serialised hypothesis-at-a-time runs compound cost and context-switching. Wrap each sub-query in try/catch so a missing table or wrong service name doesn't suppress the rest. Revert the diagnostic step before committing — it's scaffolding, not permanent test coverage. See the Comprehensive Visibility/State Dump pattern in references/breadth-first-diagnostics.md.
4. Isolate the scenario — strip every step not strictly required to reproduce. A failing 3-step scenario tells you far more than a failing 30-step one.
5. Run with --stop-on-failure — tight feedback loop when chasing a single failing scenario.
6. If intermittent: treat it as an AJAX race, not a flake — see references/ajax-flake.md. Adding And I wait is not a fix.
7. If logic inside a Context is wrong: attach Xdebug — see Xdebug Split-Process below.

Xdebug Split-Process Debugging

This is the part the Oro docs gloss over and it is the highest-leverage technique in the skill.