Tabular Parameters

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

Given the traders: 
|Larry|Stooge 3|
|Moe|Stooge 1|
|Curly|Stooge 2|
When Traders are subset to ".*y" by name
Then the traders returned are:
|Larry|Stooge 3|
|Curly|Stooge 2|

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:

Then the traders activity is: 

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:

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:

|name |rank    |
|Larry|Stooge 3|
|Moe  |Stooge 1|
|Curly|Stooge 2|

Specifying inlined separators

The separators are also configurable via inlined properties:

!header 1!header 2! .... !header n!
!-- An ignored row --!
!value 11#comment in value!value 12! .... !value 1n!
!-- Another ignored row --!
!value m1!value m2! .... !value mn!

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:

|header |
|value 1|
|NULL   |
|value 3|

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:

|header 1|value 11| ... | value m1|
|header n|value 1n| .... !value mn!
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:
{propertyKey=\{innerKey1=innerValue1\, innerKey2=innerValue2\}}

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.