liveBook · Manning

Tag

As explained in Effective Behavior-Driven Development

An @-prefixed metadata label that annotates and categorizes Gherkin elements.

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

How Effective Behavior-Driven Development covers it

How deep it goes
Defines syntax, placement, inheritance, and naming constraints, then weighs several uses against readability; defers automation implementation.
Examples
Uses @manual on a blocklist-upload scenario, alongside @fast, @pricing, @formulated, and @inprogress as grouping or status labels.
What it assumes
Assumes familiarity with feature files and scenarios, but defines tag syntax and explains that teams choose tag meanings.
What you can do after
Operate/configure it: choose and document readable tags to group scenarios and distinguish unfinished automation from completed checks.
How it connects
Connects tags to feature files, scenario outlines, living documentation, continuous integration, and application lifecycle management.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Effective Behavior-Driven Development. The section links point to the parts of the book it draws on.