Karate + Cucumber BDD: API Tests as Living Documentation

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 200

Karate replaces this model entirely. Its keywords are the step definitions:

# Karate — no step definitions needed
When method GET
Then status 200

The 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.

Read more

Start now free