BDD-Style API Automation with Karate DSL: Writing Tests Like Stories

BDD-Style API Automation with Karate DSL: Writing Tests Like Stories

Behavior-Driven Development promised to close the gap between business requirements and technical tests. In practice, BDD frameworks like Cucumber often deliver the syntax without the benefit — developers write Given-When-Then wrappers around code that non-developers still can't read or maintain.

Karate DSL is different. It takes BDD syntax and applies it directly to HTTP operations — the layer where API contracts live. The result is tests that are genuinely readable by anyone familiar with REST, not just the developer who wrote them.

Why BDD for APIs

API tests sit at a useful boundary. They're technical enough that pure natural language is awkward, but they describe behavior clearly enough that non-developer stakeholders can understand what's being tested.

A Karate test reads like a specification:

Feature: Order Processing API

Scenario: Customer places a valid order
  Given the API is running at 'https://api.shop.example.com'
  And the customer is authenticated
  When they submit an order for 2 units of product 'SKU-101'
  Then the order is created with status 'pending'
  And they receive an order confirmation number

This is executable specification. The same document serves as test, documentation, and acceptance criteria.

Karate's BDD Vocabulary

Karate uses Gherkin syntax but extends it with HTTP-specific keywords. The Given/When/Then structure maps naturally to API testing:

  • Given: Set up the request — URL, headers, body
  • When: Execute the HTTP call
  • Then: Assert the response
Scenario: Get product details
  Given url 'https://api.example.com'
  And path '/products/42'
  And header Accept = 'application/json'
  When method get
  Then status 200
  And match response.name == 'Widget Pro'
  And match response.price == '#number'
  And match response.available == true

The * keyword acts as a wildcard — you can use it when a step doesn't fit neatly into Given/When/Then:

* def productId = 42
* def baseUrl = 'https://api.example.com'

Structuring Features for Readability

Good BDD tests tell a story. Structure your features around user goals, not technical operations.

Avoid (technical-first):

Scenario: POST /orders returns 201
  Given url 'https://api.example.com'
  And path '/orders'
  And request { productId: 1, quantity: 2 }
  When method post
  Then status 201

Better (behavior-first):

Scenario: Authenticated customer can place an order
  Given a customer is logged in as 'alice@example.com'
  And they have item 'SKU-101' in their cart
  When they complete checkout
  Then an order is created
  And the order status is 'confirmed'
  And alice receives a confirmation email trigger

Both tests might exercise the same endpoint. The second one communicates intent.

Building Reusable Given Steps

The secret to readable Karate BDD is extracting common setup into reusable features and variables.

Auth setup feature (auth.feature):

Feature: Authentication
  Scenario: Login as customer
    * url 'https://api.example.com'
    * path '/auth/login'
    * request { email: '#(email)', password: '#(password)' }
    * method post
    * status 200
    * def token = response.accessToken

Using auth in a product feature:

Feature: Shopping Cart

Background:
  * def authResult = call read('auth.feature') { email: 'alice@example.com', password: 'secret' }
  * def token = authResult.token
  * url 'https://api.example.com'
  * header Authorization = 'Bearer ' + token

Scenario: Add item to cart
  Given path '/cart/items'
  And request { productId: 101, quantity: 2 }
  When method post
  Then status 200
  And match response.items[0].productId == 101

Scenario: View cart total
  Given path '/cart'
  When method get
  Then status 200
  And match response.total == '#number'
  And match response.itemCount >= 1

The Background block runs before every scenario. Auth happens once per scenario. Clean and readable.

Scenario Chains: Multi-Step Business Flows

Real business scenarios span multiple API calls. Karate handles this naturally:

Feature: Order Lifecycle

Scenario: Complete order flow from creation to fulfillment

  # Step 1: Create order
  Given url 'https://api.example.com'
  And path '/orders'
  And header Authorization = 'Bearer ' + token
  And request
    """
    {
      items: [
        { productId: 101, quantity: 2 },
        { productId: 205, quantity: 1 }
      ],
      shippingAddress: {
        street: '123 Main St',
        city: 'Portland',
        zip: '97201'
      }
    }
    """
  When method post
  Then status 201
  And match response.status == 'pending'
  * def orderId = response.id

  # Step 2: Verify order appears in list
  Given path '/orders'
  When method get
  Then status 200
  And match response[*].id contains orderId

  # Step 3: Process payment
  Given path '/orders/' + orderId + '/payment'
  And request { method: 'card', cardToken: 'tok_test_123' }
  When method post
  Then status 200
  And match response.status == 'paid'

  # Step 4: Confirm order status updated
  Given path '/orders/' + orderId
  When method get
  Then status 200
  And match response.status == 'processing'

