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 numberThis 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 == trueThe * 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 201Better (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 triggerBoth 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.accessTokenUsing 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 >= 1The 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 JWTBetter:
Scenario: Authenticated user can create a valid orderAntipattern: 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.