specification by example - by example

1

Specification By Example

By Example!

Gojko Adzic, “Specification By Example”, 2011

2


Principles

3

Notifications help assist the business processes. For example, to notify the Document Experts that there is a request for adjudication to take place, or for the Document Experts to notify the relevant personnel that a new false document has been stored in the false document database.

Notifications help assist the business processes. For example, to notify the Document Experts that there is a request for adjudication to take place, or for the Document Experts to notify the relevant personnel that a new false document has been stored in the false document database.

Examples, not ambiguous requirements

Feature: Notify request for adjudicationAs a verification operatorI want to notify document experts of adjudication requestsSo that I can be informed if a document is genuine or false

Scenario: Send notification of suspicious documentGiven I have scanned a suspicious Portuguese passportWhen I notify the document expertThen document expert receives email containing data| document type || scan timestamp || document white image || document ultraviolet image |

Scenario: Don’t notify when document is genuine

Feature: Notify request for adjudicationAs a verification operatorI want to notify document experts of adjudication requestsSo that I can be informed if a document is genuine or false

Scenario: Send notification of suspicious documentGiven I have scanned a suspicious Portuguese passportWhen I notify the document expertThen document expert receives email containing data| document type || scan timestamp || document white image || document ultraviolet image |

Scenario: Don’t notify when document is genuine

4

Build shared understanding

Don’t notify NotifyWTF?!

JUDGEMENT DAY(AKA RELEASE DATE)

Specification Workshop at start of sprint/release

- Testers (“what if we get a yellow check?”)- Developers (“yellow check = server is down”)- Product Owner/BA (“for me yellow check = red check”)

5

DELIVERED REQUIREMENT

Notifications

assist the business

processes. For example, to notify the Document Experts that there is a request for adjudication to take place, or for the Document Experts to notify the relevant personnel that a new false document has been stored in the false document database.

Notifications

assist the business

processes. For example, to notify the Document Experts that there is a request for adjudication to take place, or for the Document Experts to notify the relevant personnel that a new false document has been stored in the false document database.

Living documentation1 year later client calls…

“Actually… email is déjà vu…

we want Facebook posts!”

Notifications help assist the

business processes. For example, to notify the Document Experts that there is a request for adjudication to take place, or for the Document Experts to notify the relevant personnel that a new false document has been stored in the false document database.

Notifications help assist the

business processes. For example, to notify the Document Experts that there is a request for adjudication to take place, or for the Document Experts to notify the relevant personnel that a new false document has been stored in the false document database.

New release delivered…

6

Feature: Notify request for adjudication…

Scenario: Send notification of suspicious document

Given I have scanned a suspicious Portuguese passport

When I notify the document expert

Then document expert receives email containing data| document type || scan timestamp || document white image || document ultraviolet image |

Scenario: Don’t notify when document is genuine…







DELIVERED FEATURE

Living documentation (cont)1 year later client calls…

“Actually… email is déjà vu…

we want Facebook posts!”

















Then document expert receives Facebook post containing data| document type || scan timestamp || document white image || document ultraviolet image |








Before implementation…

7

Speak the business language...Feature: Notify request for adjudication…














Then document expert receives Facebook post with text “You have a pending request” and URL to PDF report containing data| document type || scan timestamp || document white image || document ultraviolet image |





Then document expert receives Facebook post with text “You have a pending request” and URL to PDF report containing data| document type || scan timestamp || document white image || document ultraviolet image |

8

... and be consistent...Feature: Notify request for adjudication…

Scenario: Send notification of suspicious documentGiven I have scanned a suspicious Portuguese passportWhen I notify the document expert…

Scenario: Send notification of suspicious driving licenceGiven I placed a suspicious Portuguese driving licence in the scannerWhen I notify the document expert…


Scenario: Send notification of suspicious documentGiven I have scanned a suspicious Portuguese passportWhen I notify the document expert…

Scenario: Send notification of suspicious driving licenceGiven I placed a suspicious Portuguese driving licence in the scannerWhen I notify the document expert…


Scenario: Send notification of suspicious passportGiven I have scanned a suspicious Portuguese passportWhen I notify the document expert…

Scenario: Send notification of suspicious driving licenceGiven I have scanned a suspicious Portuguese driving licenceWhen I notify the document expert…


Scenario: Send notification of suspicious passportGiven I have scanned a suspicious Portuguese passportWhen I notify the document expert…

Scenario: Send notification of suspicious driving licenceGiven I have scanned a suspicious Portuguese driving licenceWhen I notify the document expert…

Note: minimize synonims, e.g. “valid” and “correct” -> pick one

9


Good Practices

10

Keep features self-contained (think classes)Feature: Data Capture…

