Step Arguments

There are a number of situations where data will be extracted from a feature file and passed to a step as an argument, typically as either Examples table data, docstrings or a datatable.

These arguments wil be passed to step the step function callback parameter.

Cucumber Expressions

Cucumber Expressions are a novel way of matching string, substrings or custom types with identifiers.

For example taking the following Gherkin steps:

Given a user Johnny
Given a user Paul
Given an age 24
Given an age 32

We can match these with

Given("a user {word}", (name: string) => {});
Given("an age {int}", (age: number) => {});

Notice the argument types: cucumber expressions automatically cast their match to an appropriate type. A word remains a string, while an int is converted to a number.

Custom Parameter Types

On top of the parameter types provided by Cucumber, a number of custom types are defined and available for use:

• boolean
  • Matches a boolean value
  • values: true | false
  • example: `Given('a {boolean} value', (bool: boolean)=>console.log(bool));
• bool
  • alias of boolean
• number
  • Matches an integer or float value
  • values: any numeric value
  • example: `Given('a {number} value', (num: number)=>console.log(num));
• words
  • Matches multiple alphabetic words with spaces between them
  • values: any numeric value
  • example: `Given('a {number} value', (bool: number)=>console.log(bool));
  • warning: this is a very broad matcher. Use with caution.

Defining Custom Paramters

You can define your own custom parameters using the defineParameterType function. It takes a spread array of parameter type definition objects. A good place to call this function is your autometa.config.ts file.

defineParameterType(
  {
    name: "boolean",
    regex: /true|false/,
    type: Number,
    transform: (value): boolean => {
      if (value === "true") {
        return true;
      }
      if (value === "false") {
        return false;
      }
      throw new Error("Unknown boolean " + value);
    },
  },
  {
    name: "number",
    regex: FLOAT_REGEXP,
    type: Number,
    transform: (value) => {
      const transformed = Number(value);
      if (isNaN(transformed)) {
        throw new Error(`${value} can not be transformed into a number`);
      }
      return transformed;
    },
  }
);

Regular Expressions

Regular Expressions work similar to cucumber expressions but of course using RegEx matchers. Regex Matches are not converted to a new type and will be passed as strings. Cucumber expressions are recommended over Regular Expressions.

Examples Table

Step text in a Scenario Outline may contain angle brackets representing a value of the Examples table. At run time, for each row of examples, the value in the angle bracket will be replaced by its matching examples value. This value can be extracted as normal using Cucumber Expressions.

Gherkin

Feature: My Feature
    Scenario outline:
        Given a <color> <object>
    Examples
        | color | object |
        | blue  | ball   |
        | red   | truck  |

Typescript

import { Feature, Given } from "@autometa/cucumber-runner";

Feature(() => {
  Given("a {word} {word}", (color: string, object: string) => {
    console.log(color); // blue, red
    console.log(object); // ball, truck
  });
}, "./my-feature.feature");

Datatables

See Datatables

Docstring

A docstring is attached to a step with three quotation marks

Given a step with a docstring
 """
    This is my docstring
 """

Docstrings can also contain a mimetype

Given a step with a docstring
 """json
    { a: 1, b: [2,3] }
 """

If a docstring is defined, it will always be passed as the second to last argument and has type Docstring.

A docstring cannot be defined when a data table is defined. They are mutually exclusive.