Scenario writers may want to express parameters in a tabular structure. For example:
Given the traders: |name|rank| |Larry|Stooge 3| |Moe|Stooge 1| |Curly|Stooge 2| When Traders are subset to ".*y" by name Then the traders returned are: |name|rank| |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:
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:
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: |name|trades| |Larry|3000| |Moe|1000| |Curly|2000|
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:
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:
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:
{trim=false}
|name |rank |
|Larry|Stooge 3|
|Moe |Stooge 1|
|Curly|Stooge 2|
The separators are also configurable via inlined properties:
{ignorableSeparator=!--,headerSeparator=!,valueSeparator=!,commentSeparator=#}
!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!
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:
{nullPlaceholder=NULL}
|header |
|value 1|
|NULL |
|value 3|
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. |
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.
{processEscapeSequences=true, commentSeparator=#}
|header |
|line 1\nline 2 |# The value with a newline
|line 1\r\nline 2|# The value with a carriage return and a newline
|line 1\\nline 2 |# The value with an escaped escape sequence, the result will be "line 1\nline 2"
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:
{transformer=FROM_LANDSCAPE}
|header 1|value 11| ... | value m1|
...
|header n|value 1n| .... !value mn!
Or one can define our own custom transformer
{transformer=FROM_MY_FORMAT}
...
Also chain of transformers can be defined. In this case the transformers are applied sequentially from top to bottom.
{transformer=FROM_LANDSCAPE}
{transformer=FROM_MY_FORMAT}
...
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\}}
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
: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.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:
TableTransformers.ResolvingSelfReferences resolvingSelfReferencesTransformer = new TableTransformers.ResolvingSelfReferences(parameterControls);
TableTransformers transformers = tableTransformers();
transformers.useTransformer("RESOLVING_SELF_REFERENCES", resolvingSelfReferencesTransformer);
Usage example:
{transformer=RESOLVING_SELF_REFERENCES}
|header1 |header2 |header3 |
|value1 |<header1>-value2 |<header2>-value3 |
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:
|header1 |header2 |header3 | |value1 |value1-value2 |value1-value2-value3 |