Given When Then and other styles for documenting (testable) requirements
The Given-When-Then styleof writing requirementsclarifies thinking. "Given" deﬁnes the preconditions that hold before an event or operation. • "When" identiﬁes an event or operation • "Then" identiﬁes the post conditions that hold after the event or operation.
We can apply Given-When-Then at three levels of requirements writing to document intended1. business events (business behavior) involved at the highest level (organization/user actor)2. user interface for business process proxies3. code behavior at the unit-test level (robot actor).
Business Process Level:Given:[business goal / strategy]When: [business process / event]Then: [desired business behavior](This can be tested by a process audit.)
User Interface Level:Given: [user-interface context / mode] When: [user action] Then: [system response](This can be tested through the UI. )
Robot / Computer Level:Given: [system state] When: [system event / input / additional state ] Then: [expected system post-condition](This can be automated via xUnit framework.)
At the business process level, our focus ison describing the business context of a setof requirements.Given: The survey (ballot) is published (on-line); and, the survey (voting) period is in-progress.When: A respondent (voter) enters a vote on a ballot item.Then: That vote is tallied.Then: The vote is secret. (It can be authenticated. But, it cannot be traced.)Then: The voter can audit (verify that their entry is in the collection).
The interface level requirement identiﬁes the interactionbetween actors.Typically, one actor is a user and the second actor is thesystem.(In an Enterprise Integration scenario, it might be two robots.)Given: The user is signed-in and authenticated and has navigated to the survey (ballot) panel.When: Some question is a proposal.Then: The allowed responses are Yes, No, and Abstain. Abstain is the default value.
But we cannot write an automated test withoutknowing a great deal about the design.However, the design can be indicated withGiven-When-Then also.Given: A ballot or survey represented in XML.When: The ballot contains a proposal.Then: The XML representation includes the pattern:"<proposal>text</proposal>".Then: The interface-builder (component) will generate user interface code (HTML) from the XML.
At this point, a competent programmer can write code that conforms to this design. The executable test might look like this (Smalltalk):test1234ballotProposalXMLGeneratesHTML "The allowed responses for a proposal are Yes, No, and Abstain." | ballot ballotElement proposalElement html | self given: [ ballot := XML element: ballot with: [ XML element: proposal with: [proposal text]. ]. "configuration comes from setUp" builder := configuration interfaceBuilder. ] when: [ ballotElement := ballot nextElement. proposalElement := ballotElement content at: 1. self assert: ( proposalElement isTag: proposal ). html := builder buildHTMLfrom: proposalElement. ] then: [ self assert: ( html includes: Yes ). self assert: ( html includes: No ). self assert: ( html includes: Abstain ). ].
Some things cannot becompletely automated.• We cannot prove that HTML will execute properly.• We cannot prove that generated code is conceptually correct.• The previous Given-When-Then’s did not specify if widgets would be radio-buttons or pull-downs. But that is probably a good thing.
Compare: User Story• Template: As a <role name>, I need <business capability>, in order to <business beneﬁt statement>.• A user story is a reminder to have a deeper conversation with the user (or user rep).• It provides a place-holder in the backlog.
Compare: Use Case Title: (Identify the situation or end-use.) Preconditions: (Specify context. “Given”) Scenario: (Describe interaction / steps. “When-Then”) Post Conditions: (Expected effects. “Then”) Business Rules: (Identify policy constraints.)
Given When Thenclariﬁes thinking because:Given clause makes context and assumptions more explicit.When clause indicates when/where new behavior is expected.Then clauses indicate expected results (actions / end-states).