---

Article

Karate DSL is a powerful open-source testing framework that combines API test automation, performance testing, and mocks into a single, unified tool. Unlike traditional testing frameworks, Karate uses a behavior-driven development (BDD) syntax that allows even non-technical stakeholders to understand tests, while providing powerful capabilities for Java developers. This article explores how to leverage Karate DSL for comprehensive API testing in Java projects.

---

Why Karate DSL?

Key Advantages:

• No Java Code Required: Write tests in Gherkin-like syntax
• Built-in Assertions: Comprehensive validation capabilities
• Test Doubles: Built-in mock server for testing
• Performance Testing: Integration with Gatling for load testing
• Parallel Execution: Run tests in parallel for faster feedback
• JSON/XML Support: First-class support for modern data formats

Setting Up Karate DSL

1. Maven Dependencies

<properties>
<karate.version>1.4.1</karate.version>
<maven-surefire.version>3.1.2</maven-surefire.version>
</properties>
<dependencies>
<!-- Karate Core -->
<dependency>
<groupId>com.intuit.karate</groupId>
<artifactId>karate-core</artifactId>
<version>${karate.version}</version>
<scope>test</scope>
</dependency>
<!-- Karate JUnit 5 -->
<dependency>
<groupId>com.intuit.karate</groupId>
<artifactId>karate-junit5</artifactId>
<version>${karate.version}</version>
<scope>test</scope>
</dependency>
<!-- Apache HTTP Client for advanced HTTP features -->
<dependency>
<groupId>com.intuit.karate</groupId>
<artifactId>karate-apache</artifactId>
<version>${karate.version}</version>
<scope>test</scope>
</dependency>
<!-- Test Containers for integration testing -->
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers</artifactId>
<version>1.19.3</version>
<scope>test</scope>
</dependency>
<!-- AssertJ for additional assertions -->
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<version>3.24.2</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<testResources>
<testResource>
<directory>src/test/java</directory>
<excludes>
<exclude>**/*.java</exclude>
</excludes>
</testResource>
<testResource>
<directory>src/test/resources</directory>
</testResource>
</testResources>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${maven-surefire.version}</version>
<configuration>
<includes>
<include>**/*Test.java</include>
<include>**/*TestRunner.java</include>
</includes>
<systemPropertyVariables>
<karate.options>--tags ~@ignore</karate.options>
<karate.env>${karate.env:-dev}</karate.env>
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>

2. Project Structure

src/test/java
├── com/example/api/
│   ├── runners/
│   │   ├── ApiTestRunner.java
│   │   ├── UserApiTestRunner.java
│   │   └── ParallelTestRunner.java
│   └── helpers/
│       ├── JavaHelpers.java
│       └── TestDataGenerator.java
└── com/example/api/features/
├── users/
│   ├── users.feature
│   ├── user-management.feature
│   └── user-search.feature
├── products/
│   ├── products.feature
│   └── product-categories.feature
├── orders/
│   └── orders.feature
├── common/
│   ├── common.feature
│   └── auth.feature
└── utils/
├── config.js
├── utils.js
└── test-data.js

Core Karate Features

1. Basic API Test Example

# src/test/java/com/example/api/features/users/users.feature
Feature: User API CRUD Operations
Background:
* url baseUrl
* configure headers = { 'Content-Type': 'application/json', 'X-API-Key': '#(apiKey)' }
* def createUserRequest = read('classpath:com/example/api/features/users/create-user-request.json')
* def updateUserRequest = read('classpath:com/example/api/features/users/update-user-request.json')
Scenario: Create a new user successfully
Given path 'users'
And request createUserRequest
When method post
Then status 201
And match response ==
"""
{
id: '#number',
firstName: '#(createUserRequest.firstName)',
lastName: '#(createUserRequest.lastName)',
email: '#(createUserRequest.email)',
status: 'ACTIVE',
createdAt: '#notnull',
updatedAt: '#notnull'
}
"""
And def userId = response.id
And print 'Created user with ID:', userId
Scenario: Get user by ID
Given path 'users', userId
When method get
Then status 200
And match response.id == userId
And match response.status == 'ACTIVE'
Scenario: Update user information
Given path 'users', userId
And request updateUserRequest
When method put
Then status 200
And match response.firstName == updateUserRequest.firstName
And match response.lastName == updateUserRequest.lastName
Scenario: Delete user
Given path 'users', userId
When method delete
Then status 204
Scenario: Get deleted user should return 404
Given path 'users', userId
When method get
Then status 404

2. Complex Validation with Data-Driven Testing

Feature: Advanced User API Validation with Data-Driven Tests
Background:
* url baseUrl
* configure headers = { 'Content-Type': 'application/json' }
Scenario Outline: Create users with different data combinations
Given path 'users'
And request
"""
{
"firstName": "<firstName>",
"lastName": "<lastName>", 
"email": "<email>",
"age": <age>,
"role": "<role>"
}
"""
When method post
Then status <expectedStatus>
And match response contains { id: '#number' }
And match response contains deep { role: '<role>' }
Examples:
| firstName | lastName | email               | age | role    | expectedStatus |
| John      | Doe      | [email protected]    | 25  | USER    | 201            |
| Jane      | Smith    | [email protected]    | 30  | ADMIN   | 201            |
| Bob       | Johnson  | invalid-email       | 15  | USER    | 400            |
| Alice     | Brown    | [email protected]   | 200 | USER    | 400            |
Scenario: Validate user response schema
Given path 'users'
And def userData =
"""
{
firstName: 'Schema',
lastName: 'Validator',
email: '[email protected]',
age: 28,
role: 'USER'
}
"""
And request userData
When method post
Then status 201
And match response ==
"""
{
id: '#number',
firstName: '#string',
lastName: '#string', 
email: '#regex [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}',
age: '#number',
role: '#string',
status: '#string',
createdAt: '#notnull',
updatedAt: '#notnull'
}
"""
And match each response..role == '#? _ == "USER" || _ == "ADMIN" || _ == "MODERATOR"'
Scenario: Test user search with query parameters
Given path 'users'
And param page = 0
And param size = 10
And param sort = 'firstName,desc'
And param role = 'USER'
When method get
Then status 200
And match response.content == '#[]'
And match response.pageable ==
"""
{
pageNumber: 0,
pageSize: 10,
sort: { sorted: true, unsorted: false, empty: false }
}
"""
And match response.totalElements == '#number'
And match response.totalPages == '#number'

3. Authentication and Security Testing

Feature: API Authentication and Security
Background:
* url baseUrl
Scenario: Successful authentication with valid credentials
Given path 'auth', 'login'
And request
"""
{
"username": "testuser",
"password": "validpassword"
}
"""
When method post
Then status 200
And match response ==
"""
{
token: '#notnull',
type: 'Bearer',
expiresIn: '#number',
refreshToken: '#notnull'
}
"""
And def authToken = response.token
And configure headers = { 'Authorization': 'Bearer ' + authToken }
Scenario: Authentication with invalid credentials
Given path 'auth', 'login'
And request
"""
{
"username": "testuser",
"password": "wrongpassword"
}
"""
When method post
Then status 401
And match response ==
"""
{
error: 'UNAUTHORIZED',
message: 'Invalid credentials',
timestamp: '#notnull'
}
"""
Scenario: Access protected endpoint without token
Given path 'users', 'profile'
When method get
Then status 401
Scenario: Access protected endpoint with valid token
Given path 'users', 'profile'
And header Authorization = 'Bearer ' + authToken
When method get
Then status 200
And match response.username == 'testuser'
Scenario: Test token expiration
Given path 'auth', 'verify'
And header Authorization = 'Bearer ' + authToken
When method post
Then status 200
And match response.valid == true

4. File Upload and Download Testing

Feature: File Upload and Download Operations
Background:
* url baseUrl
* configure headers = { 'Authorization': 'Bearer ' + authToken }
Scenario: Upload user profile picture
Given path 'users', userId, 'avatar'
And multipart file file = { read: 'classpath:test-data/profile-picture.jpg', filename: 'avatar.jpg' }
And multipart field description = 'User profile picture'
When method post
Then status 200
And match response ==
"""
{
fileId: '#string',
filename: 'avatar.jpg',
size: '#number',
url: '#string',
uploadedAt: '#notnull'
}
"""
And def fileId = response.fileId
Scenario: Download uploaded file
Given path 'files', fileId
When method get
Then status 200
And match header Content-Type contains 'image/'
And match responseBytes.length > 0
Scenario: Upload file with validation
Given path 'users', userId, 'documents'
And multipart file document = { read: 'classpath:test-data/large-file.pdf', filename: 'document.pdf' }
When method post
Then status 413
And match response ==
"""
{
error: 'PAYLOAD_TOO_LARGE',
message: '#string',
maxSize: 10485760
}
"""

Advanced Karate Features

1. JavaScript Functions and Helpers

// src/test/java/com/example/api/utils/utils.js
function generateRandomEmail() {
var timestamp = new Date().getTime();
return 'testuser' + timestamp + '@example.com';
}
function generateUserData(role) {
return {
firstName: 'Test' + Math.floor(Math.random() * 1000),
lastName: 'User',
email: generateRandomEmail(),
age: Math.floor(Math.random() * 50) + 18,
role: role || 'USER'
};
}
function validateUserResponse(user) {
if (!user.id) return false;
if (!user.email.match(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)) return false;
if (user.age < 0 || user.age > 150) return false;
return true;
}
function calculateAge(birthDate) {
var today = new Date();
var birthDate = new Date(birthDate);
var age = today.getFullYear() - birthDate.getFullYear();
var monthDiff = today.getMonth() - birthDate.getMonth();
if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birthDate.getDate())) {
age--;
}
return age;
}

2. Java Integration Helpers

// src/test/java/com/example/api/helpers/JavaHelpers.java
package com.example.api.helpers;
import com.intuit.karate.JsonUtils;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Base64;
import java.util.UUID;
public class JavaHelpers {
public static String generateUniqueId() {
return UUID.randomUUID().toString();
}
public static String getCurrentTimestamp() {
return LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
}
public static String encodeBase64(String data) {
return Base64.getEncoder().encodeToString(data.getBytes());
}
public static String decodeBase64(String encodedData) {
return new String(Base64.getDecoder().decode(encodedData));
}
public static boolean isValidEmail(String email) {
return email != null && email.matches("^[A-Za-z0-9+_.-]+@(.+)$");
}
public static String toJsonString(Object object) {
return JsonUtils.toJson(object);
}
public static Object fromJsonString(String json) {
return JsonUtils.toJsonDoc(json);
}
}

3. Configuration Management

// src/test/java/com/example/api/utils/config.js
function getConfig() {
var env = karate.env || 'dev';
var config = {
dev: {
baseUrl: 'http://localhost:8080/api/v1',
apiKey: 'dev-key-12345',
timeout: 5000
},
qa: {
baseUrl: 'https://qa-api.example.com/api/v1',
apiKey: 'qa-key-67890',
timeout: 10000
},
staging: {
baseUrl: 'https://staging-api.example.com/api/v1',
apiKey: 'staging-key-abcde',
timeout: 15000
},
prod: {
baseUrl: 'https://api.example.com/api/v1',
apiKey: karate.properties['api.key'] || 'default-prod-key',
timeout: 20000
}
};
var result = config[env];
if (!result) {
throw 'Invalid environment: ' + env;
}
// Set default configuration
karate.configure('connectTimeout', result.timeout);
karate.configure('readTimeout', result.timeout);
return result;
}

Test Runners and Parallel Execution

1. JUnit 5 Test Runners

// src/test/java/com/example/api/runners/ApiTestRunner.java
package com.example.api.runners;
import com.intuit.karate.junit5.Karate;
import org.junit.jupiter.api.BeforeAll;
class ApiTestRunner {
@BeforeAll
static void beforeAll() {
// Setup before all tests
System.setProperty("karate.env", System.getProperty("karate.env", "dev"));
}
@Karate.Test
Karate testAll() {
return Karate.run().relativeTo(getClass());
}
@Karate.Test
Karate testUsers() {
return Karate.run("classpath:com/example/api/features/users")
.tags("@users")
.outputCucumberJson(true);
}
@Karate.Test
Karate testProducts() {
return Karate.run("classpath:com/example/api/features/products")
.tags("@products")
.outputHtmlReport(true);
}
}
// src/test/java/com/example/api/runners/ParallelTestRunner.java
package com.example.api.runners;
import com.intuit.karate.Results;
import com.intuit.karate.Runner;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
class ParallelTestRunner {
@Test
void testParallel() {
Results results = Runner.path("classpath:com/example/api/features")
.tags("~@ignore")
.outputCucumberJson(true)
.outputJunitXml(true)
.reportDir("target/karate-reports")
.parallel(5);
assertEquals(0, results.getFailCount(), results.getErrorMessages());
}
}

2. Test Configuration with Hooks

// src/test/java/com/example/api/runners/TestBase.java
package com.example.api.runners;
import com.intuit.karate.junit5.Karate;
import org.junit.jupiter.api.BeforeAll;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.utility.DockerImageName;
public abstract class TestBase {
private static GenericContainer<?> apiContainer;
@BeforeAll
static void setup() {
String environment = System.getProperty("karate.env", "dev");
if ("local".equals(environment)) {
startTestContainers();
}
}
private static void startTestContainers() {
apiContainer = new GenericContainer<>(DockerImageName.parse("my-api:latest"))
.withExposedPorts(8080)
.withEnv("SPRING_PROFILES_ACTIVE", "test")
.withReuse(true);
apiContainer.start();
String baseUrl = "http://" + apiContainer.getHost() + ":" + apiContainer.getFirstMappedPort();
System.setProperty("karate.baseUrl", baseUrl);
}
}

Performance Testing with Gatling

1. Performance Test Feature

# src/test/java/com/example/api/features/performance/users-load.feature
Feature: User API Load Testing
@performance
Scenario: Create users under load
Given url baseUrl
And header Content-Type = 'application/json'
And header X-API-Key = '#(apiKey)'
And request
"""
{
"firstName": "LoadTest",
"lastName": "User#{id}",
"email": "loadtest#{id}@example.com",
"age": 30,
"role": "USER"
}
"""
When method post
Then status 201
@performance
Scenario: Get users under load
Given url baseUrl
And path 'users'
And param page = 0
And param size = 20
When method get
Then status 200

2. Gatling Simulation Runner

// src/test/java/com/example/api/performance/PerformanceRunner.java
package com.example.api.performance;
import com.intuit.karate.gatling.KarateProtocol;
import com.intuit.karate.gatling.PreDef.*;
import io.gatling.core.PreDef.*;
import io.gatling.core.structure.ScenarioBuilder;
import io.gatling.http.PreDef.*;
import java.time.Duration;
import java.util.Collections;
public class PerformanceRunner {
private final KarateProtocol createUserProtocol = karateProtocol()
.name("Create User")
.uriPattern("/api/v1/users");
private final KarateProtocol getUserProtocol = karateProtocol()
.name("Get Users")
.uriPattern("/api/v1/users.*");
public ScenarioBuilder createUserScenario() {
return scenario("Create User Load Test")
.exec(karateFeature("classpath:com/example/api/features/performance/users-load.feature@performance"));
}
public ScenarioBuilder getUserScenario() {
return scenario("Get Users Load Test")
.exec(karateFeature("classpath:com/example/api/features/performance/users-load.feature@performance"));
}
{
setUp(
createUserScenario().injectOpen(
rampUsersPerSec(1).to(10).during(Duration.ofMinutes(2)),
constantUsersPerSec(10).during(Duration.ofMinutes(5))
).protocols(createUserProtocol),
getUserScenario().injectOpen(
rampUsersPerSec(5).to(50).during(Duration.ofMinutes(2)),
constantUsersPerSec(50).during(Duration.ofMinutes(5))
).protocols(getUserProtocol)
).maxDuration(Duration.ofMinutes(10));
}
}

Mock Server for Testing

1. Karate Mock Server Feature

# src/test/java/com/example/api/mocks/user-service-mock.feature
Feature: User Service Mock
Background:
* configure cors = true
* configure headers = { 'Content-Type': 'application/json' }
Scenario: pathMatches('/users') && methodIs('POST')
* def response =
"""
{
"id": "#(uuid())",
"firstName": "#(request.firstName)",
"lastName": "#(request.lastName)",
"email": "#(request.email)",
"status": "ACTIVE",
"createdAt": "#(now)",
"updatedAt": "#(now)"
}
"""
* def responseStatus = 201
Scenario: pathMatches('/users/{id}') && methodIs('GET')
* def user = get[0]
* if (user) 
* def response = user
* def responseStatus = 200
* else 
* def response = { error: 'User not found' }
* def responseStatus = 404
Scenario: pathMatches('/users') && methodIs('GET')
* def users = get
* def response = 
"""
{
"content": #(users),
"pageable": {
"pageNumber": 0,
"pageSize": 20,
"sort": { "sorted": false, "unsorted": true, "empty": true }
},
"totalElements": #(users.length),
"totalPages": 1,
"last": true,
"first": true
}
"""
* def responseStatus = 200

2. Mock Server Runner

// src/test/java/com/example/api/mocks/MockServerRunner.java
package com.example.api.mocks;
import com.intuit.karate.junit5.Karate;
class MockServerRunner {
@Karate.Test
Karate testMockServer() {
return Karate.run("classpath:com/example/api/mocks/user-service-mock.feature")
.systemProperty("mock.port", "8080");
}
}

CI/CD Integration

1. Maven Surefire Configuration

<profile>
<id>karate-tests</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.1.2</version>
<configuration>
<includes>
<include>**/*ParallelTestRunner.java</include>
</includes>
<systemPropertyVariables>
<karate.env>${karate.env}</karate.env>
<karate.options>--tags ~@ignore</karate.options>
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
</profile>

