Diagnosing Cucumber Scenario Outline Parameter Failures

Problem: Scenario Outline Fails to Execute as Expected

When implementing data-driven tests using a Scenario Outline, you may encounter symptoms where the test logic does not iterate through the data as intended. Common indicators include:

• Only a single scenario executes despite multiple rows in the Examples table.
• Step definitions throw errors stating a placeholder was not found or substituted.
• Test reports show a single generic scenario entry rather than distinct entries for each data row.

These issues typically stem from Gherkin syntax errors, case-sensitivity mismatches between headers and placeholders, or incorrect block indentation.

Diagnostic Table

Symptom	Possible Cause	Diagnostic Check
Only one scenario runs	Examples table missing or empty	Verify the Examples: block contains at least one data row beneath the header.
Placeholder-not-found error	Mismatched placeholder name or missing column header	Confirm every <placeholder> matches a column header exactly (case-sensitive).
All scenarios fail immediately	Gherkin syntax error in Examples block	Run the runner in dry-run mode to identify parsing errors before execution.
Report shows generic scenario	Incorrect indentation or missing header	Ensure Examples: is aligned with the Scenario Outline keyword.
CI pipeline timeout/failure	Combinatorial explosion	Count the rows in the Examples table; excessive rows can overwhelm CI resources.

Ordered Checks and Fixes

1. Validate Gherkin Syntax via Dry Run
   

   Run the runner in dry-run mode to catch syntax problems without executing the underlying code. Commands vary by implementation:

   • Ruby: cucumber --dry-run path/to/feature.feature
   • JVM (Maven): mvn test -Dcucumber.dry-run=true
   • JavaScript: npx cucumber-js --dry-run path/to/feature.feature

   If the dry run fails, check for missing pipes (|) or misaligned table columns.

2. Verify Examples Table Structure
   

   Ensure the Examples: keyword is present and followed by a header row and at least one data row. Example:

   Examples:
   | product | price |
   | Widget  | 10.00 |
   | Gizmo   | 15.50 |
   

   If the table is empty or the header is missing, the runner may skip the scenario or throw a runtime error.

3. Audit Placeholder Matching
   

   Placeholders must be wrapped in angle brackets (<name>). Check that the string inside the brackets matches the column header exactly. For example, <Product> will not match a column named product.

4. Check Background Block Constraints
   

   If a Background block is used, ensure it does not attempt to use placeholders from the Examples table. In most Cucumber implementations, placeholders are only substituted within the Scenario Outline steps, not the Background steps.

5. Manage Data Volume
   

   To prevent CI resource exhaustion from large tables, use tags to isolate data subsets:

   • Apply a tag to the Scenario Outline (e.g., @smoke).
   • Run specific subsets using --tags @smoke.
   • Split large datasets across multiple feature files.

Concrete Example

The following is a functional Scenario Outline. When executed, it should produce two distinct test results based on the Examples table.

Feature: Shopping cart

  Scenario Outline: Add a product to the cart
    Given I am on the product page for <product>
    When I click "Add to cart"
    Then the cart should contain <product> priced at <price>

  Examples:
    | product | price |
    | Widget  | 10.00 |
    | Gizmo   | 15.50 |

Verification: Run the feature and inspect the generated report. You should see two entries: one for "Widget" and one for "Gizmo".

Escalation Criteria

If the following conditions persist after applying the fixes, escalate to the test architecture team:

• Placeholder errors persist despite verified case-sensitive matches between headers and steps.
• The number of executed scenarios does not match the row count in the Examples table, and no tags are filtering the run.
• The runner crashes during the parsing phase of a large Examples table regardless of the dry-run result.

When escalating, provide the feature file, the runner version (e.g., Cucumber-JVM 7.x), and the specific error log from the dry-run.

Limitations and Practical Check

• Data Types: Examples tables only support plain-text. Complex objects must be handled via custom transformation logic in step definitions.
• Header Uniqueness: Duplicate column headers are not permitted and will cause parsing failures.

Final Check: Run the feature in dry-run mode. If no syntax errors are reported and a subsequent full run generates a report with one scenario per data row, the configuration is correct.