A requirement can sound clear in conversation yet leave developers, testers, and stakeholders expecting different results. An executable specification closes that gap with a concrete, business-readable example of expected behavior that the team can run as an automated check. It serves as both an acceptance criterion and a guide to what must be built. section 1.1 section 2.3.6
To move from a conversation to a check:
- Discuss the business goal, rules, examples, and counterexamples with the people who need the feature and those who will build and test it. section 1.1
- Write a significant example as a scenario: Given a context, When something happens, Then expect an outcome. Keep the vocabulary familiar to stakeholders. section 3.4 section 7.1
- Put the scenario in a feature file and connect its steps to test code. A scenario can be run before that code exists; its failure identifies work still to do. section 3.5.2 section 2.3.6
- Run the checks during the build. Passing scenarios support acceptance and regression testing; readable results also document delivered behavior. section 2.3.6 section 1.1
Choosing the next departing trains
For a commuter asking at 8:00 about a direct trip, a scenario states three scheduled departures—8:02, 8:15, and 8:21—and expects the first two to be shown. That precise result is more useful than a general request to “show the next trains”: it gives the team a shared answer to verify. section 3.4 section 3.5.2
Listing 3.1 An acceptance criteria expressed in Cucumber
Feature: Show next departing trains
As a commuter traveling between two stations on the same line
I want to know what time the next trains for my destination will leave
So that I can spend less time waiting at the station
Scenario: Next train going to the requested destination on the same line
Given the T1 train to Chatswood leaves Hornsby at 8:02, 8:15, 8:21
When Travis wants to travel from Hornsby to Chatswood at 8:00
Then he should be told about the trains at: 8:02, 8:15
The feature-file example keeps the commuter’s goal beside the Given–When–Then check, so the expected result remains readable without inspecting test code. section 3.5.2
Keep the business outcome separate from the means of automation. A registration journey might be checked through a web UI or a sequence of API interactions; the scenario’s purpose is to verify the business rule, not to test a particular interface. Broader journey scenarios can sit alongside narrower rules, such as valid email addresses or account activation. section 13.2.2 section 13.3
When requirements change, change the relevant scenario first. A failing check shows the difference between requested and current behavior; corresponding unit tests can help locate the code to update. If an existing check fails after a change, decide whether it describes an obsolete requirement or has caught a regression. High-level scenarios and lower-level specifications then remain useful worked examples for maintenance. section 3.7 section 2.3.9
