I've seen many teams "adopt BDD". The story usually goes like this: someone installs Cucumber, QA writes a few hundred scenarios, and a year later the suite takes two hours, breaks every time a button moves, and nobody outside the test team has opened a .feature file in months.
The team concludes that BDD doesn't work. In most cases they never did BDD. They did test automation with extra steps.
What BDD is actually for
Behaviour-Driven Development is first a communication tool. Its goal is to make the business, developers and testers agree on what the software should do before it's built, using concrete examples instead of abstract requirements.
The Given/When/Then format is just a way to write those examples down so that:
- the product owner can read them and say "yes, that's the rule",
- the developer knows exactly what to build and when they're done,
- the tester has the edge cases on the table from day one,
- and the examples can later be automated to become living documentation that tells you when the software stops behaving as agreed.
Notice the order. Conversation first, documentation second, automation third. Most failed BDD initiatives do it the other way around.
If the business never reads your feature files, you don't have living documentation. You have test scripts in a funny syntax.
Why it often fails
The same mistakes come back in almost every team I've coached:
- Tool first. "We do BDD" means "we use Cucumber". No discovery workshop, no Three Amigos, no Example Mapping. The scenarios are written by one person, alone, after the code.
- QA owns the feature files. The business is "too busy" to read them, developers see them as QA's thing. The shared language never emerges.
- Scenarios as exhaustive test cases. Every combination of every field ends up in a Scenario Outline with 40 rows. The rule drowns in data. Keep the few examples that illustrate the rule; push combinatorics down to unit tests.
- Incidental details. User names, passwords, dates, IDs and URLs that have nothing to do with the behaviour under discussion.
- Everything goes through the UI. Even rules that live entirely in the back end are checked by clicking through five screens.
- And the big one: imperative scenarios. Feature files that describe how to use the screen instead of what the system should do.
That last one deserves its own section, because it's the one that feels like a good idea at the time.
The temptation to go fast
Writing step definitions is work. So at some point someone has a bright idea: let's write a small set of generic steps once, and then anybody can write tests without coding.
When I click on the "<button>" button
When I type "<text>" in the "<field>" field
When I select "<option>" in the "<dropdown>" dropdown
Then I should see "<text>" in the "<element>" element
It works. For a few weeks, the team produces scenarios at an impressive pace. Here's what they look like:
Scenario: Transfer above limit
Given I open "https://test.bank.local/login"
When I type "jdoe" in the "username" field
And I type "Passw0rd!" in the "password" field
And I click on the "Login" button
And I click on the "Payments" menu
And I click on the "New transfer" link
And I select "BE68 5390 0754 7034" in the "From account" dropdown
And I type "BE71 0961 2345 6769" in the "Beneficiary IBAN" field
And I type "1600" in the "Amount" field
And I click on the "Confirm" button
Then I should see "Transfer refused" in the ".alert-danger" element
Read it again and answer one question: what is the business rule?
You can't tell. Is 1600 refused because of the balance? A daily limit? A per-transfer limit? Is the beneficiary blacklisted? The scenario says nothing about why, which is the only thing the business actually cares about. Twelve lines, zero knowledge.
And the bill arrives quickly:
- It's brittle. Rename "Confirm" to "Send", and every scenario that sends a transfer breaks. That's not one test, that's two hundred.
- It's unreadable. The product owner won't review this, and they're right not to. The shared language is gone.
- It's tied to one interface. The same rule applies to the mobile app and the public API, but this scenario can only ever run in a browser.
- It hides duplication. Login is copy-pasted in every scenario. When the login flow gets MFA, you edit hundreds of files.
- It's slow. Every scenario walks through the full UI, including the parts that have nothing to do with the rule.
The time you saved by not writing step definitions, you pay back with interest on every UI change.
Describe behaviour, not interactions
Here's the same example written as an actual conversation with the business:
Feature: Daily transfer limit
Rule: A customer cannot transfer more than their daily limit
Background:
Given Alice has a daily transfer limit of €2,000
Scenario: A transfer within the remaining limit is accepted
Given Alice has already transferred €500 today
When she transfers €1,500 to Bob
Then the transfer is accepted
And her remaining limit for today is €0
Scenario: A transfer above the remaining limit is refused
Given Alice has already transferred €500 today
When she tries to transfer €1,600 to Bob
Then the transfer is refused because it exceeds her daily limit
And her remaining limit for today is still €1,500
Now the rule is in the title, the examples sit right on the boundary, and the product owner can say "wait, does the limit reset at midnight or after 24 hours?" That question is worth more than the whole imperative suite, because it gets asked before the code is written.
A few quick tests I use when reviewing feature files:
- The phone test. Would the scenario still be true if the customer did this by calling their bank? If yes, you're describing behaviour. If it mentions buttons, fields or URLs, you're describing a screen.
- The read-aloud test. Can the product owner read it out loud in a meeting without stumbling? If not, it's for machines only.
- The why test. Can you tell, from the scenario alone, why the outcome is what it is?
- The redesign test. If the UX team redesigns the page tomorrow, should this file change? It shouldn't.
Of course, the clicks still have to happen somewhere. The question is where. That's an architecture problem, not a Gherkin problem.
A clean architecture: Screenplay and Page Objects
The trick is to give each kind of knowledge its own home, so that each kind of change only touches one place:
Feature files WHAT the business wants changes when a rule changes
│
Step definitions thin glue, no logic almost never changes
│
Screenplay WHO does WHAT, in which order changes when a workflow changes
Actors · Abilities · Tasks · Interactions · Questions
│
Page Objects WHERE things are on a screen changes when the UI changes
│
Driver Playwright, Selenium, HTTP client…
Each layer only talks to the one below it. Let's walk through it with the transfer example. The code is Python: behave for the step definitions and ScreenPy for the Screenplay part. The ideas apply to any stack.
Step definitions: translators, nothing more
A step definition should do one thing: turn a business sentence into an actor attempting a task. No locators, no waits, no if.
from behave import given, when, then
from screenpy import See
from screenpy.resolutions import IsEqualTo
@given("{name} has a daily transfer limit of €{limit}")
def step_daily_limit(context, name, limit):
context.actor = context.cast.actor_named(name)
context.actor.attempts_to(SetDailyLimit.to(euros(limit)))
@given("{name} has already transferred €{amount} today")
def step_previous_transfer(context, name, amount):
context.actor.attempts_to(TransferMoney.of(euros(amount)).to(ANY_BENEFICIARY))
@when("she tries to transfer €{amount} to {name}")
def step_transfer(context, amount, name):
beneficiary = context.cast.actor_named(name)
context.actor.attempts_to(TransferMoney.of(euros(amount)).to(beneficiary.iban))
@then("the transfer is refused because it exceeds her daily limit")
def step_refused(context):
context.actor.should(
See.the(TheLastTransferOutcome(), IsEqualTo(Refused("DAILY_LIMIT_EXCEEDED")))
)
If your step definitions are long, the logic belongs one layer down.
Screenplay: actors who perform tasks
The Screenplay pattern models the test the way the business talks about it: actors (Alice, Bob, an administrator) have abilities (browse the web, call an API), perform tasks made of interactions, and answer questions about the state of the system.
A task describes a business intent as a sequence of smaller steps:
from screenpy import Actor, beat
from screenpy_selenium.actions import Click, Enter, Open
class TransferMoney:
"""Transfer an amount to a beneficiary through the web banking app."""
def __init__(self, amount, beneficiary=None):
self.amount = amount
self.beneficiary = beneficiary
@classmethod
def of(cls, amount):
return cls(amount)
def to(self, beneficiary):
self.beneficiary = beneficiary
return self
@beat("{} transfers {amount} to {beneficiary}.")
def perform_as(self, the_actor: Actor) -> None:
the_actor.attempts_to(
Open.their_browser_on(NewTransferPage.URL),
Enter.the_text(str(self.beneficiary)).into_the(NewTransferPage.BENEFICIARY_IBAN),
Enter.the_text(str(self.amount)).into_the(NewTransferPage.AMOUNT),
Click.on_the(NewTransferPage.CONFIRM_BUTTON),
)
Tasks compose. TransferMoney doesn't know how to log in: the actor's session is set up by a LogIn task once, in a hook. When MFA arrives, you change LogIn, and nothing else.
A question reads the outcome without knowing how the test got there:
from screenpy_selenium.questions import Text
class TheLastTransferOutcome:
"""The outcome of the last transfer, as shown in the status banner."""
@beat("{} reads the outcome of the last transfer.")
def answered_by(self, the_actor: Actor) -> TransferOutcome:
banner = Text.of_the(NewTransferPage.STATUS_BANNER).answered_by(the_actor)
return TransferOutcome.from_banner(banner)
And here's the part teams usually miss: setup doesn't have to go through the UI. SetDailyLimit and the "already transferred €500 today" step can use the actor's ability to call an API instead of clicking through the back office. Only the behaviour under test goes through the interface you care about. Your scenarios get faster and stop failing because of screens they weren't even testing.
Page Objects: where things are, and nothing else
In this architecture the Page Object shrinks back to what it was always meant to be: a map of a screen.
from screenpy_selenium import Target
class NewTransferPage:
URL = f"{BASE_URL}/payments/transfers/new"
BENEFICIARY_IBAN = Target.the("beneficiary IBAN").located_by('[data-test="beneficiary-iban"]')
AMOUNT = Target.the("amount").located_by('[data-test="amount"]')
CONFIRM_BUTTON = Target.the("confirm button").located_by('[data-test="confirm-transfer"]')
STATUS_BANNER = Target.the("transfer status").located_by('[role="alert"]')
No assertions. No workflows. No login_and_create_transfer_and_check_banner(). When Page Objects carry workflows, they grow into thousand-line god classes that every test depends on. Screenplay takes the behaviour out of them; they keep the locations. Each pattern does the job it's good at.
Use stable, test-dedicated selectors like data-test attributes, agreed with the developers. A redesign that keeps those attributes costs you zero test changes.
What you get
Back to the changes that used to break two hundred scenarios:
- The "Confirm" button becomes "Send". You change one line in
NewTransferPage. Feature files: untouched. - Login gets MFA. You change the
LogIntask. Feature files: untouched. - The limit becomes €2,500 for premium customers. You add a scenario to the feature file, after discussing it with the business. That's exactly the change that should touch the feature file.
- The same rule must hold on the public API. You give Alice the ability to call the API and provide an API version of the
TransferMoneytask. The scenario is reused as is.
Every change lands in exactly one layer, and the layer tells you who should be involved: rules with the business, workflows with the team, locators with the developers.
Where to start
If your current suite looks like the first example, don't rewrite everything. Pick the next feature and:
- Hold a 30-minute Three Amigos session before development. Product owner, developer, tester. Use Example Mapping: rules on one colour, examples on another, questions on a third.
- Write the scenarios together, in business language, and keep only the examples that illustrate each rule.
- Automate them on a clean stack: thin steps, Screenplay tasks, slim Page Objects, setup through APIs.
- Ask the product owner to review the feature file in the pull request. If they can't, the file isn't done.
- Migrate old scenarios when you touch them, not before.
BDD doesn't fail because of Gherkin or Cucumber. It fails when we skip the conversation to get to the automation faster. Have the conversation, write down what was agreed, and let the architecture deal with the clicks.