Parametrizing API Tests in Karate with Scenario Outline and Example Tables

The Problem With Repetitive API Tests

When testing an API that accepts different payloads or query parameters for many inputs, its tempting to copy-paste the same Given/When/Then blocks over and soon the feature file grows into a maintenance nightmare: change one step, and you have to remember every duplicated copy. Karate, the API-testing framework, offers a cleaner path.

Enter Karates Scenario Outline with Example Tables

Karates Scenario Outline keyword lets you define a single set of steps once, then feed it multiple data rows via an Example Table. Each row supplies values for placeholders like #(id), and Karate automatically runs the steps for every row, producing separate test results in the report.

A Minimal, Readable Example

Feature: Test user lookup across multiple IDs

Scenario Outline: Look up a user by ID
  Given url baseUrl + '/users/' + id
  When method GET
  Then status 200
  And match response.name == '#(name)'

  Examples:
    | id   | name   |
    | 101  | Alice  |
    | 205  | Bob    |
    | 310  | Charlie|

In this feature file, the Scenario Outline keyword followed by an Examples table means Karate will run the steps once for each row. The placeholder #(id) in the URL is replaced by the value from the current rows id column, and the match assertion uses #(name) from the same row. The result is that a single feature file exercises three distinct API calls, and the report lists each as a separate scenario.

Whats Happening Under the Hood

• Scenario Outline: The keyword that tells Karate to run these steps for every data row.
• Example Table: A two-dimensional table where the first row defines column names that must match placeholder names in the steps.
• Placeholder substitution: Karate replaces #(variable) with the value from the current rows column.
• Report entry per row: Each execution appears as its own scenario in the JSON report, making it easy to see which data set passed or failed.

Trade-Offs and Limitations

While Scenario Outline tables are powerful, they are not a silver bullet. The table is static, so if your test data changes frequently or comes from an external source, you will need to supplement the feature file with a script or Karates * call read mechanism. Very large tables can also hurt readability and increase test execution time, especially if each row makes a real HTTP call. As a rule of thumb, keep the table focused on a few representative rows or use it as a smoke-test pattern rather than a full data-set runner.

Quick Verification You Can Run Yourself

If you have a Karate project set up, you can verify the pattern in under a minute:

1. Open a terminal at your project root.
2. Run the tests using your build tool: mvn test -Dtest=MyTest or gradle test --tests MyTest. Karate tests are executed through these tools, not a standalone CLI.
3. Create a feature file (e.g., UserLookup.feature) with the example above, adjusting the base URL to a reachable endpoint.
4. Inspect the generated JSON report (usually target/karate-reports/... for Maven or build/reports/karate/ for Gradle) and confirm that each row appears as a distinct scenario entry.

Note: The example uses a public-friendly URL pattern; if the endpoint requires authentication or rate-limit handling, add those steps inside the scenario outline rather than hard-coding them.