Add matrix support

[cathaysia]

Hello, I'm currently using scenario outlines for parameterized testing. However, I need to manually generate matrices for each combination.

This is not only tedious but also error-prone. It would be great if behave supported matrices.

possible germmar:

# -- file:features/xxx.feature
Feature:
  Scenario Outline: Wow            # line 2
    Given an employee "<name>" with age "<birthyear>"

    Matrix: Araxas
      name: ["alice", "bob"]
      birthyear: [1985, 1975]

[cathaysia]

As background, my scenario has four functional items, each with enable/disable states.

Manually combining them would require listing 16 possibilities. Using a matrix significantly improves both workload and readability.

[luke-hill]

This already exists as a data-table / examples table. Data-tables return a hash with or without headers. Examples tables will iterate once per scenario

# -- file:features/xxx.feature
Feature:
  Scenario Outline: Wow            # line 2
    Given an employee "<name>" with age "<birthyear>"

    Examples
      | name  | birthyear |
      | alice | 1985      |
      | bob   | 1975      |

[mpkorstanje]

To verify that something supports a Cartesian product of two collections, you'd write that down in your scenario and implement the actual logic it in your step definition. For example:

  Scenario: The frobulator supports all
    Given these widgets
      | name |
      | A    |
      | B    |
      | C    |
      | D    |
    And these states
      | name     |
      | enabled  |
      | disabled |  
    Then the frobulator accepts the carthesian product of widgets and states

Or more concisely:

  Scenario: The frobulator supports all
    * The frobulator accepts the Carthesian product of widget and state
          | widget | state    |
          | A      | enabled  |
          | B      | disabled |  
          | C      |          |
          | D      |          |

Then in your step definition you would convert the data table to a list of widgets and a list of states, then take the Carthesian product of those. Then for each item you would test if the combination works.

import com.google.common.collect.Sets;
import io.cucumber.datatable.DataTable;
import io.cucumber.java.en.When;

import java.util.List;
import java.util.Objects;
import java.util.stream.Collectors;

import static org.assertj.core.api.Assertions.assertThatNoException;

public class StepDefinitions {

    @When("The frobulator accepts the Carthesian product of widget and state")
    public void the_forbulator_accepts_all(DataTable table) {
        var widgets = table.column(0).stream().filter(Objects::nonNull).collect(Collectors.toSet());
        var states = table.column(1).stream().filter(Objects::nonNull).collect(Collectors.toSet());

        var product = Sets.cartesianProduct(widgets, states);

        product.forEach((List<String> testCase) -> {
            String widgetName = testCase.get(0);
            String state = testCase.get(1);
            the_forbulator_accepts_widget_with_satate(widgetName, state);
        });
    }

    private void the_forbulator_accepts_widget_with_satate(String widgetName, String state) {
        var widget = given_a_widget(widgetName);
        apply_state_to_widget(widget, state);

        assertThatNoException()
                .describedAs("Frobulator accepts " + widgetName + " with state " + state)
                .isThrownBy(() -> forbulator.accept(widget));
    }
    
    ...
}

This all happens in a single step because, presumably you've already written out a more detailed example for a single widget and state and you don't want to bore your readers. But remember that you you can still call other steps programmatically from inside a step so you can reuse your existing step definitions that way.