com.tngtech.jgiven.annotation
Annotation Type Table

@Documented
@Retention(value=RUNTIME)
@Target(value=PARAMETER)
public @interface Table

Marks the parameter of a step method as a data table. Such parameters are represented as tables in the report.

Only parameters that implement Iterable or arrays can be treated as data tables. The elements can either be again Iterable instances the data for each row of the table.

Note, that in that case the first list is taken as the header of the table if the columnTitles() are not set.

Elements can also be plain POJOs, in which case the field names become the headers and field values the data.

Example

Some POJO

class CoffeeWithPrice {
         String name;
         double price_in_EUR;
         CoffeeWithPrice(String name, double priceInEur) {
            this.name = name;
            this.price_in_EUR = priceInEur;
         }
     }
 

The Step Method

public SELF the_prices_of_the_coffees_are( @Table CoffeeWithPrice... prices ) {
         ...
     }
 

Invocation of the step method

given().the_prices_of_the_coffees_are(
         new CoffeeWithPrice("Espresso", 2.0),
         new CoffeeWithPrice("Cappuccino", 2.5));
 

Text Report

Given the prices of the coffees are

          | name       | price in EUR |
          +------------+--------------+
          | Espresso   | 2.0          |
          | Cappuccino | 2.5          |


 

Since:

0.6.1

Optional Element Summary

java.lang.String[]	columnTitles Explicitly specifies column titles of table header.
java.lang.String[]	excludeFields Specifies which fields should be excluded in the report.
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	transpose Whether to transpose the resulting table in the report or not.

header

public abstract Table.HeaderType header

Specifies the header type of the table. Default is 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

This simply specifies the the table has no header. The plain text report will produce the following output.

     | a1 | a2 | a3 |
     | b1 | b2 | b3 |
     | c1 | c2 | c3 |
 

HeaderType.HORIZONTAL

Specifies that the first row represents the header.

     | a1 | a2 | a3 |
     +----+----+----+
     | b1 | b2 | b3 |
     | c1 | c2 | c3 |
 

HeaderType.VERTICAL

Specifies that the first column represents the header. Thus elements a1, b1, and c1. The plain text report will produce the same output as for header type NONE, however, the HTML report will render the first column as a header.

     | a1 | a2 | a3 |
     | b1 | b2 | b3 |
     | c1 | c2 | c3 |
 

HeaderType.BOTH

Specifies that the first row and the first column are headers. The plain text report will produce the same output as for header type HORIZONTAL, however, the HTML report will render the first row and the first column as headers.

     | a1 | a2 | a3 |
     +----+----+----+
     | b1 | b2 | b3 |
     | c1 | c2 | c3 |
 

Effect on POJO lists

When the data is given by a list of POJOs then setting the header type to 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
Then the report will present the following table

| name         | Espresso | Cappuccino |
     | price in EUR | 2.0      | 2.5        |
 

The header type BOTH cannot be applied to POJO lists

Returns:

the header type of the table.

Default:

com.tngtech.jgiven.annotation.Table.HeaderType.HORIZONTAL

transpose

public abstract boolean transpose

Whether to transpose the resulting table in the report or not.

Example

Given the following data.

 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 |
 

Default:

false

excludeFields

public abstract java.lang.String[] excludeFields

Specifies which fields should be excluded in the report.

If includeFields() is set, then this attribute has no effect

Makes only sense when supplying a list of POJOs or a single POJO.

Default:

{}

includeFields

public abstract java.lang.String[] includeFields

Specifies which fields should be included in the report. All fields not in this list will be excluded.

Makes only sense when supplying a list of POJOs or a single POJO.

Default:

{}

columnTitles

public abstract java.lang.String[] columnTitles

Explicitly specifies column titles of table header.

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.

Example

Given the following table argument:

 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 |
 

Since:

0.7.1

Default:

{}

includeNullColumns

public abstract boolean includeNullColumns

Whether or not columns with only null values are shown or not. Default is to not show them.

Since:

0.7.1

Default:

false