← All field notes

BDD is a conversation, not a test script

Most BDD initiatives end up as slow, brittle UI scripts nobody from the business reads. Why it happens, the shortcut that causes it, and a Screenplay + Page Object architecture that keeps feature files about behaviour.

18 Nov 202610 min read#QA#BDD#Test automation

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:

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:

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:

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:

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:

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:

  1. 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.
  2. Write the scenarios together, in business language, and keep only the examples that illustrate each rule.
  3. Automate them on a clean stack: thin steps, Screenplay tasks, slim Page Objects, setup through APIs.
  4. Ask the product owner to review the feature file in the pull request. If they can't, the file isn't done.
  5. 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.