Data‑Driven API Testing with Karate’s Scenario Outline

Problem: Repetitive API Tests

When validating a REST endpoint that accepts a query parameter, teams often copy‑paste the same scenario for each test value. This leads to large feature files, harder maintenance, and a higher chance of forgetting to update one of the copies when the request changes.

Thesis: Scenario Outline Keeps Tests DRY

Karate DSL’s Scenario Outline lets you define a single scenario template with placeholders (<variable>) and feed it data from an Examples table. Each row becomes an independent test iteration, complete with its own name in logs and reports, while sharing the same step definitions.

Worked Example: Data‑Driven GET Search

Imagine you need to verify that the /search endpoint returns the correct number of results for three different keywords. The following feature file shows how to do this without duplication.

Feature: Search API validation

  Background:
    * url 'https://api.example.com'

  Scenario Outline: Search with keyword
    Given path 'search'
    And param q = ''
    When method get
    Then status 200
    And match response.total == 

  Examples:
    | keyword | expectedTotal |
    | apple   | 12            |
    | banana  | 7             |
    | cherry  | 3             |

To run the feature, ensure you have Java 11+ and Maven (or Gradle) configured with the Karate dependency. Execute from the project root:

mvn test -Dkarate.options="--tags @search"

If you prefer the standalone JAR:

java -jar karate.jar -t search my-search.feature

During execution you will see console output similar to:

• scenario outline - 1
• scenario outline - 2
• scenario outline - 3

Each line corresponds to a row in the Examples table. Open the generated HTML report (karate-summary.html) and you will find three distinct test cases, each showing the request URL with the correct q parameter and the asserted total value.

Trade‑Offs and Limitations

While Scenario Outline reduces boilerplate, consider these points:

• Execution cost: Every row triggers a full scenario run. Very large tables (hundreds of rows) can increase total test time and memory consumption. For massive datasets, externalize the data with read('data.csv') and loop via for each or a Java utility.
• Placeholder scope: Placeholders cannot appear inside multi‑line doc strings (""") or within expressions that are evaluated before substitution (e.g., #(someVar)). Move complex payload construction to a Background step or a separate function if needed.
• Reporting granularity: Karate automatically names iterations, but if you need custom identifiers (e.g., test‑case IDs), add a column like testId and reference it in a * print step or a custom header.

Actionable Closing

Start small: pick one endpoint that you currently test with multiple hard‑coded values, replace those scenarios with a Scenario Outline, and verify the three‑iteration output as shown above. Monitor test execution time; if it grows beyond acceptable limits, migrate the data source to an external CSV or JSON file and use Karate’s read() function. This approach keeps your test suite readable, maintainable, and fast.