Using Karate Scenario Outline and Examples for Data‑Driven Testing

Quick answer

Karate lets you run the same test steps with many data sets by using a Scenario Outline paired with an Examples table. Each row in the table creates a separate scenario instance, substituting the placeholders (e.g., <username>) with the row’s values. This avoids duplicating steps while giving you distinct reporting for each iteration.

Worked example

Suppose you want to verify a login API returns success for several credential pairs. The feature file below shows a single outline that is executed once per row in the Examples table.

Feature: Login API validation

  Scenario Outline: Login with credentials
    Given url 'https://example.com/api/login'
    And request { username: '', password: '' }
    When method post
    Then status 200
    And match response == { success: true }
    # optional: print the substituted values for debugging
    And print 'Running with username:', username

  Examples:
    | username | password |
    | alice    | secret1  |
    | bob      | secret2  |
    | carol    | secret3  |

When Karate processes this file, it treats the outline as a template and generates three internal scenarios: one where username = alice and password = secret1, another for bob/secret2, and a third for carol/secret3.

Running and verifying

To execute the feature, use either Maven or the Karate CLI. Ensure you have read access to the project directory and the ability to run Java/Maven.

• Maven (from the project root):

  mvn test

• Karate CLI (if you have the standalone jar):

  java -jar karate.jar path/to/login.feature

During execution you should see console output similar to the following (the exact wording depends on your logger configuration):

• Lines showing the substituted values, e.g., Running with username: alice
• Separate pass/fail lines for each iteration in the JUnit or Cucumber report.

To confirm that each row ran independently, add a * print step (as shown) or inspect the report: each iteration will appear as a distinct test case with its own name derived from the outline and the row’s values.

Limits

• Each row in the Examples table creates a full scenario instance. Very large tables can increase total execution time and memory consumption proportionally.
• Karate does not support nested Examples tables or dynamic generation of rows at runtime; the data set must be static when the feature is parsed.
• Complex JSON or XML objects placed directly in the table make the feature hard to read and can cause parsing errors if they contain characters like pipes (|) or quotes.

Common mistakes and how to avoid them

• Mismatched placeholder names – The placeholder inside angle brackets must match the column header exactly, including case. <Username> will not substitute a column named username. Fix: keep names identical and use lowercase for consistency.
• Quotes inside table cells – Including quotes as part of a value (e.g., "secret") can break the pipe‑delimited parsing. Fix: omit surrounding quotes; Karate treats the cell as a raw string.
• Shared state between rows – Cookies, headers, or variables defined with * def outside the scenario are retained across iterations unless cleared. This can cause false positives. Fix: call * reset() at the start of the outline or place state‑setting steps inside the scenario so each run begins clean.
• Logging sensitive data – Values from the Examples table appear in console output and test reports. Fix: mask or externalize credentials (e.g., read from environment variables) and avoid placing secrets directly in the table.