Parameterizing Cucumber Steps with Data Tables in Java

Desired outcome

Use a Cucumber Data Table to feed multiple data rows into a single step definition, so the test iterates over each row without duplicating steps.

Prerequisites

• Cucumber‑JVM 6.x or later
• Java 8+ JDK
• Maven or Gradle build tool
• Step definition classes in the io.cucumber.java.en package

Procedure

1. Add the dependency (Maven example)

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>7.15.0</version>
    <scope>test</scope>
</dependency>

2. Write a feature step with a Data Table using pipe syntax.

Given I calculate the sum of the following numbers:
  | a | b |
  | 2 | 3 |
  | 5 | 7 |
  | -1 | 4 |

3. In the step definition, accept io.cucumber.datatable.DataTable and convert rows to a list of maps or POJOs.

@Given("I calculate the sum of the following numbers:")
public void calculateSum(DataTable table) {
    List> rows = table.asMaps(Integer.class, Integer.class);
    for (Map row : rows) {
        int a = row.get("a");
        int b = row.get("b");
        int sum = a + b;
        // Assume a helper method under test
        int result = Calculator.add(a, b);
        Assertions.assertEquals(sum, result, "Mismatch for a=" + a + " b=" + b);
    }
}

4. Run the test; Cucumber will execute the step once and iterate over each row internally.

Expected checks

• The console output shows the step executed once, with the data table printed (e.g., Given I calculate the sum of the following numbers: | a | b | ...).
• No UndefinedStep warnings appear.
• The build passes if all assertions succeed.
• In the Cucumber HTML report the step displays a table icon and each row is marked passed or failed individually.

Limitations and practical verification

• Header names must exactly match the keys used in asMaps; mismatched headers cause mapping errors.
• Avoid empty cells or extra whitespace around pipes; they can produce null values or parsing failures.
• To verify, run mvn test (or gradle test) and inspect the console for the step execution line. Then open target/cucumber-reports/cucumber.html (or the equivalent Gradle path) and confirm the step shows a table icon with per‑row status.

Recovery options

• If a single row fails, wrap the iteration in a try‑catch block, log the failing data, and continue so other rows still run.
• Alternatively, use Cucumber’s retry plugin to rerun failing scenarios.
• For more granular JUnit‑style reporting, convert the table to a list and drive the test with JUnit 5’s @ParameterizedTest instead of looping inside the step.