@Documented
@Retention(value=RUNTIME)
@Target(value={PARAMETER,ANNOTATION_TYPE})
public @interface Table
In principle, every object can be represented as a table. However, JGiven treats certain types of objects in a special way.
If a parameter implements the Iterable
or is an instance of an array then each element of
the Iterable is interpreted as a single row of the table. Otherwise JGiven will only create a single row.
The elements are again interpreted differently whether they are instances of Iterable
or not.
If the elements are instances of Iterable then each element becomes a cell in the row.
Note that the first list is taken as the header of the table if the columnTitles()
is not set.
If the elements are not instances of Iterable, the field names become the headers and field values the data.
This can be overridden by the objectFormatting()
attribute.
It is also possible to completely replace the way JGiven translates arguments to tables by using the formatter()
attribute
class CoffeeWithPrice {
String name;
double price_in_EUR;
CoffeeWithPrice(String name, double priceInEur) {
this.name = name;
this.price_in_EUR = priceInEur;
}
}
public SELF the_prices_of_the_coffees_are( @Table CoffeeWithPrice... prices ) {
...
}
given().the_prices_of_the_coffees_are(
new CoffeeWithPrice("Espresso", 2.0),
new CoffeeWithPrice("Cappuccino", 2.5));
Given the prices of the coffees are
| name | price in EUR |
+------------+--------------+
| Espresso | 2.0 |
| Cappuccino | 2.5 |
Modifier and Type | Optional Element and Description |
---|---|
java.lang.String[] |
columnTitles
Explicitly specifies column titles of table header.
|
java.lang.String[] |
excludeFields
Specifies which fields should be excluded in the report.
|
java.lang.Class<? extends TableFormatterFactory> |
formatter
The formatter to use to translate the parameter object to a table.
|
Table.HeaderType |
header
Specifies the header type of the table.
|
java.lang.String[] |
includeFields
Specifies which fields should be included in the report.
|
boolean |
includeNullColumns
Whether or not columns with only
null values are shown or not. |
boolean |
numberedColumns
Automatically number the columns of a table
Default is not to generate one.
|
java.lang.String |
numberedColumnsHeader
Like
numberedColumns() but specifies a different header
for the generated row. |
boolean |
numberedRows
Automatically number the rows of the table
Default is not to generate one.
|
java.lang.String |
numberedRowsHeader
Like
numberedRows() but specifies a different header
for the generated column. |
Table.ObjectFormatting |
objectFormatting
How to format rows when the rows are plain Objects, i.e.
|
java.lang.Class<? extends RowFormatterFactory> |
rowFormatter
Specifies a factory to create a custom
RowFormatter
that is used to format POJOs each row of the table. |
boolean |
transpose
Whether to transpose the resulting table in the report or not.
|
public abstract Table.HeaderType header
HORIZONTAL
.
That is explained best by an example.
Given the following table argument:
new Object[][] {
{ "a1", "a2", "a3" },
{ "b1", "b2", "b3" },
{ "c1", "c2", "c3" }}
Then the header type argument has the following effect.
HeaderType.NONE
| a1 | a2 | a3 | | b1 | b2 | b3 | | c1 | c2 | c3 |
HeaderType.HORIZONTAL
| a1 | a2 | a3 | +----+----+----+ | b1 | b2 | b3 | | c1 | c2 | c3 |
HeaderType.VERTICAL
| a1 | a2 | a3 | | b1 | b2 | b3 | | c1 | c2 | c3 |
HeaderType.BOTH
| a1 | a2 | a3 | +----+----+----+ | b1 | b2 | b3 | | c1 | c2 | c3 |
VERTICAL
will also
transpose the table. For example
Given the following POJO list.
new CoffeeWithPrice[] {
new CoffeeWithPrice("Espresso", 2.0),
new CoffeeWithPrice("Cappuccino", 2.5)}
When setting the header type to VERTICAL
| name | Espresso | Cappuccino |
| price in EUR | 2.0 | 2.5 |
The header type BOTH
cannot be applied to POJO lists
public abstract boolean transpose
new Object[][] {
{ "a1", "a2", "a3" },
{ "b1", "b2", "b3" },
{ "c1", "c2", "c3" }}
When transpose is set to true
Then the table in the report will look as follows:
| a1 | b1 | c1 | +----+----+----+ | a2 | b2 | c2 | | a3 | b3 | c3 |instead of
| a1 | a2 | a3 | +----+----+----+ | b1 | b2 | b3 | | c1 | c2 | c3 |
public abstract java.lang.String[] excludeFields
If includeFields()
is set, then this attribute has no effect
Makes only sense when supplying a list of POJOs or a single POJO.
public abstract java.lang.String[] includeFields
Makes only sense when supplying a list of POJOs or a single POJO.
public abstract java.lang.String[] columnTitles
The first row of the data is not taken as the header row if this attribute is set.
When a list of POJOs is given as parameter then this overrides the default behavior of taking the field names as table headers.
new Object[][] {
{ "a1", "a2", "a3" },
{ "b1", "b2", "b3" },
{ "c1", "c2", "c3" }}
Then the columnTitles()
attribute is set as follows:
columnTitles = { "t1", "t2", "t3" }Then the resulting table will look as follows
| t1 | t2 | t3 | +----+----+----+ | a1 | a2 | a3 | | b1 | b2 | b3 | | c1 | c2 | c3 |
public abstract boolean includeNullColumns
null
values are shown or not.
Default is to not show them.public abstract boolean numberedRows
If the table has a horizontal header, the generated column has header '#'.
To use a different header use numberedRowsHeader()
.
public abstract java.lang.String numberedRowsHeader
numberedRows()
but specifies a different header
for the generated column. This implicitly sets numberedRows()
to true
.
Note that in case the table has no horizontal header a JGivenWrongUsageException
will be thrown if this value is set.
public abstract boolean numberedColumns
If the table has a vertical header, the generated row has header '#'.
To use a different header use numberedColumnsHeader()
.
public abstract java.lang.String numberedColumnsHeader
numberedColumns()
but specifies a different header
for the generated row. This implicitly sets numberedColumns()
to true
.
Note that in case the table has no vertical header a JGivenWrongUsageException
will be thrown if this value is set.
public abstract java.lang.Class<? extends TableFormatterFactory> formatter
objectFormatting()
or rowFormatter()
attribute.public abstract Table.ObjectFormatting objectFormatting
rowFormatter()
is set.
In addition, JGiven will automatically switch to the Table.ObjectFormatting.PLAIN
formatter when there is an additional formatting annotation besides the @Table
annotation.public abstract java.lang.Class<? extends RowFormatterFactory> rowFormatter
RowFormatter
that is used to format POJOs each row of the table.
The default implementation evaluates the objectFormatting()
attribute and
creates a corresponding RowFormatter