Cucumber provides a powerful mechanism for running parameterized tests using the @CucumberParams annotation, enabling users to feed data dynamically into their tests. This allows for running the same scenario with different sets of input values, which is ideal for testing a variety of conditions without duplicating test code.

Starting from the latest version (3.1.2), @CucumberParams supports multiple data sources, including CSV, Excel, and Java Method Source.

Supported Data Source Types

The data source is defined using the sourceType attribute:

public enum DataSourceType {
    CSV,
    EXCEL,
    METHOD
}

Each source type has its own configuration requirements, described below.

Project Configuration Overview

The configuration is divided into three main parts:

• JUnit Test Configuration
• Scenario Feature Configuration
• Data Source Configuration (CSV / Excel / Method)

JUnit Test Configuration

Mandatory Extension (Required for ALL data sources)

The following extension must be added to the test class for all data source types:
@ExtendWith({CucumberParamsIterationExtension.class})

1️⃣ CSV Data Source (File-Based)

To use parameterized tests with a CSV file, first create a well-structured CSV file containing the test data.

Example CSV file:

username,password,age
user1,123,21
user2,456,34
user3,789,55

Pass the file path to the annotation:

@CucumberParams(
    sourceType = DataSourceType.CSV,
    filePath = "src/test/resources/ScenarioExample.csv"
)

Test Example:

@ParameterizedTest
@CucumberParams(
    sourceType = DataSourceType.CSV,
    filePath = "src/test/resources/ScenarioExample.csv"
)
public void example1(String username, String password, String age) {
    executeTest(
        new Scenario("example of UI scenario test"),
        new FeatureFile("exampleCucumber"),
        new Dictionary("UI")
    );
}

ℹ️ Info: Special Characters in CSV file Values
If a value contains a comma (,), it must be escaped using \:
price
15,000$

NEW – Inline CSV Source (csvSource)

It is now possible to define CSV data directly inside the annotation, without using an external file.

This is especially useful for:

• Small datasets
• Self-contained tests
• Improved readability and portability

Inline CSV Example:

@ParameterizedTest
@CucumberParams(
    sourceType = DataSourceType.CSV,
    csvSource = {
        "username,password,price",
        ",123,'15,000'",
        "user2,456,45000",
        "user3,789,37000"
    }
)
public void cucumberParameterizedTest(
        String username,
        String password,
        String price
) {
    // test implementation
}

Notes:

• The first row is treated as the header
• Values containing commas must be wrapped in quotes
• Empty values are supported
• Parsing behavior is aligned with JUnit's @CsvSource

2️⃣Excel Data Source

For Excel-based data, both filePath and sheetName must be provided:

@CucumberParams(
    sourceType = DataSourceType.EXCEL,
    filePath = "src/test/resources/data.xlsx",
    sheetName = "Sheet1"
)

• filePath – the relative path to the Excel file.
• sheetName – the exact name of the sheet containing the test data.

The first row in the Excel sheet must contain column headers, which are used as parameter keys and must match the placeholders defined in the feature file (e.g. <username>, <password>).

3️⃣ Method Source Data Provider (NEW)

You can now provide test data directly from a Java method using sourceType = METHOD.

This approach is useful when:

• Data is generated dynamically
• CSV / Excel files are not desired
• Logic-based data preparation is required

Method Source Example:

public class TestData {

    public static List<Arguments> dataProvider() {
        return List.of(
            Arguments.of("username", "password", "price"),
            Arguments.of("aUser", "123456", "60010"),
            Arguments.of("bUser", "345678", "60020"),
            Arguments.of("cUser", "976544", "60030")
        );
    }
}

Test Usage:

@ParameterizedTest
@CucumberParams(
    sourceType = DataSourceType.METHOD,
    methodSource = "co.verisoft.TestData#dataProvider"
)
public void exampleWithMethodSource(String username, String password, String price) {
    executeTest(
        new Scenario("example scenario using method source"),
        new FeatureFile("exampleCucumber"),
        new Dictionary("UI")
    );
}

Notes:

• The method must be static

• Supported return types:

  • Stream<Arguments>
  • Collection<Arguments>
  • Arguments[]

• Method Source Resolution (Important)
  When the method source is located in a different class, the method must be referenced using a Fully Qualified Method Name, exactly like JUnit’s native @MethodSource.
  Format:

<package>.<ClassName>#<methodName>

Example:

methodSource = "co.verisoft.TestData#dataProvider"

This behavior is equivalent to:

@MethodSource("co.verisoft.TestData#dataProvider")

If the method is located in the same test class, you may use the method name only:

methodSource = "dataProvider"

Scenario Feature Configuration

To enable parameterization in a feature file, parameters must be defined using angle brackets (< >).
Each parameter name must exactly match the column header (CSV / Excel) or the key provided by the method source.

Feature File Example:

Scenario: example of UI scenario test
  Then user Login to the website "<username>""<password>""<age>"

Execution Behavior

• The scenario runs once per data set (row / record / method invocation)
• Data is injected dynamically into the scenario
• Example: 3 data sets → scenario runs 3 times

Summary

The enhanced @CucumberParams annotation now provides a unified and flexible mechanism for parameterized Cucumber tests, supporting:

• CSV files
• Inline CSV values (NEW)
• Excel files
• Java Method Sources

This design enables clean test code, reusable data providers, and scalable test scenarios across different data sources.

ℹ️ Info: Parameterized Cucumber tests support String-based parameters only, and these parameters must be used exclusively in steps or statements that accept Stringvalues.