Karate + Cucumber BDD: API Tests as Living Documentation
Karate is built on Cucumber-JVM, which means every Karate test file is a valid Gherkin feature file. You get Cucumber's readable scenario format, tags, runner configuration, and HTML reports — but without writing any step definitions. Karate's built-in steps handle all HTTP operations.
How Karate Extends Gherkin
Standard Cucumber requires you to map each Gherkin step to a Java method:
# Standard Cucumber — needs a step definition in Java
When I send a GET request to "/users/1"
Then the response status should be 200Karate replaces this model entirely. Its keywords are the step definitions:
# Karate — no step definitions needed
When method GET
Then status 200The Given/When/Then structure is preserved for readability, but Karate doesn't enforce which keyword you use for which operation. Given, When, Then, And, But, and * are all interchangeable — they affect the report formatting but not execution.
Feature File Structure
Feature: User Management API
As an API consumer
I want to manage users
So that I can maintain user accounts
Background:
* url 'https://api.example.com'
* header Authorization = 'Bearer ' + adminToken
@smoke @users
Scenario: Create a new user
Given path '/users'
And request
"""
{
"name": "Alice Smith",
"email": "alice@example.com",
"role": "member"
}
"""
When method POST
Then status 201
And match response.id == '#notnull'
And match response.name == 'Alice Smith'
And match response.role == 'member'
@users @regression
Scenario: Get user by ID
Given path '/users/1'
When method GET
Then status 200
And match response ==
"""
{
"id": 1,
"name": "#string",
"email": "#string",
"role": "#string",
"createdAt": "#notnull"
}
"""
@negative @users
Scenario: Get non-existent user returns 404
Given path '/users/99999'
When method GET
Then status 404
And match response.error == 'User not found'@tag annotations on scenarios let you selectively run subsets of tests.
Scenario Outline for Data-Driven Tests
Feature: User role validation
Scenario Outline: Create user with role <role>
Given url 'https://api.example.com/users'
And request { name: 'Test User', email: '<email>', role: '<role>' }
When method POST
Then status <expectedStatus>
Examples:
| role | email | expectedStatus |
| admin | admin@example.com | 201 |
| member | member@example.com | 201 |
| guest | guest@example.com | 201 |
| invalid | bad@example.com | 400 |Each row in Examples generates a separate scenario. Karate runs them all and reports each one individually in the HTML report.
Cucumber Runner Setup
JUnit 5 Runner
package api;
import com.intuit.karate.junit5.Karate;
class ApiTests {
@Karate.Test
Karate testUsers() {
return Karate.run("users").relativeTo(getClass());
}
@Karate.Test
Karate testOrders() {
return Karate.run("orders").relativeTo(getClass());
}
@Karate.Test
Karate testAll() {
return Karate.run("classpath:api").relativeTo(getClass());
}
}JUnit 4 Runner with Cucumber Annotations
package api;
import com.intuit.karate.junit4.Karate;
import cucumber.api.CucumberOptions;
import org.junit.runner.RunWith;
@RunWith(Karate.class)
@CucumberOptions(
features = "classpath:api",
tags = { "@smoke" },
plugin = {
"pretty",
"html:target/cucumber-reports",
"json:target/cucumber.json"
}
)
public class SmokeTestRunner {}The JUnit 4 runner supports the full Cucumber @CucumberOptions annotation, including tag filtering and multiple output formats.
Tagging and Filtering
Run specific tags from the command line:
# Maven — run only @smoke scenarios
mvn test -Dkarate.options="--tags @smoke"
# Run multiple tags (AND)
mvn test -Dkarate.options="--tags @smoke @regression"
# Run either tag (OR)
mvn test -Dkarate.options="--tags @smoke,@regression"
# Exclude a tag
mvn test -Dkarate.options="--tags ~@wip"In the Java runner:
@Karate.Test
Karate testSmoke() {
return Karate.run("classpath:api")
.tags("@smoke")
.relativeTo(getClass());
}Common tagging strategies:
@smoke— fast, critical-path tests for CI@regression— full test suite for nightly runs@negative— error case scenarios@wip— in-progress scenarios excluded from CI@slow— tests with known latency, excluded from quick runs
HTML Reports
Karate generates an HTML report automatically at target/karate-reports/karate-summary.html. For Cucumber-style reporting, add the Cucumber reporting plugin:
<plugin>
<groupId>net.masterthought</groupId>
<artifactId>maven-cucumber-reporting</artifactId>
<version>5.7.4</version>
<executions>
<execution>
<id>execution</id>
<phase>verify</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<projectName>API Tests</projectName>
<outputDirectory>${project.build.directory}/cucumber-reports</outputDirectory>
<jsonFiles>
<param>${project.build.directory}/cucumber.json</param>
</jsonFiles>
</configuration>
</execution>
</executions>
</plugin>This generates a report showing:
- Feature-level pass/fail summary
- Scenario counts by status
- Each step with request/response details
- Tags summary showing pass rate per tag
Sharing Steps Across Features
Karate supports calling one feature from another:
Feature: Order flow
Background:
* def authResult = call read('classpath:api/auth.feature')
* def token = authResult.response.token
* url 'https://api.example.com'
* header Authorization = 'Bearer ' + token
Scenario: Create and fulfill order
# Create user
* def userResult = call read('classpath:api/users/create-user.feature')
* def userId = userResult.response.id
# Create order
Given path '/orders'
And request { userId: '#(userId)', items: [{ productId: 1, qty: 2 }] }
When method POST
Then status 201
* def orderId = response.id
# Fulfill order
Given path '/orders/' + orderId + '/fulfill'
When method POST
Then status 200
And match response.status == 'fulfilled'This keeps each building block in its own feature file, reusable across multiple test scenarios.
Background vs Hooks
Karate's Background section runs before each scenario in the same file — equivalent to Cucumber's Background. For setup that should run across multiple feature files, use karate-config.js or callSingle:
# In Background of a feature file
* def config = callSingle('classpath:global-setup.feature')callSingle is memoized — it runs only once per test suite execution, regardless of how many feature files reference it. This is useful for expensive setup like fetching auth tokens.
Living Documentation
The combination of Gherkin descriptions, scenario names, and the step-by-step report makes Karate tests readable as documentation. A well-written feature file tells the story of what an API does:
Feature: Password Reset Flow
As a user who forgot their password
I want to receive a reset link by email
So that I can regain access to my account
Scenario: Request password reset
Given I am a registered user with email 'user@example.com'
# translated to Karate:
Given url 'https://api.example.com/auth/reset-password'
And request { email: 'user@example.com' }
When method POST
Then status 200
And match response.message == 'Reset link sent'The feature description and scenario names appear in every report. Teams can share HTML reports with non-technical stakeholders who can understand what was tested without reading the Karate syntax.
Parallel Execution with Tags
Run tagged subsets in parallel:
Results results = Runner.path("classpath:api")
.tags("@regression")
.parallel(4);
assertEquals(0, results.getFailCount(), results.getErrorMessages());Tags and parallel execution compose — you can run @regression scenarios across 4 threads, skipping anything tagged @slow or @wip.