liveBook · Manning

Parameter type

As explained in Effective Behavior-Driven Development

A user-defined parameter type that matches captured text and converts it into a value for a step definition.

A team wants its pizza scenarios to say “14-inch pizza” rather than “large pizza.” The wording is clearer to the business, but an inch value is not an enumeration value that the automation tool can convert automatically. A custom parameter type keeps the domain wording in the scenario and converts the captured text into the value a step definition needs. section 14.4

A parameter type is a named placeholder in a Cucumber Expression. Built-in placeholders such as {string} and {int} capture common forms of text. A custom one defines which domain-specific text to match and how to turn it into a typed argument. For example, {pizza-size} can accept 10", 12", or 14" and pass a PizzaSize value to the ordering step. section 12.3.3 section 14.4

Listing 14.16 Define a pizza-size parameter type
*** Features/Ordering.feature ***
Rule: More than 4 large pizzas cannot be delivered as a single order
  Scenario: Five large pizzas are ordered
    ...
    When the customer places an order for 5 pizzas of size 14"

*** Support/CustomParameterTypes.cs ***
[StepArgumentTransformation("(10\"|12\"|14\")", Name = "pizza-size")]
public PizzaSize ConvertPizzaSize(string pizzaSizeString) =>
  pizzaSizeString switch
  {
    "10\"" => PizzaSize.Small,
    "12\"" => PizzaSize.Medium,
    "14\"" => PizzaSize.Large,
    _ => throw new FormatException($"Invalid size: {pizzaSizeString}")
  };

*** StepDefinitions/OrderingStepDefinitions.cs ***
[When(
  "the customer places an order for {int} pizza(s) of size {pizza-size}")]
public void WhenTheCustomerPlacesAnOrderFor(int count, PizzaSize pizzaSize)
{
  var order = new OrderObjectMother()
    .WithItems(count, size: pizzaSize)
    .Build();
  ...
}

The scenario uses an inch value, the custom parameter type converts it, and the step definition receives a PizzaSize. section 14.4

In Reqnroll, a method marked [StepArgumentTransformation] registers the conversion. Its regular expression specifies the accepted text; capture groups supply arguments to the conversion method. The method belongs in a [Binding] class. An explicit Name sets the placeholder name; without one, Reqnroll uses the return type’s name. Keeping conversions in a separate support class avoids burying them in individual step definitions. section 12.3.4

The same technique can support natural references such as “they” alongside “the authenticated customer.” Use these references carefully: matching is context-insensitive, so “it” may be ambiguous when a customer can cancel both an order and a promotion. Nor should flexible matching conceal inconsistent business terms. section 13.3.1 section 12.3.3

Keep the matching easy to reason about:

  • Prefer simple parameter definitions and step expressions over intricate combinations. Multiple possible matches cause an ambiguous-step error; no match causes an undefined-step error. section 12.3.5
  • Use built-in conversion when it expresses the domain value clearly; introduce a custom parameter type when the wording needs its own matching and conversion. section 14.4

How Effective Behavior-Driven Development covers it

How deep it goes
Works through a pizza-size conversion and specifies Reqnroll registration, naming, regular expressions and capture groups; cautions against complicated matching.
Examples
Uses inch-based pizza sizes, color names and RGB values, and pronouns referring to an authenticated customer.
What it assumes
Builds on Cucumber Expressions and step definitions while introducing custom registration through a worked example.
What you can do after
Apply it via Reqnroll to match domain-specific scenario wording and convert captured text into typed step arguments.
How it connects
Links Cucumber Expressions, step definitions, regular expressions, built-in parameter conversion, domain terminology and ambiguous step matching.

Also explained in

Compare how 2 books explain parameter type →

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.