Exit course
Chapter 11 of 12 Intermediate 8 min read 3 quick checks Updated

BDD Anti-Patterns and How to Fix Them

On this page
  1. 1. Cucumber without the conversation
  2. 2. Scripts in Gherkin
  3. 3. A step library as a programming language
  4. 4. Scenarios that depend on each other
  5. 5. Everything through the browser
  6. 6. Incidental details
  7. 7. Long journeys and conjunction steps
  8. 8. Steps that do not wait for the page
  9. 9. Step definitions organised by feature file
  10. 10. Ignoring undefined and pending steps

Most teams that give up on Cucumber do so for the same handful of reasons. None of them is a bug in Cucumber; they are habits that turn executable specifications into a slow, fragile test layer nobody reads. This chapter lists the common ones with a fix for each, so you can spot them in your own suite.

1. Cucumber without the conversation#

Symptom: testers write feature files after the code is done; the product owner has never read one; the scenarios mirror the implementation.

Why it hurts: you pay for an extra layer (Gherkin plus step definitions) and get none of the benefit, which was catching misunderstandings early.

Fix: run a short discovery session (chapter 1) before development starts, and have someone from the business side review the formulated scenarios. If nobody outside engineering will ever read the scenarios, ask honestly whether plain JUnit, pytest or Playwright Test would serve you better.

2. Scripts in Gherkin#

Symptom: steps like When I click "#submit", And I wait 2 seconds, Then the ".alert" element contains "Saved".

Why it hurts: every UI change breaks scenarios although the behaviour is unchanged, and the scenarios no longer say what the feature is for (chapter 2).

Fix: rewrite steps in business language and push locators, waits and navigation down into step definitions and page objects. A useful test: would the step still be true if the feature were delivered through an API or a mobile app?

3. A step library as a programming language#

Symptom: a few dozen ultra-generic steps (I click {string}, I type {string} into {string}, I go to {string}) from which every scenario is assembled.

Why it hurts: it looks like reuse but it is a slow, untyped programming language with no functions, no variables and no IDE support. Scenarios become long and say nothing about the domain.

Fix: reuse belongs in the code below the step definitions (page objects, API clients, helpers), not in the wording of the steps. It is fine to have many specific steps that each call the same helper.

A team is proud that 600 scenarios use only 25 step definitions, all of the form I click {string} and I type {string} into {string}. What is the problem?

Generic steps move the test logic into the feature files, where it cannot be refactored and nobody outside QA can read it. Reuse should happen in the code that step definitions call.

4. Scenarios that depend on each other#

Symptom: "Create an order" must run before "Cancel the order"; running one scenario alone, or in a different order, fails.

Why it hurts: you cannot run a single scenario to debug it, you cannot run in parallel (chapter 8), and one failure cascades into many.

Fix: every scenario sets up its own context in its Given steps. Create the order through an API or a database helper in the step definition of Given Tom has an open order, and keep UI interactions for the behaviour being tested.

5. Everything through the browser#

Symptom: every rule, including validation tables and calculations, is checked by a Cucumber scenario that drives a browser. The suite takes an hour.

Why it hurts: UI scenarios are the slowest and most fragile tests you have. Using them to check 40 input combinations multiplies both problems.

Fix: keep a few UI scenarios per rule to show the behaviour end to end, and check the detail lower down. Cucumber can run the same Gherkin against an API or the domain code if the step definitions call those instead of a page object. Chapter 6's advice about Scenario Outlines applies: illustrate the rule, do not enumerate inputs.

6. Incidental details#

Symptom: scenarios full of values that do not matter to the rule: full addresses, phone numbers, product SKUs, timestamps.

Why it hurts: the reader cannot tell which value is the point. When one of them changes, scenarios fail for no business reason.

Fix: keep only what illustrates the rule ("an order over 50 euros", "a customer in Belgium") and generate the rest in step definitions or parameter types. Personas such as "Tom" (chapter 4) are one way to hide details behind a name.

A free-shipping scenario lists the customer's full name, street, phone number, card number and five products with SKUs. The rule is "orders over 50 euros ship free". What should the scenario keep?

The total is the only value the rule depends on. Everything else is incidental: it hides the point and makes the scenario fail for reasons unrelated to shipping.

7. Long journeys and conjunction steps#

Symptom: one scenario signs in, searches, adds to the basket, checks out and signs out; or steps like Given I am signed in and have two items in my basket and a voucher.

Why it hurts: the first failure hides everything after it, the title cannot say what is being tested, and conjunction steps cannot be reused.

Fix: one behaviour and one When per scenario (chapter 2). Split conjunction steps into separate Given/And steps, or name the state once (Given Tom has a basket ready for checkout) and build it in code.

8. Steps that do not wait for the page#

Symptom: scenarios that pass on a fast laptop and fail on a CI runner or a cloud grid, usually on the first Then after an action.

Why it hurts: the step reads the page before the new one has loaded, sees the old content and fails. Teams then add sleeps, which make every run slower and still fail on a bad day.

Fix: wait for the condition, not for time: WebDriverWait until an element or URL appears in Selenium, web-first expect assertions in Playwright. This course hit exactly this bug when chapter 8 switched on parallel runs: the first version of Given Tom is signed in read the page heading straight after clicking "Login", and with two browsers competing for the CPU it sometimes read "Login Page" instead of "Secure Area". Waiting for the URL to contain /secure fixed it.

A related trap is something on screen that is not part of the page at all. On the grid, Chrome showed its own "change your password" dialog after the sign-in (the demo password is in breach lists). The dialog is not in the DOM, so findElement happily found the "Logout" link, but the click landed on the dialog and the scenario failed waiting for the login page. The session video showed it at once; turning off the password manager in ChromeOptions (chapter 3) fixed it. When a step fails only on the grid, watch the video before changing any waits. The flaky tests course goes through the whole family of timing bugs.

9. Step definitions organised by feature file#

Symptom: SignInFeatureSteps, CheckoutFeatureSteps, each with its own copy of "Tom is signed in".

Why it hurts: step definitions are global (chapter 4). Copies either collide as ambiguous steps or drift apart under slightly different wording.

Fix: organise step definitions by domain concept (AccountSteps, BasketSteps), and share state between them with dependency injection (chapter 5), not inheritance or static fields.

10. Ignoring undefined and pending steps#

Symptom: the build is green, but the report is full of undefined or pending steps that never ran.

Why it hurts: a scenario with an undefined step checks nothing.

Fix: current versions of Cucumber-JVM and Cucumber-JS fail the run on undefined and pending steps by default, as chapter 4 showed. Keep it that way, and mark work in progress with a @wip tag that CI excludes, rather than leaving half-defined scenarios in the main run. A --dry-run (or cucumber.execution.dry-run=true on the JUnit Platform) lists undefined steps without starting a single browser.

A scenario passes locally every time and fails on the grid about one run in three, always on Then he sees "Order confirmed", with the old page's text in the error. What is the best fix?

The step reads the page before navigation finished. Waiting for the condition fixes the cause; a sleep only shifts the odds and slows every run, and retries hide the bug.