Architecture
These pages show how Behat Steps works inside. You don't need any of it to write scenarios. It's here for when you write a trait or extend the library, or want to know why a step behaves the way it does. The section holds the following pages:
- Logical architecture shows the parts and which way they depend on each other.
- 3 pages take 1 layer each:
- The Backend layer reaches the site and picks a backend for every step by capability.
- The Extension layer plugs the library into Behat and Mink and gives traits their options.
- The Steps layer holds every step and helper.
- Data flow shows what runs when, and whose code it is.
- Anatomy of a trait takes a trait apart, line by line.
- Public API and versioning lists what semantic versioning covers, and the exceptions a failing step throws.
- Class inheritance shows what extends what.
An AI agent maintains these pages and their diagrams through the update-architecture-docs skill in .claude/skills/update-architecture-docs/SKILL.md, which draws them with the drawio-skill. Everything here is traced from the source code, and where the 2 disagree, the code wins.
Looking for a reference instead? Web steps and Drupal steps list the steps, HELPERS.md lists the helpers behind them and Configuration reference lists the options and tags.
Diagram sources
Each diagram is a draw.io source beside 2 SVGs its page embeds: 1 for the light color mode and 1 for the dark, so the site shows the one that matches. All 3 are committed, so a reviewer sees the source diff and the rendered result. The following table lists every diagram of this section:
| Diagram | Page | Source | Renders |
|---|---|---|---|
| Logical architecture | Logical architecture | logical-architecture.drawio | light, dark |
| Backend selection | Backend layer | backend-selection.drawio | light, dark |
| Extension layer | Extension layer | extension-layer.drawio | light, dark |
| Steps layer | Steps layer | steps-layer.drawio | light, dark |
| Data flow | Data flow | data-flow.drawio | light, dark |
| Class inheritance | Class inheritance | class-inheritance.drawio | light, dark |
The 3 diagrams of the HTTP clients guide live beside it in guides/, drawn and checked the same way.
To change a diagram by hand, open its source in draw.io, save it, then export every SVG again from the repository root:
php scripts/draw-diagram.php --export docs/content/architecture docs/content/guides
Each SVG records the hash of the source it came from, and php scripts/draw-diagram.php --check docs/content/architecture docs/content/guides, which the unit suite runs too, fails an SVG exported from an older source and a diagram missing either of its SVGs.
After a structural change, ask the AI agent to "update architecture docs". A new layer, namespace, backend or capability counts, and so does a change to an inheritance tree or to the scenario lifecycle. The agent re-traces the affected diagrams and pages from the current code and redraws them through the update-architecture-docs skill.