introduce columnTitles attribute for the @Table annotation

jgiven-core/src/main/java/com/tngtech/jgiven/annotation/Table.java

@@ -10,7 +10,9 @@
  * <p>
  * Only parameters that implement {@link java.lang.Iterable} or arrays can be treated as data tables.
  * The elements can either be again {@link java.lang.Iterable} instances the data for each row
- * of the table. Note, that in that case the first element is taken as the header of the table.
+ * of the table.
+ * <p>
+ * Note, that in that case the first list is taken as the header of the table if the {@link Table#columnTitles()} are not set.
  * <p>
  * Elements can also be plain POJOs, in which case the field names become the headers and field values the data.
  * <p>
@@ -50,6 +52,7 @@
  *
  * }</pre>
  *
+ * @since 0.6.1
  */
 @Documented
 @Retention( RetentionPolicy.RUNTIME )
@@ -175,6 +178,39 @@
      */
     String[] includeFields() default {};
 
+    /**
+     * Explicitly specifies column titles of table header.
+     * <p>
+     * The first row of the data is <b>not</b> taken as the header row if this attribute is set.
+     * <p>
+     * When a list of POJOs is given as parameter then this overrides the default behavior of taking
+     * 
+     * <h2>Example</h2>
+     * Given the following table argument:
+     * <pre>
+     * {@code new Object[][] {
+     *     { "a1", "a2", "a3" },
+     *     { "b1", "b2", "b3" },
+     *     { "c1", "c2", "c3" }}
+     * }
+     * </pre>
+     * Then the {@link #columnTitles()} attribute is set as follows:
+     * <pre>
+     * columnTitles = { "t1", "t2", "t3" }    
+     * </pre>
+     * Then the resulting table will look as follows
+     * <pre>
+     *     | t1 | t2 | t3 |
+     *     +----+----+----+
+     *     | a1 | a2 | a3 |
+     *     | b1 | b2 | b3 |
+     *     | c1 | c2 | c3 |
+     * </pre>
+     * 
+     * @since 0.7.1
+     */
+    String[] columnTitles() default {};
+
     public enum HeaderType {
         /**
          * The table has no header

jgiven-core/src/main/java/com/tngtech/jgiven/report/model/StepFormatter.java

@@ -133,6 +133,10 @@ public static DataTable toTableValue( Object tableValue, Table tableAnnotation )
             first = false;
         }
 
+        if( tableAnnotation.columnTitles().length > 0 ) {
+            result.add( 0, Arrays.asList( tableAnnotation.columnTitles() ) );
+        }
+
         result = tableAnnotation.transpose() ? transpose( result ) : result;
         return new DataTable( tableAnnotation.header(), result );
     }
@@ -142,7 +146,12 @@ static DataTable pojosToTableValue( Iterable<?> objects, final Table tableAnnota
 
         Object first = objects.iterator().next();
         Iterable<Field> fields = getFields( tableAnnotation, first );
-        list.add( getFieldNames( fields ) );
+
+        if( tableAnnotation.columnTitles().length > 0 ) {
+            list.add( Arrays.asList( tableAnnotation.columnTitles() ) );
+        } else {
+            list.add( getFieldNames( fields ) );
+        }
 
         for( Object o : objects ) {
             list.add( toStringList( ReflectionUtil.getAllFieldValues( o, fields, "" ) ) );

jgiven-core/src/test/java/com/tngtech/jgiven/format/StepFormatterTest.java

@@ -146,7 +146,7 @@ public void testToTableValue() {
         tableAnnotation = new TableAnnotation();
         tableAnnotation.includeFields = new String[] { "fieldA" };
         assertThat( StepFormatter.toTableValue( new AnotherPojo(), tableAnnotation ).getData() )
-            .containsExactly(Arrays.asList("fieldA"), Arrays.asList("test"));
+            .containsExactly( Arrays.asList( "fieldA" ), Arrays.asList( "test" ) );
 
         // single POJO transposed
         tableAnnotation = new TableAnnotation();
@@ -160,6 +160,12 @@ public void testToTableValue() {
         assertThat( StepFormatter.toTableValue( new TestPojo(), tableAnnotation ).getData() )
             .containsExactly( Arrays.asList( "x", "5" ), Arrays.asList( "y", "6" ) );
 
+        // single POJO columnTitles set
+        tableAnnotation = new TableAnnotation();
+        tableAnnotation.columnTitles = new String[] { "t1", "t2" };
+        assertThat( StepFormatter.toTableValue( new TestPojo(), tableAnnotation ).getData() )
+            .containsExactly( Arrays.asList( "t1", "t2" ), Arrays.asList( "5", "6" ) );
+
         // string array
         assertThat( StepFormatter.toTableValue( new String[][] { { "1" } }, new TableAnnotation() ).getData() )
             .containsExactly( Arrays.asList( "1" ) );
@@ -186,5 +192,24 @@ public void testToTableValue() {
                 Lists.newArrayList( "1", "2" ),
                 Lists.newArrayList( "3", "4" ) )
             );
+
+        tableAnnotation = new TableAnnotation();
+        tableAnnotation.columnTitles = new String[] { "t1", "t2" };
+        assertThat( StepFormatter.toTableValue( new Object[][] { { 1, 2 }, { 3, 4 } }, tableAnnotation ).getData() )
+            .isEqualTo( Lists.newArrayList(
+                Lists.newArrayList( "t1", "t2" ),
+                Lists.newArrayList( "1", "2" ),
+                Lists.newArrayList( "3", "4" ) )
+            );
+
+        tableAnnotation = new TableAnnotation();
+        tableAnnotation.columnTitles = new String[] { "t1", "t2" };
+        tableAnnotation.transpose = true;
+        assertThat( StepFormatter.toTableValue( new Object[][] { { 1, 2 }, { 3, 4 } }, tableAnnotation ).getData() )
+            .isEqualTo( Lists.newArrayList(
+                Lists.newArrayList( "t1", "1", "3" ),
+                Lists.newArrayList( "t2", "2", "4" ) )
+            );
+
     }
 }

jgiven-core/src/test/java/com/tngtech/jgiven/format/TableAnnotation.java

@@ -10,6 +10,7 @@ public class TableAnnotation implements Table {
     boolean transpose = false;
     String[] excludeFields = {};
     String[] includeFields = {};
+    String[] columnTitles = {};
 
     @Override
     public HeaderType header() {
@@ -31,6 +32,11 @@ public String[] includeFields() {
         return includeFields;
     }
 
+    @Override
+    public String[] columnTitles() {
+        return columnTitles;
+    }
+
     @Override
     public Class<? extends Annotation> annotationType() {
         return null;

jgiven-examples/src/test/java/com/tngtech/jgiven/examples/datatable/DataTableExamples.java

@@ -20,6 +20,11 @@ public DataTableStage a_list_of_lists_is_used_as_parameter(
             return self();
         }
 
+        public DataTableStage a_list_of_lists_is_used_as_parameter_with_column_titles(
+                @Table( columnTitles = { "Name", "Email" } ) List<List<String>> table ) {
+            return self();
+        }
+
         public DataTableStage a_list_of_POJOs_is_used_as_parameters(
                 @Table TestCustomer... testCustomer ) {
             return self();
@@ -58,6 +63,15 @@ public void a_list_of_list_can_be_used_as_table_parameter() {
             );
     }
 
+    @Test
+    public void a_list_of_list_can_be_used_as_table_parameter_and_column_titles_can_be_set() {
+        given().a_list_of_lists_is_used_as_parameter_with_column_titles(
+            asList(
+                asList( "John Doe", "[email protected]" ),
+                asList( "Jane Roe", "[email protected]" ) )
+            );
+    }
+
     @Test
     public void a_list_of_POJOs_can_be_represented_as_data_tables() {
         given().a_list_of_POJOs_is_used_as_parameters(