Best practices for scenario language

Title

Use a short label that provides a high-level description.
Avoid using CamelCase words without spaces in the title. For example, "Customer Service Rep" is preferred to "CustomerServiceRep".

Description

Put the description at the top of the file, immediately after the feature name.
Format the description using the following template:
- As a (role or persona)
- I want to (feature)

This approach helps to provide clarity on the user's identity, the reason for having the feature, and the feature's business value.

Limit each feature file to one persona. If the same behavior must be tested for multiple persons, create separate feature files for each persona. In this case, name each file feature_persona.feature. For example, RegionalFormat_CSR.feature.

Background

Provide context and incidental details for the scenario.
Write it so that it is common to most or all of the scenarios in the feature.
Make it as short as possible.
Limit each feature to only one background section.

Backgrounds ought to be used with caution. Keep in mind that that anyone reading the scenario must remember that there is background information at the beginning of the feature file that complements each scenario. Avoid moving information from scenario steps into the background if this makes the background less readable. It is preferable to have lines repeated in multiple scenarios than it is to have an unreadable background.

Scenario

Every scenario either:
- Tests one and only one behavior, or
- Is an end-to-end test that covers an entire workflow
Write and capitalize terms as they appear in the user interface. For example, refer to an activity's priority as "Low", "Normal", "High", or "Urgent".
If a given term does not appear consistently in the user interface:
- Use the version that best matches the industry standard, or
- Use the version that best matches the section of the user interface that is being tested, or
- Use the version that appears most often in the user interface
Avoid making references to specific user interface controls. Focus on behaviors (such as "When I complete the activity") as opposed to user interface elements (such as "When I click the Complete button").

Scenario title

Use short and objective descriptions that identify the general behavior.
Avoid repeating the primary persona, as this already appears in the feature description.
- However, if the action performed in a scenario requires a persona in addition to the one mentioned in the feature description, then it may be necessary to repeat the primary persona. For example, a scenario that tests a customer service representative behavior after supervisor approval has been granted may require explicit mention of the customer service representative.
Avoid using Gherkin keywords, such as "given", "when", and "then".
Avoid using words such as "verify", "assert", or "should". The scenario is testing a behavior, and therefore these types of words are redundant.

Given steps

Use affirmative statements to represent the initial state or precondition. For example, do this:
```
Given an activity
And the activity's priority is "Urgent"
```

Avoid the redundant phrases "there is", "there are", or "already". For example, avoid this:
```
Given there is already an activity
```

Avoid using actions or talking about user interactions with the system. For example, avoid this:
```
Given an activity
And I reassign it to the "supervisor"
```
Do this instead:
```
Given an activity
And the activity has been reassigned to the "supervisor"
```

When steps

Use an action verb
Use the present tense
Use active voice to clarify the person is the actor

Use the first person pronoun ("I") as needed to add clarity. For example, do this:

Given an activity
And the activity's priority is not "Urgent"
When I set the priority to "Urgent"

Then steps

Use "should" to make the Then step more assertive. For example:
```
Then the activity's status is "Complete"
```
Instead, do this:
```
Then the activity's status should be "Complete"
```