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 or Given / When / Then language
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.
Step Phrasing
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 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.
Real World Example
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 label exactly one agent link of a resource as primary,
so that it 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 it should only be viewable on the edit view of a (Resource
| Digital Object | Accession | Resource Component | Digital Object Component)
Rule: Either none or just one agent can be marked as primary on a resource. That
agent appears as a 1xx field in the MARCXML export of that resource
Scenario: As a staff User, I want 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
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 exports the resource to MARCXML
Then no 1xx field appears in the MARCXML export of that resource
Scenario: As a staff User, I want to be allowed to mark maximum one agent as primary
on a Resource, so that the rule of having a single 1xx field in the MARCXML
export of that resource is followed.
Given the user edits a resource
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 third 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 on the third agent
And the third agent appears as the unique 1xx field on the MARCXML export of that resource
A more detailed article on how to write good Behavior Scenarios can be found here.