Behat Steps

Behat lets you write tests as plain-English scenarios, then runs them against your site. This page introduces Behat Steps, the library that gives those scenarios their steps, so you can tell whether it suits your project before you install it. Here's a scenario:

Feature: Contact page

  Scenario: Visitor finds the contact page
    When I visit "/contact"
    Then the response status code should be 200
    And I should see the heading "Contact"

Each line is a step, and Behat can only run a step when there's PHP code behind it. Behat Steps is that code: hundreds of steps for pages, forms, links, cookies, APIs and Drupal sites, already written, documented and tested, so you can go straight to writing scenarios.

The steps come as PHP traits: 28 that work on any website, and 29 that only mean something on a Drupal site. The library tests its own steps to avoid false positives and negatives, and every step follows the same wording rules, so the language stays consistent from one trait to the next. When no shipped step says what you mean, you write your own, and it can call the same helpers the shipped steps are built on.

What you get

Here's what comes with the library:

• Web steps and Drupal steps list every step, with a page per trait and an example for each step.
• Every step is a thin wrapper over named helpers, so your own steps can call the same code. HELPERS.md lists every helper, and it ships with the package.
• A step names the capability it needs, never a backend, so a step whose capability Drush provides, such as clearing caches or creating users, runs through Drush as well as in-process.
• It supports Behat 3.33+ and Behat 4, Drupal 11 and 12, and PHP 8.3 to 8.5, as Supported versions shows.
• The steps work with 3 browsers: BrowserKit for plain HTTP, and Selenium2 or Chrome for a real browser that runs JavaScript.
• After each scenario, the library deletes the entities its steps created, in reverse creation order.
• The step and helper references ship with the package as Markdown, so an AI coding agent in your project reads the same reference you do. A skill ships beside them that has the agent write a step of your own on the helpers.
• Architecture shows how the layers fit together, with a page per layer and a trait taken apart line by line. An AI agent maintains its diagrams through the update-architecture-docs skill.

How it fits together

You extend 1 of the library's contexts, the classes that hold its steps, in a context of your own, FeatureContext. Then you register it in your Behat configuration, along with the Behat Steps extension and Mink, the library that drives the browser. Contexts explains which context to extend.

A step that works on a page goes through Mink's browser session. A step that needs the site itself, such as one that creates a user, goes through a backend such as Drupal or Drush. Key concepts explains each piece, with a diagram of the whole.

Supported versions

Each major version runs on the following versions of Behat, Drupal and PHP:

Version	Behat	Drupal	PHP	Support
4.x	3.33+, 4	11, 12	8.3, 8.4, 8.5	Receives new features, bugfixes and security updates.
3.x	3	10, 11	8.2, 8.3, 8.4, 8.5	LTS until 1 July 2027. Its latest minor receives bugfixes and security updates only.
2.x	3	9, 10	8.2+	Unsupported. Receives no updates.

Where to next

• New to Behat or to this library? Start with Installation, then the Quick start, which takes you to a passing scenario. Key concepts explains the pieces as you meet them.
• To upgrade a 3.x project, see Migrating from 3.x, which covers the migration guide and the AI agent skill that applies it.
• For steps of your own, Scenario styles explains when they pay off, and HELPERS.md lists what they can call.