Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Patterns and Pitfalls

Cucumber Anti-Patterns and How to Fix Them

Spot and fix common Cucumber anti-patterns: UI scripts, giant scenarios, feature-coupled steps, hidden setup, assertion overload, test-case lists and duplicate steps.

Most failed Cucumber adoptions share a story. The team starts with enthusiasm, writes a few hundred scenarios in a hurry, and after a year the suite is slow, brittle and ignored. Nobody reads the feature files, the product owner never opens them, and the developers treat Cucumber as an awkward test runner. The tool did not fail; the habits did. This lesson catalogs the habits that hurt most, shows what each looks like, explains why it hurts and gives a concrete fix. Use it as a review checklist for your own scenarios.

Cucumber cannot run on this site, so the snippets are Gherkin and read-only Java. The runnable stand-in analyses a list of steps for near duplicates, one of the quiet problems in every older suite.

1. Gherkin as a UI script

GHERKIN
When I click "Add to cart"
And I click the cart icon
And I click "Checkout"

Why it hurts: scenarios break when the interface changes, and nobody can see the business rule. Fix: write intentions ("she buys the book") and move clicks into page objects. Full discussion in Declarative vs imperative.

2. Giant scenarios

A scenario with 25 steps that registers, logs in, shops, pays and checks e-mail tests five behaviors at once. When it fails you do not know which one broke, and it takes minutes to run.

Fix: one scenario, one behavior, usually 3 to 7 steps. Share set-up through a small Background or a state-building Given that talks to the system directly rather than clicking through earlier features.

3. Conjunction steps

GHERKIN
Given a registered customer who has two items in the cart and a valid coupon

Why it hurts: one unreadable step, impossible to reuse in a variation. Fix: split into Given a registered customer, And she has 2 items in her cart, And she has a valid coupon. Each piece becomes reusable. The opposite also hurts: ten trivial steps that always travel together should become one meaningful step.

4. Feature-coupled step definitions

Teams create LoginSteps, CartSteps, CheckoutSteps and put Given a customer is logged in in only one of them, then copy it elsewhere with slightly different wording. Cucumber matches steps globally, not per feature file, so the folder name means nothing.

Fix: organize step classes by domain concept (customers, orders, payments), share state through an injected world (Scenario state), and reuse the same step wording everywhere.

5. Vague or ritual steps

Given the system is up and running or Then everything works fine convey nothing. Fix: delete them, or replace them with facts that matter, such as Given the catalog contains "Learning SQL".

6. Hidden business setup and assertion overload

Business facts buried in @Before hooks (Hooks) make scenarios unreadable. The reverse, a Then step that checks a dozen fields, makes failures hard to interpret.

Fix: visible Givens for relevant data; one Then per outcome. If you need to check several attributes of the same thing, use a data table: Then her receipt shows: with rows. Failures then name the field that differs.

7. Actions in Then, assertions in When

Java
@Then("the order is saved")
public void saved() {
    orderService.save(order);          // wrong: a Then must observe, not change
    assertNotNull(order.id());
}

Fix: Given sets up state, When performs one action, Then only observes. The structure is explained in the Gherkin lessons of this track.

8. Scenarios that depend on each other

Scenario B passes only because scenario A created a record earlier. It fails alone, in parallel, or when the order changes.

Fix: each scenario builds what it needs (Test data) and cleans up after itself.

9. Testing every combination in Gherkin

GHERKIN
Scenario Outline: Tax by country
  Examples: (120 rows of country and price)

Cucumber is for documenting and checking key examples, not for exhaustively testing every input. Fix: keep a handful of illustrative examples in Gherkin and cover the combinatorial detail with fast unit tests or property-based tests.

10. Cucumber as a test case management tool

Scenarios named TC_0042_verify_login_with_valid_credentials, written by testers alone after development, never discussed with the business. That is a test script wearing a Gherkin costume; you have paid the cost of the format without the collaboration benefit. Fix: write scenarios before or during implementation, in a conversation between business, development and testing (Three amigos).

11. Sleeps and race conditions

Thread.sleep in steps. Fix: explicit waits in page objects (Waits).

12. Too many layers of indirection

The opposite problem: a base step class, a generic "do anything" step (When I perform "click" on "checkout"), and a custom DSL on top of Gherkin. Fix: prefer plain, boring step definitions and page objects. Abstraction should reduce duplication you really have, not duplication you imagine.

Finding duplicate steps

Older suites accumulate near-identical step texts: she adds 2 books, she adds "2" books, the customer adds two books. Each needs a definition, and each is a chance for drift. The stand-in below normalizes step texts (lowercasing, replacing numbers and quoted values with placeholders) and reports groups that collapse to the same pattern.

Java Finding near-duplicate steps (Java stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Cucumber's own usage plugin (Reports) shows which step definitions are used and how often, which helps retire dead ones.

A review checklist

Before merging a new feature file, ask:

  • Can a non-programmer say what behavior this describes?
  • Is it free of UI words, locators and sleeps?
  • Is every fact that affects the outcome visible in the scenario?
  • Does each scenario test one behavior in about seven steps or fewer?
  • Does it pass alone, in any order and in parallel?
  • Does it live at the cheapest level that can prove the behavior?

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is a 25-step scenario problematic?

    One scenario should describe one behavior, so a failure points to one thing.
  2. 2. Cucumber matches steps to definitions how?

    Steps are global, so organize step classes by domain concept and reuse wording.
  3. 3. A Then step calls orderService.save(order). What is wrong?

    Mixing actions into Then confuses the structure and can hide failures.
  4. 4. What is the best place to test 120 tax-rate combinations?

    Cucumber documents key examples; exhaustive combinations belong in cheaper unit or property-based tests.

Summary

  • The common traps: UI scripts, giant scenarios, conjunction steps, feature-coupled steps, vague steps, hidden setup, assertion overload, ordering dependencies, exhaustive tables, tester-only authorship, sleeps and over-abstraction.
  • Fix them with declarative wording, one behavior per scenario, domain-organized glue, visible data and the cheapest effective test level.
  • Review each new feature file with a short checklist, and prune duplicate and dead steps regularly.

Next: Flaky and slow suites