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:
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:
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.