From bada1e948e6e4bf52e87c1ccbeed9584b9c2fdd1 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Mon, 16 Feb 2026 13:18:03 +0100 Subject: [PATCH 1/2] docs: Behat and AI --- behat_and_ai.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++++ index.rst | 1 + 2 files changed, 82 insertions(+) create mode 100644 behat_and_ai.rst diff --git a/behat_and_ai.rst b/behat_and_ai.rst new file mode 100644 index 0000000..6ea4ff7 --- /dev/null +++ b/behat_and_ai.rst @@ -0,0 +1,81 @@ +Behat and AI +============ + +AI coding agents can generate and modify code based on behavioural descriptions. +Behat provides a reliable way to define, verify, and preserve behaviour in these workflows. + +By expressing behaviour as executable scenarios, Behat ensures that AI-generated code +satisfies a clear and objective contract. + +Using Behat as a Behavioural Contract +------------------------------------- + +Behat scenarios define observable behaviour in a precise and executable form: + +.. code-block:: gherkin + + Feature: Refund processing + + Scenario: Refunding a paid order + Given there is a paid order + When I refund the order + Then the order should be marked as refunded + + Scenario: Prevent duplicate refunds + Given an order has already been refunded + When I refund the order + Then the refund should be rejected + +AI agents can implement features and use Behat to verify that the expected behaviour is satisfied. +When scenarios pass, the behavioural contract is fulfilled. + +Executable and Verifiable Behaviour +----------------------------------- + +Behat scenarios serve as executable specifications. They can be used by AI agents to: + +* verify correctness after implementing a feature +* detect behavioural regressions +* ensure behaviour remains consistent during refactoring + +Because scenarios are executable, they remain accurate as the system evolves. + +Generating Scenarios with AI +---------------------------- + +AI agents can generate Behat scenarios from behavioural descriptions. +These scenarios can then be reviewed, refined, and executed. + +This allows behaviour to be defined before or alongside implementation. + +Behat provides a structured and executable representation of behaviour +that can be used directly by AI tooling. + +Human Review and Iteration +-------------------------- + +Generated scenarios should be reviewed to ensure they accurately represent the intended behaviour. + +Once validated, scenarios serve as the authoritative definition of the feature. AI agents can implement +or modify the system until all scenarios pass. + +This creates a reliable feedback loop where behaviour is defined, verified, and preserved. + +Maintaining Behaviour Over Time +------------------------------- + +Behat ensures that behaviour remains stable as code changes. AI agents can safely modify or refactor code, +and Behat will detect any unintended behavioural changes. + +As long as scenarios pass, the defined behaviour is preserved. + +Behat MCP Server +---------------- + +Behat provides an `MCP (Model Context Protocol) server`_ that allows AI agents to interact +directly with Behat projects. + +The MCP server enables agents to discover scenarios, execute Behat, +and integrate behavioural verification into automated workflows. + +.. _`MCP (Model Context Protocol) server`: https://github.com/Behat/mcp-server diff --git a/index.rst b/index.rst index 0d6c844..c5af569 100644 --- a/index.rst +++ b/index.rst @@ -96,6 +96,7 @@ and many more. cookbooks releases useful_resources + behat_and_ai community .. _`Behaviour Driven Development`: https://en.wikipedia.org/wiki/Behavior-driven_development From b232c2c1ad99b8433d537373670c7866e66ff9d6 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Tue, 17 Feb 2026 08:38:44 +0100 Subject: [PATCH 2/2] Updates after code review --- behat_and_ai.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/behat_and_ai.rst b/behat_and_ai.rst index 6ea4ff7..59cbb43 100644 --- a/behat_and_ai.rst +++ b/behat_and_ai.rst @@ -54,7 +54,10 @@ that can be used directly by AI tooling. Human Review and Iteration -------------------------- -Generated scenarios should be reviewed to ensure they accurately represent the intended behaviour. +As with any specification or testing tool, generated scenarios and assertions should be reviewed carefully. +It is critical to ensure that both the human-readable scenarios and the executable step definitions +accurately represent the intended behaviour. They also need to be robust enough to prove that +the actual behaviour matches the expectations, even if the implementation changes. Once validated, scenarios serve as the authoritative definition of the feature. AI agents can implement or modify the system until all scenarios pass. @@ -64,8 +67,8 @@ This creates a reliable feedback loop where behaviour is defined, verified, and Maintaining Behaviour Over Time ------------------------------- -Behat ensures that behaviour remains stable as code changes. AI agents can safely modify or refactor code, -and Behat will detect any unintended behavioural changes. +With well-designed scenarios and step definitions, Behat ensures that behaviour remains stable as code changes. +AI agents can safely modify or refactor code, and Behat will detect any unintended behavioural changes. As long as scenarios pass, the defined behaviour is preserved.