Scenario: Capture mandatory demographic dataScenario: Capture one page documentScenario: Capture default fingerprintsScenario: Capture photo with valid live QA checksScenario: Capture signatureScenario: Save when mandatory modules completed

Feature: Data Capture…

Scenario: Capture mandatory demographic dataScenario: Capture one page documentScenario: Capture default fingerprintsScenario: Capture photo with valid live QA checksScenario: Capture signatureScenario: Save when mandatory modules completed

Feature: Demographic Capture…Scenario: Capture mandatory demographic data

Feature: Demographic Capture…Scenario: Capture mandatory demographic data

Feature: A4 Documents Capture…Scenario: Capture one page document

Feature: A4 Documents Capture…Scenario: Capture one page document

…Note: it’s ok to have a feature with a single scenario

Feature: Fingerprints Capture…Scenario: Capture default fingerprints

Feature: Fingerprints Capture…Scenario: Capture default fingerprints Feature: Login

…Scenario: Can't login without software licence

Feature: Login…Scenario: Can't login without software licence

11

Feature: …

Scenario: <statement of the functionality the scenario exercises>

[Given <application state and/or input data and/or user roles>]When <user action or system event>Then <system state and/or output data> <validation check>

Feature: …

Scenario: <statement of the functionality the scenario exercises>

[Given <application state and/or input data and/or user roles>]When <user action or system event>Then <system state and/or output data> <validation check>

Feature: Photo Enrollment

Scenario: Can’t save enrollment when missing photoGiven demographic module is completeAnd photo module is not completeWhen I save the data captureThen an error message containing “missing photo” is displayed


Scenario: Can’t save enrollment when missing photoGiven demographic module is completeAnd photo module is not completeWhen I save the data captureThen an error message containing “missing photo” is displayed

Respect Given-When-Then mantra


Scenario: No photoGiven I enrolled a new applicant and there is no photoWhen I try to saveThen data is not saved


Scenario: No photoGiven I enrolled a new applicant and there is no photoWhen I try to saveThen data is not saved

12

Specifications, not clicks...Feature: Demographic Capture…

Scenario: Demographic data not mandatoryGiven that MandatoryFields is set to FALSE in config fileWhen I click Save buttonThen data is saved in the local database

Feature: Demographic Capture…

Scenario: Demographic data not mandatoryGiven that MandatoryFields is set to FALSE in config fileWhen I click Save buttonThen data is saved in the local database


Scenario: Demographic data not mandatoryGiven demographic data is not mandatoryWhen I save data captureThen captured data is saved offline


Scenario: Demographic data not mandatoryGiven demographic data is not mandatoryWhen I save data captureThen captured data is saved offline

Exception: when the client imposes technical constraints then keep them in scenario, e.g. “send data by FTP”

13

Feature: <one-liner functionality description easy to reference >As a <persona/role>I want to <action/procedure>In order to <goal>

Feature: <one-liner functionality description easy to reference >As a <persona/role>I want to <action/procedure>In order to <goal>

Feature: Verify documentsAs a verification operatorI want to verify documentsIn order to prevent fraudulent account creation

Scenario: Verify suspicious documentWhen I scan a suspicious Portuguese passportThen a flashing red indicator is displayed

Feature: Verify documentsAs a verification operatorI want to verify documentsIn order to prevent fraudulent account creation

Scenario: Verify suspicious documentWhen I scan a suspicious Portuguese passportThen a flashing red indicator is displayed

Focus on 1 persona per featureFeature: Verify documents

As a system userI want to use the applicationIn order to verify documents

Scenario: Scan suspicious documentGiven I have valid operator credentialsWhen I scan a suspicious Portuguese passportThen a flashing red indicator is displayed

Feature: Verify documentsAs a system userI want to use the applicationIn order to verify documents

Scenario: Scan suspicious documentGiven I have valid operator credentialsWhen I scan a suspicious Portuguese passportThen a flashing red indicator is displayed

14

Focus on 1 user action per scenarioFeature: Save capture…

Scenario: Mandatory modules completedGiven that all mandatory modules are completedWhen I save captureThen data is saved offlineAnd is available for both Data Capture and Export services

Feature: Save capture…

Scenario: Mandatory modules completedGiven that all mandatory modules are completedWhen I save captureThen data is saved offlineAnd is available for both Data Capture and Export services

Feature: Save capture …

Scenario: Mandatory modules completed before saving …

Scenario: Search previously saved capture…

Scenario: Export previously saved capture to filesystem…


Scenario: Mandatory modules completed before saving …

Scenario: Search previously saved capture…

Scenario: Export previously saved capture to filesystem…

Note: user actions can be physical, e.g. “When applicant places right index finger on scanner”

15

Actions, not expected resultsFeature: Save capture…

