Readability and Maintainability

Writing Good Cucumber Well

Readability

Maintainability

Features/Scenarios

Step Definitions

Data Objects

Page Objects

TestFactoryWatir

SeleniumRuby

● Feature● Summary● Scenario

Cucumber’s Parts

● Feature● Summary● Scenario

Cucumber’s Parts

“What is the point?”“Why is this a feature?”“Who is going to care?”

● We are all QA

● If it’s not readable no one will read it● “Living” requirements documentation● Ubiquitous language

Theme: Effective Communication

Why “Readable” Cucumber?

Write a scenario without thinking about...● User Interface● The needs of the Ruby code

Instead, pretend you’re talking to a SME

(Be okay with getting it wrong the first time, because you will)

The Basic Approach

Ask yourself this question:

“If the entire system were scrapped and re-written from scratch, what is the likelihood that this

Feature/Scenario would survive in its present form?”

The Basic Approach

Unit Tests● Fields allowing certain character sets● Select lists containing expected values● Document IDs unique

User Interface Tests● Element alignments● Usability considerations

Performance Tests● Page loading● Server calls

Cucumber is not suited for...

I create a proposal

Declarative versus Imperative

I go to the login pageI enter my user nameI enter my passwordI click the login buttonI click the “Create Proposal” linkI click the “expand all” buttonI type “Title” in the title fieldI select “New” in the Type selection listI type “00340” in the Sponsor Code fieldI type today’s date into the Start Date fieldI type tomorrow’s date into the End Date fieldI click on the save button

...

I create a proposal

Declarative In Detail

in the BL-BL unitwith a 5-year budgetwith a Federal sponsorwithout a PIstarting next yearhaving a sponsor deadline

Given a particular system state

When a specific event occurs

Then a new state is expected

● Everything needed for the test/requirement to be valid is spelled out concisely

● Everything not needed is left out

● The point is explicit● The expected/desired outcome

is comprehensible● Remember that the user has

some goal in mind--some reason for using the software

Given/When/Then

Scenario: Create Proposal with Invalid SponsorGiven a user exists with the role Proposal CreatorWhen the proposal creator creates a proposal with an invalid sponsorThen an error should say that a valid sponsor is required

Scenario: Adding an F&A rate to an AwardGiven a User exists with the role Award ModifierAnd the Award Modifier creates an AwardWhen the Award Modifier adds an F&A rate to the AwardThen the default start and end dates are based on the F&A rate's fiscal year

Scenario: Protocol submitted to a Committee with submission date restrictionsGiven users exist with the roles IRB Administrator and Protocol CreatorAnd the IRB Admin submits a committee with events scheduled before and after its adv submission days settingAnd the Protocol Creator creates an IRB Protocol in the committee's home unitWhen the Protocol is being submitted to the committee for reviewThen the earliest available schedule date is based on the committee's Adv Submission Days value

Examples - Scenario Title

Given I am logged in as "@PersonX@"And I attempt to view the portal pageWhen I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to "@project_code.project-manager-principal@"And I set Chart Code to "@project_code.chart-code@"And I set Organization Code to "@project_code.org-code@"And I submit the documentAnd I acknowledge the document as "@project_code.reviewer1@"And I acknowledge the document as "@project_code.reviewer2@"Then it should go to a Final Status

Example - Yikes!

Given I am logged in as "@PersonX@"And I attempt to view the portal pageWhen I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to "@project_code.project-manager-principal@"And I set Chart Code to "@project_code.chart-code@"And I set Organization Code to "@project_code.org-code@"And I submit the documentAnd I acknowledge the document as "@project_code.reviewer1@"And I acknowledge the document as "@project_code.reviewer2@"Then it should go to a Final Status

Example - Yikes!

Only “@PersonX@”???

Seems like this, and the other “@” lines are sneaky bits of code, which is a no-no at the Scenario level!

Given I am logged in as an AdministratorAnd I attempt to view the portal pageWhen I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to a Project ManagerAnd I set Chart Code to a valid chart codeAnd I set Organization Code to a valid org codeAnd I submit the documentAnd I acknowledge the document as the first reviewerAnd I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

Given I am logged in as an AdministratorAnd I attempt to view the portal pageWhen I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to a Project ManagerAnd I set Chart Code to a valid chart codeAnd I set Organization Code to a valid org codeAnd I submit the documentAnd I acknowledge the document as the first reviewerAnd I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

How do you code for an “attempt”?

Why is “viewing” the portal page important for this scenario?

Given I am logged in as an AdministratorAnd I attempt to view the portal pageWhen I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to a Project ManagerAnd I set Chart Code to a valid chart codeAnd I set Organization Code to a valid org codeAnd I submit the documentAnd I acknowledge the document as the first reviewerAnd I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

Given I am logged in as an AdministratorWhen I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to a Project ManagerAnd I set Chart Code to a valid chart codeAnd I set Organization Code to a valid org codeAnd I submit the documentAnd I acknowledge the document as the first reviewerAnd I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

What is the pivotal, state-changing event in this scenario?

Given I am logged in as an AdministratorAnd I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to a Project ManagerAnd I set Chart Code to a valid chart codeAnd I set Organization Code to a valid org codeAnd I submit the documentAnd I acknowledge the document as the first reviewerWhen I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

Given I am logged in as an AdministratorAnd I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to a Project ManagerAnd I set Chart Code to a valid chart codeAnd I set Organization Code to a valid org codeAnd I submit the documentAnd I acknowledge the document as the first reviewerWhen I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

Why isn’t every bit of data in the test being remembered automatically?

Is it really important to explicitly state this stuff in the scenario?Also, these steps seem dangerously vague. Will they always work?

Given I am logged in as an AdministratorAnd I access the Project Code maintenance documentAnd I fill in a random DescriptionAnd I fill in a random Project NameAnd I fill in a random Project DescriptionAnd I fill in a random Project Code (and remember it)And I set Project Manager Principal Name to a Project ManagerAnd I set Chart Code to a valid chart codeAnd I set Organization Code to a valid org codeAnd I submit the documentAnd I acknowledge the document as the first reviewerWhen I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

Same goes with all of these guys.

Given I am logged in as an AdministratorAnd I submit a new project code maintenance documentAnd I acknowledge the document as the first reviewerWhen I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

Given I am logged in as an AdministratorAnd I submit a new project code maintenance documentAnd I acknowledge the document as the first reviewerWhen I acknowledge the document as the second reviewerThen it should go to a Final Status

Example - Yikes!

What should go to a final status?

Remember, step definitions are “global.”

Given I am logged in as an AdministratorAnd I submit a new project code maintenance documentAnd I acknowledge the document as the first reviewerWhen I acknowledge the document as the second reviewerThen the project code maintenance document’s status should be final

Example - Yikes?

Given I am logged in as an AdministratorAnd I submit a new project code maintenance documentAnd I acknowledge the document as the first reviewerWhen I acknowledge the document as the second reviewerThen the project code maintenance document’s status should be final

Example - Getting better

Not bad! But it can still be better...

Given an Administrator submits a new project code maintenance documentWhen first and second reviewers acknowledge the project code maintenance documentThen the project code maintenance document’s status should be final

Example - Ahhhhh... Much better

● Cucumber adds value when abstracted from the code● Scenarios should:

○ Model user behavior○ Validate something important to the user

● Avoid:○ Excessive detail and specificity○ UI references (“click”, “field”, “page”, etc.)○ Being too generic

● Final thought: Read The Cucumber Book

Summary