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

Class	Description
AccessibilityTrait	Assess accessibility of rendered pages.
CommandTrait	Run local shell commands and assert on their result.
CookieTrait	Verify and inspect browser cookies.
DateTrait	Convert relative date expressions into timestamps or formatted dates.
DiagnosticsTrait	Append on-failure diagnostics to the failure message of any failed step.
DropzoneTrait	Simulate a real multi-file drag-and-drop gesture onto a Dropzone target.
ElementTrait	Interact with HTML elements using CSS selectors and DOM attributes.
FieldTrait	Manipulate form fields and verify widget functionality.
FileDownloadTrait	Test file download functionality with content verification.
IframeTrait	Switch between iframes and the root document.
JavascriptTrait	Automatically detect JavaScript errors during test execution.
JsonTrait	Assert JSON responses with path and schema checks.
KeyboardTrait	Simulate keyboard interactions in Drupal browser testing.
LinkTrait	Verify link elements with attribute and content assertions.
MetatagTrait	Assert <meta> tags and head/SEO markup in page markup.
ModalTrait	Interact with and assert modals.
PathTrait	Navigate and verify paths with URL validation.
ResponseTrait	Verify HTTP responses with status code and header checks.
ResponsiveTrait	Test responsive layouts with viewport control.
RestTrait	Lightweight REST API testing with no Drupal dependencies.
TableTrait	Interact with HTML table elements and assert their content.
WaitTrait	Wait for a period of time or for AJAX to finish.
XmlTrait	Assert XML responses with element and attribute checks.

Index of Drupal steps

Class	Description
Drupal\BigPipeTrait	Wait for Drupal BigPipe placeholders to be replaced on JavaScript scenarios.
Drupal\BlockTrait	Manage Drupal blocks.
Drupal\CacheTrait	Invalidate specific Drupal caches from within a scenario.
Drupal\ConfigOverrideTrait	Disable Drupal config overrides from settings.php during a scenario.
Drupal\ConfigTrait	Assert and set stored Drupal configuration values with automatic revert.
Drupal\ContentBlockTrait	Manage Drupal content blocks.
Drupal\ContentTrait	Manage Drupal content with workflow and moderation support.
Drupal\DraggableviewsTrait	Order items in the Drupal Draggable Views.
Drupal\EckTrait	Manage Drupal ECK entities with custom type and bundle creation.
Drupal\EmailTrait	Test Drupal email functionality with content verification.
Drupal\FileTrait	Manage Drupal file entities with upload and storage operations.
Drupal\MediaTrait	Manage Drupal media entities with type-specific field handling.
Drupal\MenuTrait	Manage Drupal menu systems and menu link rendering.
Drupal\ModuleTrait	Enable and disable Drupal modules with automatic state restoration.
Drupal\OverrideTrait	Override Drupal Extension behaviors.
Drupal\ParagraphsTrait	Manage Drupal paragraphs entities with structured field data.
Drupal\QueueTrait	Manage and assert Drupal queue state.
Drupal\RedirectTrait	Manage Drupal redirect entities provided by the contrib redirect module.
Drupal\SearchApiTrait	Assert Drupal Search API with index and query operations.
Drupal\StateTrait	Manage and assert Drupal State API values with automatic revert.
Drupal\TaxonomyTrait	Manage Drupal taxonomy terms with vocabulary organization.
Drupal\TestmodeTrait	Configure Drupal Testmode module for controlled testing scenarios.
Drupal\TimeTrait	Control system time in tests using Drupal state overrides.
Drupal\UserTrait	Manage Drupal users with role and permission assignments.
Drupal\WatchdogTrait	Assert Drupal does not trigger PHP errors during scenarios using Watchdog.
Drupal\WebformTrait	Manage Drupal webforms.

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:

Exception	When thrown
ElementNotFoundException	Element, field, link, or selector not found on page
ExpectationException	Assertion fails (value mismatch, state verification)
UnsupportedDriverActionException	Feature requires specific driver (e.g., Selenium)
\RuntimeException	Invalid input or processing error (not an assertion)

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