Gwen Gets Scenario Outlines

After some consideration, full support for scenario outlines has been added to gwen-web as of version 2.3.0 to give users more power and better support BDD.

Standard Execution

The following example shows a meta file that defines a step definition for joining two strings together and a feature file containing a scenario outline that exercises it with different string values.

Meta file:

Feature: Join Strings Meta

  @StepDef
  Scenario: I join the two strings
      Given the result is "${string 1}${string 2}"

Feature file:

Feature: Join Strings

  Scenario Outline: Joining <string 1> and <string 2> should yield <result>

    This scenario is evaluated at the point where the outline is declared.
    Joining <string 1> and <string 2> should yield <result>

    Given string 1 is "<string 1>"
      And string 2 is "<string 2>"
     When I join the two strings
     Then the result should be "<result>"

    Examples: Basic string concatenation

      The header row contains the placeholder names. The body rows that
      follow contain the data that is bound to each scenario that is evaluated.

      | string 1 | string 2 | result   |
      | howdy    | doo      | howdydoo |
      | any      | thing    | anything |

The Gwen interpreter will expand and evaluate each record in the body of the Examples table at the point where the scenario outline is declared in the feature. This example contains just one Examples clause in the outline but many can be specified.

Evaluated scenario outlines appear in HTML reports as follows.

Each Examples table record in the report (excluding the header) is rendered as a hyperlink that when hovered over and clicked will reveal the expanded scenario.

Outlines as StepDefs for Deferred Execution

For cases where you may want to reuse a scenario outline across many scenarios or features, you can make it a step definition in the meta and then call it by name in the feature where you want it to execute.

Meta file:

Feature: Join Strings Meta

  @StepDef
  Scenario: I join the two strings
      Given the result is "${string 1}${string 2}"

  @StepDef
  Scenario Outline: Joining <string 1> and <string 2> should yield <result>

    This outline is loaded into memory and execution is deferred until a call is made.
    Joining <string 1> and <string 2> should yield <result>

    Given string 1 is "<string 1>"
      And string 2 is "<string 2>"
     When I join the two strings
     Then the result should be "<result>"

    Examples: Basic string concatenation

      The header row contains the placeholder names. The body rows that
      follow contain the data that is bound to each scenario that is evaluated.

      | string 1 | string 2 | result   |
      | howdy    | doo      | howdydoo |
      | any      | thing    | anything |

Feature file:

Feature: Join Strings

  Scenario: Join different pairs of strings and compare their results
      Given Joining <string 1> and <string 2> should yield <result>

The Gwen interpreter will load the outline in the meta to memory and execute it when it is called by the scenario in the feature. Any number of scenarios in any features can call the outline in this way as long as the meta is in scope.

Calls to scenario outlines are rendered as steps in HTML reports (just like all calls to step definitions are).

When the step is hovered over and clicked, the called outline is revealed as a StepDef.

Each Examples table record in the report (excluding the header) is rendered as a hyperlink that when hovered over and clicked will reveal the expanded scenario.

Notes about outlines as StepDefs

• They are reusable
• They can be called from anywhere, including backgrounds and the REPL console too!
• If the name of the outline contains data placeholders, then their bound table values are substituted into the expanded scenario name prefixes at evaluation time. Specifying placeholders in the name is handy in this way but it is also optional. We could have named the outline ‘joining two strings should yield a compound string‘ instead and called it by that name if we wanted to. In this case the expanded scenarios would all have this same name prefix. Either way, the expanded scenarios will always be given unique names that are suffixed with the example record number (see report snapshots above). If you are using placeholders in the name though, then your call to the step definition should also include the same placeholder name literals (as shown in this example) to prevent potential name clashes with any other step definitions you may have with a similar name. If a name clash does occur, Gwen will report it and you will need to rename.

Advertisement