Scenario: Saving fails when mandatory modules not completedGiven that mandatory module “Demographics” is not completedWhen I try to save captureThen an error message containing “missing modules” is displayed

Feature: Save capture…

Scenario: Saving fails when mandatory modules not completedGiven that mandatory module “Demographics” is not completedWhen I try to save captureThen an error message containing “missing modules” is displayed


Scenario: Saving fails when mandatory modules not completedGiven that mandatory module “Demographics” is not completedWhen I save captureThen an error message containing “missing modules” is displayed


Scenario: Saving fails when mandatory modules not completedGiven that mandatory module “Demographics” is not completedWhen I save captureThen an error message containing “missing modules” is displayed

16

Refactor specification by abstraction...

Feature: Export document verification report…

Scenario: Export false Portuguese passport verification report Given I have scanned a suspicious Portuguese passportAnd I have notified the document expertAnd document expert confirmed document is falseAnd I received notificationWhen I select to export document verification reportThen PDF refort is generated in “c:\Program Data\DocVerifier\Export”


Scenario: Export false Portuguese passport verification report Given I have scanned a suspicious Portuguese passportAnd I have notified the document expertAnd document expert confirmed document is falseAnd I received notificationWhen I select to export document verification reportThen PDF refort is generated in “c:\Program Data\DocVerifier\Export”


Scenario: Export false Portuguese passport verification report Given a confirmed false Portuguese passportWhen I select to export document verification reportThen PDF refort is generated in “c:\Program Data\DocVerifier\Export”


Scenario: Export false Portuguese passport verification report Given a confirmed false Portuguese passportWhen I select to export document verification reportThen PDF refort is generated in “c:\Program Data\DocVerifier\Export”

17

Same scenario, multiple examples...Feature: Verify documents…

Scenario: Verify suspicious Portuguese passportWhen I scan a suspicious Portuguese passportThen a flashing red indicator is displayed

Scenario: Verify suspicious Spanish passportWhen I scan a suspicious Spanish passportThen a flashing red indicator is displayed

Feature: Verify documents…

Scenario: Verify suspicious Portuguese passportWhen I scan a suspicious Portuguese passportThen a flashing red indicator is displayed

Scenario: Verify suspicious Spanish passportWhen I scan a suspicious Spanish passportThen a flashing red indicator is displayed


Scenario Outline: Verify suspicious passport When I scan a suspicious <nationality> passport Then a flashing red indicator is displayed

Examples: | nationality | | Portuguese | | Spanish |


Scenario Outline: Verify suspicious passport When I scan a suspicious <nationality> passport Then a flashing red indicator is displayed

Examples: | nationality | | Portuguese | | Spanish |

Note: parameters in the scenario name don’t get replaced and obscure the purpose

18


Process

19

Why should you care?

Dev – earlier feedback, done = all scenarios passing

QA – know what to test, avoid long feedback loops at crunch time (aka release date)

PO/BA – make sure team understands business needs, delivers value, not technical achievements

Support – know what application is supposed to do in maintenance phase - support request or change request?

20

Working with features

• Shared ownership• When writing understand what are the different functionalities covered in existing features to

avoid overlap. Everyone responsible to keep them tidy and consistent.

• Acceptance, not unit tests • Unit tests check stuff is stored in DB, features check that data can be extracted for the user

• Exception: audit data often needs to be checked directly against DB

• Who can change features? Everyone in the team!

• When can they be changed? Any time spec changes!

Remember…

Specification by Example is about improving communication, so… communicate!

21

Feature organization

• Feature structureRoot folder “features”. Subfolders group related functionality.

• Feature tags (one of each)• Functionality tag: same as parent folder name, e.g. @Authentication, @Backup, @DataExport, …• Release tag, e.g.: @prototype, @phase01, @phase02• Testing tag: @functional, @usability, @load, @security

• Comments / references• can reference sources of requirements, either word documents, email exchanges with clients, change requests, etc… • not mandatory, beware it’s hard to keep up to date

22

Work organization

Client story Server story

23

Work organization (cont)

ApplicationLicence feature ServiceLicence feature

24

References

Basic concepts (worth reading entire chapter)Specification By ExampleIntroducing BDDAcceptance TDD (ATDD) ExplainedSpecification By Example: a Love Story

http://cuke4ninja.com/sec_cucumber_jargon.html

http://cuke4ninja.com/chp_feature_files.html

http://specificationbyexample.com/key_ideas.html





http://dannorth.net/introducing-bdd/

http://dannorth.net/introducing-bdd/

http://www.methodsandtools.com/archive/archive.php?id=72



http://watirmelon.files.wordpress.com/2011/05/specificationbyexamplealovestory1.pdf







