README

A collection of Behat steps

What is it?

This library is a collection of reusable testing actions and assertions for automated testing with Behat. It’s designed to help you write reliable, readable, and maintainable tests faster.

We provide a set of generic traits that can be used in any PHP project, with special support for Drupal through additional step definitions. All methods are properly namespaced, so they won’t conflict with your existing custom step definitions.

Our goal is to make this a go-to library for Behat steps. We maintain solid test coverage to avoid false positives and negatives, and follow clear guidelines to keep the step language consistent.

We actively maintain this package and welcome contributions from the community.

Available steps

Index of Generic steps

Index of Drupal steps

Installation

composer require --dev drevops/behat-steps:^3

Optional dependencies

To keep installs lean, packages needed by only some traits are declared as suggest rather than hard requirements (only behat/behat and behat/mink are required). Add the ones for the traits you use to your project's require-dev - run composer suggests to list them:

• Drupal traits (DrevOps\BehatSteps\Drupal\*) need drupal/drupal-extension.
• JsonTrait needs softcreatr/jsonpath for JSON path steps and justinrainbow/json-schema for JSON schema steps.
• @javascript scenarios need a Mink driver - see JavaScript drivers below.

Usage

Add required traits to your FeatureContext.php (example):

<?php

use DrevOps\BehatSteps\CookieTrait;

/**
 * Defines application features from the specific context.
 */
class FeatureContext extends DrupalContext {

  use CookieTrait;

}

Ensure that your behat.yml has all the required extensions enabled.

JavaScript drivers

Steps that require a real browser (used by scenarios tagged @javascript) are driver agnostic: they work with a Selenium/WebDriver driver and with selenium-less drivers that talk to Chrome directly over the Chrome DevTools Protocol. Both are exercised by this library's own CI.

To run @javascript scenarios without a Selenium server, add dmore/behat-chrome-extension (which pulls in dmore/chrome-mink-driver) and point it at a headless Chrome:

default:
  extensions:
    DMore\ChromeExtension\Behat\ServiceContainer\ChromeExtension: ~
    Behat\MinkExtension:
      browser_name: chrome
      javascript_session: chrome
      chrome:
        api_url: 'http://chrome:9222'

Any image that exposes a DevTools endpoint works (for example chromedp/headless-shell). For local visual debugging you can override api_url at runtime via Behat's BEHAT_PARAMS environment variable - for instance to drive a headed Chrome on your host - as long as that browser can reach your site's base_url.

Exceptions

This library uses Mink exception classes for consistent error handling:

Example error messages:

Element matching css "#my-element" not found.
Link with title "My Link" not found.
Select with id|name|label "My Select" not found.
The cookie with name "session" was not set.

Skipping before scenario hooks

Some traits provide beforeScenario hook implementations. These can be disabled by adding @behat-steps-skip:METHOD_NAME tag to your test.

For example, to skip beforeScenario hook from ElementTrait, add @behat-steps-skip:ElementTrait tag to the feature.

Automatic entity cleanup

Traits that create Drupal entities (content blocks, media, managed files, paragraphs, ECK entities, menus and menu links, redirects, blocks and webforms) register each created entity in a shared registry and delete them in reverse creation order at the end of the scenario, keeping the test database clean across long suites. Nodes, users, taxonomy terms, roles and language entities are cleaned up by the base Drupal Extension and are never registered here, so there is no double-deletion.

To keep all registered entities after a scenario, add @behat-steps-skip:entityCleanupAfterScenario to the scenario or feature.

To keep only entities of a named type, add @behat-steps-entity-cleanup-skip:ENTITY_TYPE_ID (for example @behat-steps-entity-cleanup-skip:media). Repeat the tag to keep several types.

Writing tests with AI assistants

Copy and paste below into your project's CLAUDE.md or AGENTS.md file.

## Writing Behat Tests

Available step definitions are listed in `.behat-steps.txt`.
Read this file before writing or modifying Behat tests.
Use only step patterns from this file. Do not invent steps.

If `.behat-steps.txt` does not exist or is outdated, regenerate it:

    ./vendor/bin/behat --definitions=i > .behat-steps.txt

Regenerate after adding new step traits or updating dependencies.

For detailed examples, see: vendor/drevops/behat-steps/STEPS.md

Development

See CONTRIBUTING.md for details on how to contribute to this project.

This repository was created using the Scaffold project template