Behat Drupal Extension

The Drupal Extension is an integration layer between Behat, Mink Extension, and Drupal. It provides step definitions for common testing scenarios specific to Drupal sites.

Note: v6 supports Drupal 10 and 11 on PHP 8.2+ and runs on DrupalDriver 3.x. Sites that need Drupal 7 or PHP 8.1 should pin to the 5.x branch. See UPGRADING.md for the v5 to v6 migration guide.

Use it for testing your Drupal site.

If you're new to the Drupal Extension, we recommend starting with the full documentation.

Quick start

1. Install using Composer:

   composer require --dev drupal/drupal-extension

2. Create a file called behat.yml with a minimal configuration. For more information on configuration options, see the configuration guide.

   default:
     autoload: ['%paths.base%/tests/bootstrap']
     suites:
       default:
         paths: ['%paths.base%/tests/features']
         contexts:
           - Drupal\DrupalExtension\Context\DrupalContext
     extensions:
       Drupal\MinkExtension:
         browserkit_http: ~
         base_url: http://example.org/  # Replace with your site's URL
       Drupal\DrupalExtension:
         blackbox: ~

3. Initialize Behat in your project:

   vendor/bin/behat --init

4. Find pre-defined steps to work with using:

   vendor/bin/behat -di

5. Optionally, define your own steps in tests/bootstrap/FeatureContext.php

6. Start adding your feature files to the tests/features directory of your repository.

Available steps

Class	Description
ConfigContext	Provides pre-built step definitions for interacting with Drupal config.
DrupalContext	Provides pre-built step definitions for interacting with Drupal.
DrushContext	Provides step definitions for interacting directly with Drush commands.
MailContext	Provides pre-built step definitions for interacting with mail.
MarkupContext	Extensions to the Mink Extension.
MessageContext	Provides step-definitions for interacting with Drupal messages.
MinkContext	Extensions to the Mink Extension.

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 `STEPS.md`.
Read this file before writing or modifying Behat tests.
Use only step patterns from this file. Do not invent steps.

If `STEPS.md` does not exist or is outdated, regenerate it:

    vendor/bin/behat -di > STEPS.md

Regenerate after adding new Context classes or updating dependencies.

For detailed step documentation, see: vendor/drupal/drupal-extension/STEPS.md

Credits

• Originally developed by Jonathan Hedstrom with great help from eliza411
• Maintainers
  • Alex Skrypnyk
• All these great contributors

Additional resources

• Behat Drupal Extension documentation
• Behat Steps - A collection of Behat steps
• Behat documentation
• Mink documentation
• Drupal Behat group

Release notes

See GitHub Releases.

Contributing

Features and bug fixes are welcome!

See CONTRIBUTING.md for more information.