Getting Started with Karate DSL: Your First API Test in 15 Minutes
Karate DSL lets you write API tests without Java boilerplate. You get a purpose-built syntax for HTTP testing, built-in assertions for JSON/XML, and parallel execution out of the box. This guide gets you from zero to running tests in about 15 minutes.
Prerequisites
- Java 11+ installed (
java -version) - Maven 3.6+ or Gradle 7+ installed
- A text editor or IDE (IntelliJ, VS Code, or Eclipse)
No prior Java knowledge required. Karate's syntax is its own language — you won't be writing Java in your test files.
Step 1: Create a Maven Project
The fastest way to start is with the Karate Maven archetype:
mvn archetype:generate \
-DarchetypeGroupId=com.intuit.karate \
-DarchetypeArtifactId=karate-archetype \
-DarchetypeVersion=1.4.1 \
-DgroupId=com.example \
-DartifactId=karate-tests \
-Dversion=1.0-SNAPSHOTWhen prompted, press Enter to accept defaults.
Or manually create a Maven project with this pom.xml:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>karate-tests</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<karate.version>1.4.1</karate.version>
</properties>
<dependencies>
<dependency>
<groupId>com.intuit.karate</groupId>
<artifactId>karate-junit5</artifactId>
<version>${karate.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<testResources>
<testResource>
<directory>src/test/java</directory>
<excludes>
<exclude>**/*.java</exclude>
</excludes>
</testResource>
</testResources>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0</version>
</plugin>
</plugins>
</build>
</project>Step 2: Set Up Directory Structure
Create these directories:
src/
test/
java/
com/
example/
TestRunner.java
karate-config.js
features/
users.featureImportant: Feature files go under src/test/java, not src/test/resources. The pom.xml above configures Maven to treat .feature files in src/test/java as test resources.
Step 3: Create the Test Runner
Create src/test/java/com/example/TestRunner.java:
package com.example;
import com.intuit.karate.junit5.Karate;
class TestRunner {
@Karate.Test
Karate testAll() {
return Karate.run().relativeTo(getClass());
}
}This runner discovers all .feature files in the same package and below.
Step 4: Create karate-config.js
Create src/test/java/karate-config.js:
function fn() {
var config = {
baseUrl: 'https://jsonplaceholder.typicode.com'
};
return config;
}This file runs before every test. Variables you define here are available in all feature files. We're using JSONPlaceholder — a free fake REST API — so you can test against a real endpoint immediately.
Step 5: Write Your First Test
Create src/test/java/features/users.feature:
Feature: Users API
Scenario: Get all users
Given url baseUrl
And path '/users'
When method GET
Then status 200
And match response == '#[]'
And match response[0] == { id: '#number', name: '#string', email: '#string', username: '#string', address: '#object', phone: '#string', website: '#string', company: '#object' }
Scenario: Get a specific user
Given url baseUrl
And path '/users/1'
When method GET
Then status 200
And match response.id == 1
And match response.name == 'Leanne Graham'
And match response.email == '#string'
Scenario: Create a user
Given url baseUrl
And path '/users'
And request { name: 'Test User', email: 'test@example.com', username: 'testuser' }
When method POST
Then status 201
And match response.id == '#number'
And match response.name == 'Test User'Step 6: Run Your Tests
mvn testYou should see output like:
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0Karate generates an HTML report at target/karate-reports/karate-summary.html. Open it in a browser to see request/response details for each scenario.
Understanding the Syntax
Let's break down the key elements in the test above.
Given url baseUrl
Sets the base URL for this scenario. baseUrl comes from karate-config.js.
And path '/users'
Appends the path to the base URL. The final URL becomes https://jsonplaceholder.typicode.com/users.
When method GET
Executes the HTTP request. Karate sends everything defined in the Given steps, then waits for a response.
Then status 200
Asserts the HTTP response status code. If the actual status is anything other than 200, the test fails immediately.
And match response == '#[]'
Asserts the response is a non-empty JSON array. The #[] wildcard means "any array with at least one element."
And match response[0] == { ... }
Asserts the structure of the first element. The #number, #string, #object wildcards check type without caring about the exact value.
Common Next Steps
Add a Background for Shared Setup
Feature: Users API
Background:
Given url baseUrl
And path '/users'
Scenario: Get all users
When method GET
Then status 200
Scenario: Get user count
When method GET
Then status 200
And match response == '#[10]' # exactly 10 usersExtract Values from Responses
Scenario: Create then fetch user
Given url baseUrl
And path '/posts'
And request { title: 'My Post', body: 'Content', userId: 1 }
When method POST
Then status 201
* def postId = response.id
Given url baseUrl
And path '/posts/' + postId
When method GET
Then status 200
And match response.title == 'My Post'Test Error Cases
Scenario: Get nonexistent user returns 404
Given url baseUrl
And path '/users/9999'
When method GET
Then status 404Add Headers
Scenario: Request with auth header
Given url baseUrl
And path '/users'
And header Authorization = 'Bearer my-token'
And header Accept = 'application/json'
When method GET
Then status 200Running Specific Tests
Run a single feature file:
mvn test -Dtest=TestRunner -Dkarate.options="classpath:features/users.feature"Run a specific scenario by tag:
@smoke
Scenario: Get all users
...mvn test -Dkarate.options="--tags @smoke"IDE Setup (IntelliJ)
- Install the Karate plugin from the IntelliJ marketplace
- Open any
.featurefile - Click the green play button next to a scenario to run it
This gives you per-scenario run/debug without touching the command line.
What's Next
Once your first tests run, the natural progression is:
- Data-driven tests —
Scenario OutlinewithExamplestables - Calling features from features — reusable auth flows, shared setup
- Service mocks — running Karate as a mock server
- Parallel execution — running hundreds of scenarios concurrently
The Karate DSL complete guide covers all of these in depth.