liveBook · Manning

Introduce and refer pattern

As explained in Effective Behavior-Driven Development

A narrative pattern that distinguishes introducing a new entity from referring to an existing entity through specific natural-language phrases.

When a scenario mentions several entities of the same kind, readers can lose track of which one a step means. The Introduce and Refer pattern distinguishes a new entity from an existing one by giving them different natural-language phrases. section 13.3

Use the pattern when a scenario follows a particular actor, entity, or concept across multiple steps. This keeps the scenario readable and makes use of its execution context more consistent. section 13.3

Track the order

Introduce an order with “the customer has placed an order.” Later, refer to it as “the order” or “the placed order.” If the customer re-orders an existing order, call the result “the new order” to distinguish it. section 13.3

Table 13.2 Sample step text for introducing and referring to entities in a scenario
Introduction step
Refer to it later as
Given the customer has placed an order
the order, the placed order
Given the customer is authenticated
the customer, the authenticated customer
When the customer searches for “Margherita”
search result
When the customer selects the first order
the order
Given there is an existing fulfilled order
the order, the existing order, the fulfilled order
When the customer re-orders the existing order
the new order

Compare introduction phrases with later references for orders, customers, and search results. section 13.3

How Effective Behavior-Driven Development covers it

How deep it goes
Defines phrase conventions and connects entity references to scenario context and custom parameter types.
Examples
Uses orders, authenticated customers, search results, and re-orders to illustrate entity introductions and references.
What you can do after
Apply the pattern to make scenarios easier to read and scenario-context use more consistent.
How it connects
Connects scenario context with BDD scenarios and the Local Scenario Context, Shareable Scenario Context, and Entity Selector patterns.

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.