2. GitHub Actions Workflow

# .github/workflows/api-tests.yml
name: API Tests
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
api-tests:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:14
env:
POSTGRES_PASSWORD: test
POSTGRES_DB: testdb
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
ports:
- 5432:5432
steps:
- uses: actions/checkout@v3
- name: Set up JDK 21
uses: actions/setup-java@v3
with:
java-version: '21'
distribution: 'temurin'
cache: 'maven'
- name: Run API Tests
run: mvn test -Pkarate-tests -Dkarate.env=ci
env:
API_BASE_URL: http://localhost:8080
DATABASE_URL: jdbc:postgresql://localhost:5432/testdb
- name: Upload Test Reports
uses: actions/upload-artifact@v3
with:
name: karate-reports
path: target/karate-reports/
retention-days: 7

Best Practices

1. Test Organization

• Group features by business domain
• Use descriptive scenario names
• Implement proper tagging strategy
• Separate positive and negative tests

2. Data Management

• Use dynamic test data generation
• Clean up test data after execution
• Implement data factories for complex objects
• Use scenario outlines for data-driven testing

3. Maintenance

• Regular review of test patterns
• Update tests for API changes
• Monitor test execution time
• Refactor common steps into background

Conclusion

Karate DSL provides a comprehensive solution for API testing that combines simplicity with powerful features. Key benefits include:

• Reduced Learning Curve: BDD syntax is accessible to all team members
• Comprehensive Testing: Supports REST, SOAP, GraphQL, and more
• Built-in Capabilities: No need for additional assertion libraries
• Performance Testing: Integrated Gatling support
• Mock Server: Built-in test doubles for integration testing
• Parallel Execution: Fast test execution with minimal configuration

By leveraging Karate DSL, teams can achieve high test coverage with maintainable, readable tests that provide fast feedback and reliable API validation across the entire development lifecycle.