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
CookieTrait	Verify and inspect browser cookies.
DateTrait	Convert relative date expressions into timestamps or formatted dates.
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.
KeyboardTrait	Simulate keyboard interactions in Drupal browser testing.
LinkTrait	Verify link elements with attribute and content assertions.
MetatagTrait	Assert <meta> tags 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	Bypass Drupal BigPipe when rendering pages.
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\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\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

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.

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.

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