Learning Objectives
By the end of this lesson you will be able to:
- Explain what makes a
Whenstep correct - Recognize why a scenario should have exactly one
When - Rewrite a
Whenstep that's doing too much
When Is the Trigger
If Given is the world before, When is the single moment something happens to it. It answers: "what action causes the behavior I'm testing?"
When the user applies the discount code "SAVE10"
When the user submits the login form with an incorrect password
When the payment gateway times out
Note the last example: a When doesn't have to be a human clicking something. It can be any event — a system trigger, a third-party timeout, a scheduled job firing. What matters is that it's the thing that causes the behavior described in Then.
Why Exactly One When
A scenario tests one cause-and-effect relationship. If you find yourself writing two When steps, you're almost certainly testing two different things stitched into one scenario:
# Wrong — two unrelated actions crammed into one scenario
Given a registered user
When they log in with valid credentials
When they update their email address
Then their profile shows the new email
This scenario is actually testing login and profile editing. Split it:
Scenario: User updates their email address
Given a logged-in user
When they update their email address
Then their profile shows the new email
Now the login precondition moved into Given ("a logged-in user"), and the scenario has one clean trigger.
When Should Name the Action, Not the Mechanics
Like Given, a When step should stay at the business-action level, not the UI-mechanics level:
# Too mechanical
When the user clicks the button with id "submit-btn"
# Correct — describes the business action
When the user submits the payment form
The mechanical version breaks the moment the button's HTML id changes. The business-action version survives any implementation detail change underneath it.
Pro Tip: When you catch yourself writing a second
When, don't delete it — that's often the signal you actually have two scenarios pretending to be one.
Key Takeaways
Whenis the single trigger action or event that causes the behavior under test- A trigger can be a human action, a system event, or a third-party occurrence — not only clicks
- A scenario should contain exactly one
When; more than one usually means it should be split Whensteps should describe business actions, not UI mechanics like element IDs