Skip to main content

GET STARTED

Quick Start

Already installed? Let's write and run your first real test in under 5 minutes.

Haven't installed yet?

See Install & Get Started to choose your setup path (VS Code, CLI, Maven, Gradle, or standalone JAR).

Your First Test​

Create a file called users.feature:

users.feature
Feature: User API

  Scenario: List all users
    Given url 'https://jsonplaceholder.typicode.com'
    And path 'users'
    When method get
    Then status 200
    # Verify we got an array of 10 users
    And match response == '#[10]'
    # Each user has the expected shape
    And match each response contains { id: '#number', name: '#string', email: '#string' }

  Scenario: Get a single user
    Given url 'https://jsonplaceholder.typicode.com'
    And path 'users', 1
    When method get
    Then status 200
    And match response.name == 'Leanne Graham'
    And match response.address.city == '#string'

  Scenario: Create a user
    Given url 'https://jsonplaceholder.typicode.com'
    And path 'users'
    And request { name: 'Jane Doe', email: 'jane@example.com' }
    When method post
    Then status 201
    And match response contains { name: 'Jane Doe' }

Run It​

Choose the method matching your setup:

Karate CLI
karate users.feature
Standalone JAR
java -jar karate.jar users.feature
Maven (with JUnit runner)
mvn test

You should see output like:

3 scenario(s) passed, 0 failed

An HTML report is generated in your output directory — open it in a browser to see detailed request/response logs for every step.

What Just Happened?​

KeywordWhat it does
Given urlSets the base URL
And pathAppends to the URL path
And requestSets the request body (auto-detected as JSON)
When methodSends the HTTP request
Then statusAsserts the response status code
And matchAsserts response content (supports fuzzy matching)

The #string, #number, #[10] markers are fuzzy matchers — they validate types and shapes without requiring exact values. This is key to writing robust API tests.

Add Configuration​

Create karate-config.js to share settings across all tests:

karate-config.js
function fn() {
  var env = karate.env || 'dev';
  var config = {
    baseUrl: 'https://jsonplaceholder.typicode.com'
  };
  if (env === 'staging') {
    config.baseUrl = 'https://staging-api.example.com';
  }
  return config;
}

Now simplify your feature files:

users.feature
Feature: User API

  Scenario: List all users
    Given url baseUrl
    And path 'users'
    When method get
    Then status 200

Switch environments with:

karate -e staging users.feature
karate-config.js# Global test configuration
src/test/java
└── examples
├── ExamplesTest.java# JUnit 5 test runner (Maven/Gradle only)
└── users
└── users.feature# Karate test script

Key points:

  • Feature files live next to Java files (not in separate folders)
  • karate-config.js goes in the classpath root (or project root for CLI)
  • No Java code required in feature files — only needed for the JUnit runner

Next Steps​

On This Page