Tabular Parameters

Scenario writers may want to express parameters in a tabular structure. For example:

JBehave supports multi-line parameters out-of-the-box and the user only needs to declare the parameter type as ExamplesTable for it to be automatically parsed as a tabular structure:

Parametrised tables

Sometimes, you may want to parametrise the table row values and replace them with named parameters, e.g. as specified in the Examples table and changing for each parametrised scenario:

The ExamplesTable provide an option to specify whether the named parameters should be replaced in the values when retrieving the rows as parameters:

Row values as converted parameters

Besides retrieveing the row values as String name-value pairs, the user retrieve them as Parameters, which allow the values to converted to the desidered type, using the same ParameterConverters defined in the stories configuration:

In order not to repeat values in tabular structures, defaults are supported that allow re-use of previous defined tables:

In this example, the row parameters are the union (for the corresponding row number) of the ranks and activity tables. Note that any existing value in the row map of data will not be overridden.

Finally, the Parameters facade also allows for specification of a default value if the parameter name is not found:

Mapping parameters to custom types

It may sometime be useful to map the table row parameters to a custom object. This can be done by annotating the type with the AsParameters annotation:

The fields can be optionally mapped to the parameter names via the Parameter annotation.

If not present, the default mapping will use the name of fields to match the name of the parameters.

Once we've defined our custom parameters type, we can inject it in a method requiring one or more of these types:

If we cannot control the custom type, e.g. we want to map to a type contained in a third-party library, we can still achieve the mapping programmatically:

Convert row to type using custom converter

It may sometime be useful to map the whole row to a custom object using custom converter rather than relying on field to field mapping

Given the following class that we want to convert from Parameter

Create parameter converter for the Person class, please do not forget to register converter in ParameterConverters

Use as(java.lang.reflect.Type) method to perform the conversion

Preserving whitespace

By default, value in the table are trimmed, i.e. any preceding and trailing whitespace is removed. This is the most useful and common usecase. If, for some reason, you need to preserve the whitespace, you can specify an optional parsing property:

Specifying inlined separators

The separators are also configurable via inlined properties:

Mapping values to null-s

By default all empty values in ExamplesTable are treated as empty strings. However it might be required to map certain values to null-s. It can be done at the step implementation level or by applying the generic approach at the table level:

Using values with line breaks

Line break is a default separator for rows in ExamplesTable, that's why they can't be added as is to the data. In order to put the value with line breaks to ExamplesTable escape sequences (a character preceded by a backslash (\) is an escape sequence) must be used.

Escape Sequence	Description
\n	Insert a newline in the value at this point.
\r	Insert a carriage return in the text at this point.
\\	Insert a backslash character in the text at this point.

Inlined property processEscapeSequences defines whether escape sequences should be replaced in the data. It’s false by default (no property is declared explicitly). The allowed values are true and false, any other values are considered invalid and will lead to exception thrown at parsing.

Using table transformers

Table transformers allow the table to be transformed via an inlined property. E.g. to transform from a landscape table form we can to use the pre-registered transformer:

Or one can define our own custom transformer Also chain of transformers can be defined. In this case the transformers are applied sequentially from top to bottom. In this case the custom transformer needs to be registered by name with the TableTransformers via the ExamplesTableFactory:

The custom table factory then needs to be configured to used by the parameter converters and the story parser:

In addition, there is the possibility to escape commas and braces in transformer properties:

Loading tabular parameter from an external resource

The tabular parameter can also be loaded from an external resource, be it a classpath resource or a URL.

Inlined properties can be applied to the tabular parameter loaded from an external resource

We need to enable theExamplesTable parameter converter to find the resource with the appropriate resource loader configured via the ExamplesTableFactory

:

Modifying content of tabular parameter

When using ExamplesTable to process tabular parameter data, it may be useful to allow additions of columns to the table for a given row, e.g. to express a result value for given row. The non-affected rows would then be given default blank values for the new column.

Equally, we may want to start from the content data (list of maps) and create a new table with modified content.

Once modified, the table can be written to an output:

In other words, ExamplesTable can be used for both the string->content and the content->string transformations when implementing a step with tabular parameters.

Under the hood, JBehave users the same table parsing functionality of the parametrised scenarios, but there is a fundamental difference between these two use cases: with parametrised scenarios, the scenario is run for each line of the table (using in each execution the parameter values of the given row), while in using tabular parameters we are simply using the tabular structure as a parameter, and how this structure is interpreted is up to the scenario writer. The difference is in the Examples: keyword, which is only present for parametrised scenarios.

Working with self-referencing rows in example table

By default, JBehave does not support self-referencing relationship in example table rows (when a column value in a row relates to another column in the same row). To resolve such mechanism can be used the transformer for resolving self references which must first be registered in your Configuration:

Usage example:

The transformer enables resolution of references to one column from another column within the one row of the example table. Circular references will result in error.
The table from the example above will be transformed into the following: