Package com.tngtech.jgiven.annotation

Annotation Interface Table

@Documented @Retention(RUNTIME) @Target({PARAMETER,ANNOTATION_TYPE}) public @interface Table
Marks the parameter of a step method as a data table. Such parameters are represented as tables in the report.

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

Example

Some POJO

 {
        @code
        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

  • Element Details

    • header

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

    • transpose

      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

      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

      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

      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

      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

    • numberedRows

      boolean numberedRows
      Automatically number the rows of the table Default is not to generate one.

      If the table has a horizontal header, the generated column has header '#'. To use a different header use numberedRowsHeader().

      Since:
      0.8.2
      Default:
      false

    • numberedRowsHeader

      String numberedRowsHeader
      Like numberedRows() but specifies a different header for the generated column. This implicitly sets to true.

      Note that in case the table has no horizontal header a will be thrown if this value is set.

      Since:
      0.8.2
      Default:
      "MARKER FOR ABSENT VALUES IN ANNOTATIONS - JGIVEN INTERNAL DO NOT USE!"

    • numberedColumns

      boolean numberedColumns
      Automatically number the columns of a table Default is not to generate one.

      If the table has a vertical header, the generated row has header '#'. To use a different header use numberedColumnsHeader().

      Since:
      0.8.2
      Default:
      false

    • numberedColumnsHeader

      String numberedColumnsHeader
      Like numberedColumns() but specifies a different header for the generated row. This implicitly sets to true.

      Note that in case the table has no vertical header a will be thrown if this value is set.

      Since:
      0.8.2
      Default:
      "MARKER FOR ABSENT VALUES IN ANNOTATIONS - JGIVEN INTERNAL DO NOT USE!"

    • formatter

      Class<? extends TableFormatterFactory> formatter
      The formatter to use to translate the parameter object to a table. If you only want to override how POJOs are formatted you should use the objectFormatting() or rowFormatter() attribute.
      Since:
      0.10.0
      Default:
      com.tngtech.jgiven.format.table.DefaultTableFormatter.Factory.class

    • objectFormatting

      Table.ObjectFormatting objectFormatting
      How to format rows when the rows are plain Objects, i.e. no Iterables. Note that this setting is ignored if a different 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.
      Since:
      0.10.0
      Default:
      FIELDS

    • rowFormatter

      Class<? extends RowFormatterFactory> rowFormatter
      Specifies a factory to create a custom RowFormatter that is used to format POJOs each row of the table.

      The default implementation evaluates the objectFormatting() attribute and creates a corresponding RowFormatter

      Since:
      0.10.0
      Default:
      com.tngtech.jgiven.format.table.DefaultRowFormatterFactory.class

    • fieldsFormatSetAnnotation

      Class<? extends Annotation> fieldsFormatSetAnnotation
      Specify a custom NamedFormats annotation

      The NamedFormat defined in this set will be used when formatting POJOs fields.

      Default:
      java.lang.annotation.Annotation.class

    • fieldsFormat

      NamedFormat[] fieldsFormat
      Specify an array of NamedFormat to use when formatting POJOs fields.

      When a NamedFormat.name() matches a field name, field value is formatted using this NamedFormat.

      Note : when set, has precedence over fieldsFormatSetAnnotation()

      Default:
      {}