A scenario may describe useful behavior even when automating it would be premature. For example, if the way a blocklist is uploaded may change, the team can keep the scenario and label it @manual. The label records how the scenario will be tested without putting that decision into steps about the system’s behavior. section 9.13
A Gherkin tag is text preceded by @. Tags annotate and group parts of a feature file; they are not predefined commands. Teams choose their meanings, so a label such as @manual needs a shared definition. Because feature files are business-readable documentation, tags should make sense to stakeholders as well as to automation tools. section 9.13 section 10.4
Listing 9.23 Tagging a scenario
@manual Scenario: Upload replacement blocklist Given a manually created blocklist defined using names, emails and phone ➥ numbers When the blocklist is uploaded Then the upload should replace the existing blocklist
See how @manual sits immediately above a scenario whose expected behavior remains in its Given, When, and Then steps. section 9.13
Use a tag when its label helps readers find a scenario or understand how it is handled:
- Group related scenarios for selection or reporting: @fast can identify a quick-feedback subset, while @pricing can identify scenarios relevant to a business area. section 10.5
- Mark unfinished automation with agreed labels such as @formulated or @inprogress, so expected failures do not obscure results from completed scenarios. section 10.5.1
- Record an external work-item identifier only when that connection will be useful; otherwise it adds distraction without improving understanding. section 10.5.2
- Keep automation-related labels understandable to stakeholders. @browser may express an execution need; a low-level implementation label may make the scenario harder to discuss. section 10.5.3
Tags can be placed on a feature, rule, scenario, scenario outline, or examples block. A feature or rule tag applies to its scenarios and scenario outlines; an examples-block tag applies to scenarios generated from that block. Multiple tags are allowed, but each is case-sensitive and cannot contain whitespace. Choose labels for a clear purpose, document their meaning, and avoid decorating scenarios with tags that only the toolchain understands. section 9.13 section 10.5
