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:
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:
The 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:
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 tabular parameter con also be loaded from an external resource, be it a classpath resource or a URL.
We need to enable theExamplesTable parameter converter to find the resource with the appropriate resource loader configured via the ExamplesTableFactory:
Note: 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.