One or more Behavior Scenarios (also known as Use Cases or Usage Scenarios) are encouraged in a Feature Request in order to describe the requirements in an unambiguous and compact manner.
Feature requests that include detailed Behavior Scenarios or Use Cases can be more easily reviewed and are more likely to be prioritized for development since these use cases provide more detailed information about the requested feature and improve the likelihood of a successful outcome in development.
Gherkin, also known as Given / When / Then syntax, is a language for writing Behavior Scenarios. Gherkin is a plain-text language with a simple structure and is intended to be easy enough to learn for non-programmers while allowing the level of specificity required by developers to successfully develop a feature.
Gherkin scenarios are meant to be short and sound like plain English. Each scenario has the following structure:
Given some initial state
When an action is taken
Then an outcome is expected
Here is an example usage scenario in Given / When / Then syntax:
Feature: As a non-logged in user, I want to login, so that I can access restricted
functionality
Background: As the staff area of ArchivesSpace includes functions that need to be
available to staff personnel only, users should go through a login process
before accessing it.
Rule: Login is only possible with valid credentials
Scenario: Sucessful Log-in
Given a user has already created a staff account
When the user inputs their correct credentials in the login form
Then the user should be successfully logged in
Scenario: Attempt to Log-in with wrong password
Given a user has already created a staff account
When the user inputs their username correctly but their password is misspelled
Then the user should see a "Login attempt failed" message |
The most important keywords in Given / When / Then Syntax are:
Feature: a general description of the feature that usually includes multiple usage scenarios, preferably in the form: As a [persona], I [want to], [so that]
Background: an optional description of the background idea or context of the Feature
Rule: A rule can group multiple scenarios together, covering one aspect of the Feature
Scenario: a summary of the use case, preferably in the form: As a [persona], I [want to], [so that]
Given: some initial state
When: an action that triggers a response from the system
Then: an expected outcome
And: an additional step added after a Given, When, or Then
But: same function like And, just giving some more expression flexibility. But and And are interchangeable
Note that there is no “Or” step in Gherkin, each scenario is a sequence of steps describing a behavior. If an Or step seems necessary to describe another path in the sequence of events in a scenario, then it is probably better to add another scenario to describe the alternative path.
Given-When-Then steps must appear in order and cannot repeat. A Given may not follow a When or Then, and a When may not follow a Then. That is because any single When-Then pair denotes an individual behavior and each scenario covers one behavior.
Any time more than one When-Then pair seem necessary, separate scenarios should be written instead. Each scenario should describe a single behavior.
Here are some basic recommendations on how to write steps:
Write all steps in third-person. If first-person and third-person steps mix, scenarios become confusing.
Write all steps in order.
Write steps as a subject-predicate action phrase. Both passive and active voice can be used but be sure to write your scenario in a way that describes the intended action.
Include as much detail as possible: Do not leave out parts of the scenario for brevity. Do not assume that the reviewer is familiar with organization-specific workflows and processes. If the feature request impacts or is dependent on archival standards, include this information.
Use present tense for all step types to ensure that each step refers to an action that happens during the scenario and not something that should have happened already or will happen at some future time.
As an example the feature request ANW-504 could be further clarified with the following behavior scenarios:
Feature: As a staff user, I want to mark none or exactly one agent link of a resource as
primary, so that the primary agent appears as a 1xx field in MARCXML resource
exports.
Background: The primary agent should appear as a 1xx field in MARCXML exports.
It should not be viewable anywhere in the PUI.
On the SUI only viewable on the edit and show views of a Resource
| Digital Object | Accession | Resource Component | Digital Object Component
Rule: When no linked agent is marked as primary on a resource, no 1xx field appears in
the MARCXML export of that resource, and no agent link is marked as primary in
the show view of that Resource | Digital Object | Accession | Resource Component
| Digital Object Component on SUI.
Scenario: As a staff User, I want to be able to mark no agent as primary on a Resource so
that no primary agent appears in the show view of that resource
Given the user edits a resource on SUI
And the resource has three agent links (two creators and one subject)
But the user does not mark any of the three agents to be a primary agent
When the user opens the show view of that resource
Then no "primary" label appears next to any linked agent
Scenario: As a staff User, I want to be able to mark no agent as primary on a Resource so
that no 1xx field appears in the MARCXML export of that resource
Given the user edits a resource on SUI
And the resource has three agent links (two creators and one subject)
But the user does not mark any of the three agents to be a primary agent
When the user downloads a MARCXML export of that resource
Then no 1xx field appears in the MARCXML
Scenario: As a staff User, I want to be allowed to mark exactly one agent as primary
on a Resource
Given the user edits a resource on SUI
And the resource has three agent links (two creators and one subject)
And the second agent link is already marked as primary
When the user clicks on the "Make primary" button of the first agent
Then the "primary" label is removed from the second agent
And the "Make Primary" button appears on the second agent
And the "primary" label appears next to the first agent in the edit form
Scenario: As a staff user, I want to see a "primary" label next to the primary agent of a
resource, on the show view of the resource, so that it becomes clear that there
is a primary agent defined for that resource
Given a staff user marks an agent link as primary on a resource
When the user opens the show view for that resource
Then a "primary" label appears next to the agent link marked as primary
Scenario: As a staff user, I want to see a 1xx field for the primary agent in the MARCXML
export of a resource
Given a staff user marks an agent link as primary on a resource
When the user downloads a MARCXML export of that resource
Then a 1xx field appears in the MARCXML for the primary agent link |
A more detailed article on how to write good Behavior Scenarios can be found here.