Skip to content
wannacode

What, not how

In short: A scenario says what the system does, not how you click around the screen. "Click the Order button" breaks with every design change while the rule stays the same. One scenario checks one behaviour: one "When". The words are the business words: cart, order, delivery, not tables and URLs.

Problem

Forty scenarios and one button

The shop changes the design of the cart. The "Order" button becomes "Go to payment" and moves to a new line. Nothing in the rules has changed.

The next morning 40 scenarios fail. They are all about delivery, and they all start like this:

Feature: Free delivery


  Scenario: Delivery under the boundary
    Given I open the shop website
    And I put a mug for 49.99 € in the cart
    And I open the cart
    When I click the "Order" button
    Then the bottom of the screen says "Delivery: 4.90 €"

The owner cannot read them either. They look for the delivery rule and see buttons.

The idea

What, not how

This scenario says how to click around the screen. That is why it is called imperative: a series of commands. The same example, told as what the system does, is declarative:

Feature: Free delivery


  Scenario: An order just under the boundary
    Given a cart of 49.99 €
    When I place the order
    Then delivery is 4.90 €

Three lines instead of five, and none of them knows about buttons. If tomorrow the order is placed by voice or through the mobile app, the scenario stays the same. The rule has not changed, so the scenario should not change either.

The "how" does not disappear. It moves into the code that binds the step "When I place the order" to the system. One line there gets fixed for the new button, not 40 scenarios.

Try it

What or how?

1. Which step is declarative?
2. Which step is declarative?
3. Which step is declarative?

Exercise

Rewrite it

1. Without the buttons. The editor holds the scenario from the start of the lesson.

Rewrite the scenario in the language of the vocabulary: no website, buttons or screen. Add an example exactly on the boundary too, so that both bugs are caught.

GherkinFree delivery

The idea

One behaviour per scenario

Here is something else that looks thrifty:

Feature: Free delivery


  Scenario: Delivery
    Given a cart of 49.99 €
    When I place the order
    Then delivery is 4.90 €
    Given a cart of 50.00 €
    When I place the order
    Then delivery is free

These are two scenarios in one. If it fails, you have to read the lines to find out which behaviour is broken. And if the first half fails, the second half does not even run.

The rule is one behaviour per scenario: one "When", and the name states that behaviour. If you need an "and" in the name ("cancelling and refunding"), there are two behaviours.

Exercise

Split it

2. Two in one. In this task two "When" steps in one scenario are an error.

Split the scenario in two: each with one behaviour and a name that states it.

GherkinFree delivery

The idea

The language of the business

The words in a scenario are the words of the owner and the customer: cart, order, delivery, promo code. The same as in the story and on the Example Mapping board. If the business says "order", the scenario does not say "request", and the code does not say cart_submission.

We do not write:

  • names of tables and fields (orders.delivery_fee);
  • URLs and server responses (POST /api/orders, 200);
  • function names (calcDelivery(4999)).

Those are the team's decisions and they change, while the rule stays. A scenario that contains them breaks because of them, and whoever knows the rule cannot read it.

More precisely, if you are curious

The Cucumber documentation ("Writing better Gherkin") says the same: a scenario describes the behaviour of the system, not how it is built, that is, what, not how. It does not forbid the imperative style: in some contexts the details matter, but such scenarios cost more to maintain.

When is the "how" the requirement itself? When you check the accessibility of the payment form, the keyboard and the labels are the behaviour. Then the scenario says them. But the delivery rule does not depend on a button.

The idea of a shared language for the business and the team has a name in software design: the ubiquitous language of Eric Evans's Domain-Driven Design (2003). The words in the conversation, in the scenario and in the code are the same.

Test

Check yourself

1. Why is "click the Order button" a bad step in a delivery scenario?
2. A scenario has two "When" steps. What do you do?
3. A scenario name: "Cancelling and refunding". What does it hint at?
4. Which scenario speaks the language of the business?

Made by Ivo Gergov as part of Evo Tech's campaign for accessible programming education ·