Karate Labs: Data-Driven API Testing with Scenario Outline and Examples Tables

Model repeated API checks with one Scenario Outline

When the same endpoint must be verified with different inputs and expectations, duplicate scenarios create maintenance cost. In Karate Labs the practical decision is to define one Scenario Outline and put variable data in an Examples table. Karate executes each row as a separate scenario instance with placeholders substituted before HTTP calls.

How placeholder substitution works

Placeholders like <id> and <expectedStatus> in path, request, match or status steps are replaced from the current Examples row. One test definition can therefore cover many input and expectation pairs. Each Examples row is reported as an individual case, so failures are attributable to a specific input row.

Worked feature file

Feature: User API data-driven tests

Scenario Outline: Get user by ID
  Given url baseUrl + '/users/' + '<id>'
  When method get
  Then status <expectedStatus>
  And match response.id == <id>

Examples:
  | id  | expectedStatus |
  | 1   | 200            |
  | 999 | 404            |
  | abc | 400            |

Karate creates three scenario instances from the table: GET /users/1 expecting 200, GET /users/999 expecting 404, and GET /users/abc expecting 400. The Examples keyword signals Karate to expand the outline.

Limits and common mistakes

Angle-bracket substitution vs #(...) expressions

Angle-bracket substitution is not the same as Karate's #(...) expression evaluation. Confusing the two causes literal text or failed matches.

Table values are strings

Examples values are commonly strings. Numeric or boolean expectations may need explicit conversion or a match expression that accounts for type.

Given path 'users', parseInt(<id>)
Then match response.id == parseInt(<id>)

Column names must match exactly

A misspelled header leaves an unresolved placeholder that can look like an endpoint bug. The scenario uses <userId> but the table provides | user |, Karate substitutes the literal string.

Shared mutable state leaks

Variables defined in one Examples row can leak to others, especially under parallel execution. Avoid modifying shared headers or cookies inside the outline. Use call to isolate setup when needed.

When to move data out of the table

Keep deterministic boundary and error cases inline for readability. Move to external CSV or JSON fixtures with Examples: [read('test-users.csv')] when you have more than 10-15 cases, data is generated, or multiple features share the dataset.

Tags and selective runs

Tags placed on a Scenario Outline are inherited by generated examples, enabling selective runs without duplicating logic.

@smoke
Scenario Outline: Get user by ID
  ...

Examples: ...

Verification approach: create a small outline with two known rows, run via the project's JUnit/Maven/Gradle Karate runner, confirm two scenario instances appear with correct substitution, then change one expectedStatus to force a single row failure, and finally introduce a misspelled header to confirm name matching matters.