Variables persist through a scenario. orderId captured in step 1 is available in steps 2, 3, and 4.

Negative Scenarios and Error Cases

BDD isn't just happy paths. Negative scenarios are equally important:

Feature: Order Validation

Scenario: Cannot order out-of-stock product
  Given url 'https://api.example.com'
  And path '/orders'
  And header Authorization = 'Bearer ' + token
  And request { items: [{ productId: 999, quantity: 100 }] }
  When method post
  Then status 422
  And match response.error == 'INSUFFICIENT_STOCK'
  And match response.productId == 999

Scenario: Cannot place order without authentication
  Given url 'https://api.example.com'
  And path '/orders'
  And request { items: [{ productId: 101, quantity: 1 }] }
  When method post
  Then status 401
  And match response.error == 'UNAUTHORIZED'

Scenario: Invalid quantity is rejected
  Given url 'https://api.example.com'
  And path '/orders'
  And header Authorization = 'Bearer ' + token
  And request { items: [{ productId: 101, quantity: -5 }] }
  When method post
  Then status 400
  And match response.errors[*].field contains 'quantity'

Each scenario tests a specific business rule. The test name documents what rule it covers.

Using Tags for Test Organization

Karate inherits Cucumber's tagging system. Tags let you run subsets of tests:

@smoke @critical
Feature: Core order API

@regression
Scenario: Create order with valid data
  ...

@slow @integration
Scenario: Complete order lifecycle
  ...

Run by tag:

mvn test -Dkarate.options="--tags @smoke"
mvn test -Dkarate.options="--tags @regression,~@slow"

Tag strategy:

  • @smoke — fast, critical path tests for every deploy
  • @regression — full coverage suite, run nightly
  • @integration — requires downstream services
  • @wip — work in progress, excluded from CI

Parameterized Scenarios with Examples

Feature: Product Search

Scenario Outline: Search returns relevant results for <category>
  Given url 'https://api.example.com'
  And path '/products/search'
  And param q = '<query>'
  And param category = '<category>'
  When method get
  Then status 200
  And match response.count >= <minResults>
  And match each response.items == { category: '<category>', name: '#string' }

  Examples:
    | query   | category    | minResults |
    | widget  | electronics | 5          |
    | desk    | furniture   | 3          |
    | organic | food        | 10         |

Each row generates a separate test scenario. Results appear individually in reports.

Collaboration Benefits

The real BDD payoff isn't technical — it's organizational.

QA engineers can write Karate tests without Java expertise. The domain-specific syntax is learnable in hours, not weeks.

Product managers can read scenarios and verify they match acceptance criteria. They can catch gaps before implementation.

Developers can use feature files as a spec before writing API endpoints. Karate tests become TDD anchors.

Support teams can understand what's being tested when investigating customer-reported issues.

This collaboration requires the test files to live in version control alongside the code — not in a separate tool or test management system. Karate's file-based approach enforces this naturally.

Connecting BDD Tests to Monitoring

BDD scenarios describe expected system behavior. That behavior should hold in production, not just in test environments.

Once your Karate scenarios are passing, consider running the same business scenarios as continuous monitors. HelpMeTest lets you run API test scenarios every 5 minutes against production endpoints — the same given-when-then logic, running 24/7, alerting you when the behavior your BDD tests describe starts failing in the real world.

Common BDD Antipatterns in Karate

Antipattern: Implementation details in scenario names

Scenario: POST /orders returns 201 with valid JWT

Better:

Scenario: Authenticated user can create a valid order

Antipattern: One massive scenario Long scenarios with 30+ steps are hard to debug and document nothing useful.

Better: Split by business concept. Each scenario should test one thing.

Antipattern: Duplicated setup in every scenario

Scenario: Create order
  Given url 'https://api.example.com'
  And header Authorization = ...
  ...

Scenario: Cancel order
  Given url 'https://api.example.com'
  And header Authorization = ...
  ...

Better: Use Background or call shared setup features.

Summary

Karate DSL makes BDD practical for API testing by removing the translation layer between human-readable specs and executable tests. The same file that communicates intent to stakeholders is the file that runs against your API.

The key is discipline in how you write scenarios. Focus on business behavior, not implementation details. Build reusable setup. Test negative cases as thoroughly as happy paths. When your feature files read like clear documentation, you've achieved what BDD promised.

Read more

Start now free