1. Overview
Cucumber is a Behavioral Driven Development (BDD) framework that allows developers to create text-based test scenarios using the Gherkin language.
In many cases, these scenarios require mock data to exercise a feature, which can be cumbersome to inject — especially with complex or multiple entries.
In this tutorial, we’ll look at how to use Cucumber data tables to include mock data in a readable manner.
2. Scenario Syntax
When defining Cucumber scenarios, we often inject test data used by the rest of the scenario:
Scenario: Correct non-zero number of books found by author
Given I have the a book in the store called The Devil in the White City by Erik Larson
When I search for books by author Erik Larson
Then I find 1 book
2.1. Data Tables
While inline data suffices for a single book, our scenario can become cluttered when adding multiple books.
To handle this, we create a data table in our scenario:
Scenario: Correct non-zero number of books found by author
Given I have the following books in the store
| The Devil in the White City | Erik Larson |
| The Lion, the Witch and the Wardrobe | C.S. Lewis |
| In the Garden of Beasts | Erik Larson |
When I search for books by author Erik Larson
Then I find 2 books
We define our data table as a part of our Given clause by indenting the table underneath the text of the Given clause. Using this data table, we can add an arbitrary number of books — including only a single book — to our store by adding or removing rows.
Additionally, data tables can be used with any clause — not just Given clauses.
2.2. Including Headings
It’s clear that the first column represents the title of the book, and the second column represents the author of the book. The meaning of each column is not always so obvious, though.
When clarification is needed, we can include a header by adding a new first row:
Scenario: Correct non-zero number of books found by author
Given I have the following books in the store
| title | author |
| The Devil in the White City | Erik Larson |
| The Lion, the Witch and the Wardrobe | C.S. Lewis |
| In the Garden of Beasts | Erik Larson |
When I search for books by author Erik Larson
Then I find 2 books
While the header appears to be just another row in the table, this first row has a special meaning when we parse our table into a list of maps in the next section.
3. Step Definitions
After creating our scenario, we implement the Given step definition.
In the case of a step that contains a data table, we implement our methods with a DataTable argument:
@Given("some phrase")
public void somePhrase(DataTable table) {
// ...
}
The DataTable object contains the tabular data from the data table we defined in our scenario as well as methods for transforming this data into usable information. Generally, there are three ways to transform a data table in Cucumber: (1) a list of lists, (2) a list of maps and (3) a table transformer.
To demonstrate each technique, we’ll use a simple Book domain class:
public class Book {
private String title;
private String author;
// standard constructors, getters & setters ...
}
Additionally, we’ll create a BookStore class that manages Book objects:
public class BookStore {
private List<Book> books = new ArrayList<>();
public void addBook(Book book) {
books.add(book);
}
public void addAllBooks(Collection<Book> books) {
this.books.addAll(books);
}
public List<Book> booksByAuthor(String author) {
return books.stream()
.filter(book -> Objects.equals(author, book.getAuthor()))
.collect(Collectors.toList());
}
}
For each of the following scenarios, we’ll start with a basic step definition:
public class BookStoreRunSteps {
private BookStore store;
private List<Book> foundBooks;
@Before
public void setUp() {
store = new BookStore();
foundBooks = new ArrayList<>();
}
// When & Then definitions ...
}
3.1. List of Lists
The most basic method for handling tabular data is converting the DataTable argument into a list of lists.
We can create a table without a header to demonstrate:
Scenario: Correct non-zero number of books found by author by list
Given I have the following books in the store by list
| The Devil in the White City | Erik Larson |
| The Lion, the Witch and the Wardrobe | C.S. Lewis |
| In the Garden of Beasts | Erik Larson |
When I search for books by author Erik Larson
Then I find 2 books
Cucumber converts the above table into a list of lists by treating each row as a list of the column values.
So, Cucumber parses each row into a list containing the book title as the first element and the author as the second:
[
["The Devil in the White City", "Erik Larson"],
["The Lion, the Witch and the Wardrobe", "C.S. Lewis"],
["In the Garden of Beasts", "Erik Larson"]
]
We use the asLists method — supplying a String.class argument — to convert the DataTable argument to a List<List<String>>. This Class argument informs the asLists method what data type we expect each element to be.
In our case, we want the title and author to be String values, so we supply String.class:
@Given("^I have the following books in the store by list$")
public void haveBooksInTheStoreByList(DataTable table) {
List<List<String>> rows = table.asLists(String.class);
for (List<String> columns : rows) {
store.addBook(new Book(columns.get(0), columns.get(1)));
}
}
We then iterate over each element of the sub-list and create a corresponding Book object. Lastly, we add each created Book object to our BookStore object.
If we parsed data containing a heading, we would skip the first row since Cucumber does not differentiate between headings and row data for a list of lists.
3.2. List of Maps
While a list of lists provides a foundational mechanism for extracting elements from a data table, the step implementation can be cryptic. Cucumber provides a list of maps mechanism as a more readable alternative.
In this case, we must provide a heading for our table:
Scenario: Correct non-zero number of books found by author by map
Given I have the following books in the store by map
| title | author |
| The Devil in the White City | Erik Larson |
| The Lion, the Witch and the Wardrobe | C.S. Lewis |
| In the Garden of Beasts | Erik Larson |
When I search for books by author Erik Larson
Then I find 2 books
Similar to the list of lists mechanism, Cucumber creates a list containing each row but instead maps the column heading to each column value.
Cucumber repeats this process for each subsequent row:
[
{"title": "The Devil in the White City", "author": "Erik Larson"},
{"title": "The Lion, the Witch and the Wardrobe", "author": "C.S. Lewis"},
{"title": "In the Garden of Beasts", "author": "Erik Larson"}
]
We use the asMaps method — supplying two String.class arguments — to convert the DataTable argument to a List<Map<String, String>>. The first argument denotes the data type of the key (header) and second indicates the data type of each column value. So, we supply two String.class arguments because our headers (key) and title and author (values) are all Strings.
Then we iterate over each Map object and extract each column value using the column header as the key:
@Given("^I have the following books in the store by map$")
public void haveBooksInTheStoreByMap(DataTable table) {
List<Map<String, String>> rows = table.asMaps(String.class, String.class);
for (Map<String, String> columns : rows) {
store.addBook(new Book(columns.get("title"), columns.get("author")));
}
}
The final (and most rich) mechanism for converting data tables to usable objects is to create a TableTransformer.
A TableTransformer is an object that instructs Cucumber how to convert a DataTable object to the desired domain object:
Let’s see an example scenario:
Scenario: Correct non-zero number of books found by author with transformer
Given I have the following books in the store with transformer
| title | author |
| The Devil in the White City | Erik Larson |
| The Lion, the Witch and the Wardrobe | C.S. Lewis |
| In the Garden of Beasts | Erik Larson |
When I search for books by author Erik Larson
Then I find 2 books
While a list of maps, with its keyed column data, is more precise than a list of lists, we still clutter our step definition with conversion logic.
Instead, we should define our step with the desired domain object (in this case, a BookCatalog) as an argument:
@Given("^I have the following books in the store with transformer$")
public void haveBooksInTheStoreByTransformer(BookCatalog catalog) {
store.addAllBooks(catalog.getBooks());
}
To do this, we must create a custom implementation of the TypeRegistryConfigurer interface.
This implementation must perform two things:
- Create a new TableTransformer implementation
- Register this new implementation using the configureTypeRegistry method
To capture the DataTable into a useable domain object, we’ll create a BookCatalog class:
public class BookCatalog {
private List<Book> books = new ArrayList<>();
public void addBook(Book book) {
books.add(book);
}
// standard getter ...
}
To perform the transformation, let’s implement the TypeRegistryConfigurer interface:
public class BookStoreRegistryConfigurer implements TypeRegistryConfigurer {
@Override
public Locale locale() {
return Locale.ENGLISH;
}
@Override
public void configureTypeRegistry(TypeRegistry typeRegistry) {
typeRegistry.defineDataTableType(
new DataTableType(BookCatalog.class, new BookTableTransformer())
);
}
//...
And then we’ll implement the TableTransformer interface for our BookCatalog class:
private static class BookTableTransformer implements TableTransformer<BookCatalog> {
@Override
public BookCatalog transform(DataTable table) throws Throwable {
BookCatalog catalog = new BookCatalog();
table.cells()
.stream()
.skip(1) // Skip header row
.map(fields -> new Book(fields.get(0), fields.get(1)))
.forEach(catalog::addBook);
return catalog;
}
}
}
Note that we’re transforming English data from the table, and we therefore return the English locale from our locale() method. When parsing data in a different locale, we must change the return type of the locale() method to the appropriate locale.
Since we included a data table header in our scenario, we must skip the first row when iterating over the table cells (hence the skip(1) call). We would remove the skip(1) call if our table did not include a header.
By default, the glue code associated with a test is assumed to be in the same package as the runner class. Therefore, no additional configuration is needed if we include our BookStoreRegistryConfigurer in the same package as our runner class.
If we add the configurer in a different package, we must explicitly include the package in the @CucumberOptions glue field for the runner class.
4. Conclusion
In this article, we looked at how to define a Gherkin scenario with tabular data using a data table.
Additionally, we explored three ways of implementing a step definition that consumes a Cucumber data table.
While a list of lists and a list of maps suffice for basic tables, a table transformer provides a much richer mechanism capable of handling more complex data.
The complete source code of this article can be found over on GitHub.
