Getting Started with Karate DSL: Your First API Test in 15 Minutes

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-SNAPSHOT

When 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.feature

Important: 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 test

You should see output like:

[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0

Karate 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 users

Extract 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 404

Add 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 200

Running 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)

  1. Install the Karate plugin from the IntelliJ marketplace
  2. Open any .feature file
  3. 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 Outline with Examples tables
  • 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.

Read more

Start now free