Brief "How To" guide

1. Given When Then
and other styles
for
documenting (testable) requirements

2. The Given-When-Then style
of writing requirements
clarifies thinking.
"Given" defines the preconditions
that hold before an event or operation.
• "When" identifies an event or operation
• "Then" identifies the post conditions
that hold after the event or operation.

3. We can apply Given-When-Then at
three levels of requirements writing
to document intended
1. business events (business behavior) involved
at the highest level (organization/user actor)
2. user interface for business process proxies
3. code behavior at the unit-test level (robot actor).

4. Business Process Level:
Given:[business goal / strategy]
When: [business process / event]
Then: [desired business behavior]
(This can be tested by a process audit.)

5. User Interface Level:
Given: [user-interface context / mode]
When: [user action]
Then: [system response]
(This can be tested through the UI. )

6. Robot / Computer Level:
Given: [system state]
When: [system event / input / additional state ]
Then: [expected system post-condition]
(This can be automated via xUnit framework.)

7. At the business process level, our focus is
on describing the business context of a set
of 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).

8. The interface level requirement identifies the interaction
between actors.
Typically, one actor is a user and the second actor is the
system.
(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.

9. But we cannot write an automated test without
knowing a great deal about the design.
However, the design can be indicated with
Given-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.

10. 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' ).
].

11. Some things cannot be
completely 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.

12. Compare: User Story
• Template:
As a <role name>,
I need <business capability>,
in order to <business benefit 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.

13. 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.)

14. Given When Then
clarifies 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).

15. GitHub Resources
• https://github.com/RichardAlexanderGreen/
GivenWhenThen
• See also:
• https://github.com/KentBeck/TDD-Tyrant
• https://github.com/pivotal/jasmine