Behavior Scenarios

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

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 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

Behavior Scenarios

Gherkin or Given / When / Then language

Step Phrasing

Real World Example

Further Reading