GET STARTED

Installation

Get Karate up and running in your project in just a few minutes. Choose the installation method that best suits your development environment.

Prerequisites

Before installing Karate, ensure you have:

Java 17 or higher (as required by Karate 1.5.1+)
Your preferred build tool (Maven, Gradle) or Node.js

Installation Methods

Maven

Karate provides flexible Maven integration options to suit different project needs.

Basic Dependency (Recommended)

The JUnit 5 variant provides the best IDE experience and is recommended for most projects:

<dependency>
    <groupId>io.karatelabs</groupId>
    <artifactId>karate-junit5</artifactId>
    <version>1.5.1</version>
    <scope>test</scope>
</dependency>

Core Dependency (Minimal)

For minimal setups or when you want to run tests directly without JUnit:

<dependency>
    <groupId>io.karatelabs</groupId>
    <artifactId>karate-core</artifactId>
    <version>1.5.1</version>
    <scope>test</scope>
</dependency>

Fat JAR (For Dependency Conflicts)

If you encounter dependency conflicts with Netty, Thymeleaf, ANTLR, or other libraries, use the "all" classifier:

<dependency>
    <groupId>io.karatelabs</groupId>
    <artifactId>karate-core</artifactId>
    <version>1.5.1</version>
    <classifier>all</classifier>
    <scope>test</scope>
</dependency>

Note: For complex projects with many dependencies, consider using Maven profiles to separate testing dependencies from development dependencies.

Quick Start with Archetype

Create a complete Karate project skeleton with one command:

mvn archetype:generate \
  -DarchetypeGroupId=io.karatelabs \
  -DarchetypeArtifactId=karate-archetype \
  -DarchetypeVersion=1.5.1 \
  -DgroupId=com.mycompany \
  -DartifactId=myproject

Corporate Proxy Issues: If the archetype command fails behind a corporate proxy, temporarily disable or rename your Maven settings.xml file and try again.

Recommended Build Configuration

To keep test files organized alongside your Java classes, add this to your <build> section:

<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>
            <configuration>
                <includes>
                    <include>**/*Test.java</include>
                </includes>
                <systemProperties>
                    <karate.options>--tags ~@ignore</karate.options>
                </systemProperties>
            </configuration>
        </plugin>
    </plugins>
</build>

This configuration allows you to:

Keep .feature files alongside .java files
Configure default test execution options
Set up proper test inclusion patterns

Maven Command Line Examples

# Run all tests
mvn test

# Run a specific test class
mvn test -Dtest=CatsRunner

# Run with specific tags
mvn test "-Dkarate.options=--tags @smoke"

# Run with environment
mvn test -DargLine="-Dkarate.env=staging"

# Run a specific feature file
mvn test "-Dkarate.options=classpath:features/users.feature" -Dtest=TestRunner

Gradle

Karate integrates seamlessly with Gradle projects. For detailed Gradle-specific guidance, also refer to the Karate Gradle Wiki.

Basic Dependency (Recommended)

Add to your build.gradle:

testImplementation 'io.karatelabs:karate-junit5:1.5.1'

Or with Kotlin DSL (build.gradle.kts):

testImplementation("io.karatelabs:karate-junit5:1.5.1")

Core Dependency (Minimal)

For minimal setups without JUnit 5:

testImplementation 'io.karatelabs:karate-core:1.5.1'

Recommended Build Configuration

To organize test files alongside Java classes and enable proper test execution:

sourceSets {
    test {
        resources {
            srcDir file('src/test/java')
            exclude '**/*.java'
        }
    }
}

test {
    // Enable karate.options and karate.env system properties
    systemProperty "karate.options", System.properties.getProperty("karate.options")
    systemProperty "karate.env", System.properties.getProperty("karate.env")

    // Ensure tests are always run (disable up-to-date checks)
    outputs.upToDateWhen { false }

    // Optional: Configure test inclusion patterns
    include '**/*Test.java'
}

For Kotlin DSL (build.gradle.kts):

sourceSets {
    test {
        resources {
            srcDir("src/test/java")
            exclude("**/*.java")
        }
    }
}

tasks.test {
    systemProperty("karate.options", System.getProperty("karate.options"))
    systemProperty("karate.env", System.getProperty("karate.env"))
    outputs.upToDateWhen { false }
    include("**/*Test.java")
}

Gradle Command Line Examples

# Run all tests
./gradlew test

# Run a specific test class
./gradlew test --tests *CatsRunner
# Alternative syntax
./gradlew test -Dtest.single=CatsRunner

# Run with specific tags
./gradlew test -Dkarate.options="--tags @smoke"

# Run with environment
./gradlew test -Dkarate.env=staging

# Run specific feature file
./gradlew test -Dkarate.options="classpath:features/users.feature" --tests *TestRunner

NPM / Node.js

NPM Installation

Perfect for JavaScript/TypeScript projects

# Install globally
npm install -g @karatelabs/karate-cli

# Or add to your project

npm install --save-dev @karatelabs/karate-cli

# Run tests

npx karate test *.feature

Standalone JAR

Download and run Karate without any build tool:

# Download the latest standalone JAR
curl -L -o karate.jar \
  https://github.com/karatelabs/karate/releases/download/v1.5.1/karate-1.5.1.jar

# Run tests
java -jar karate.jar test.feature

Docker

Run Karate in a containerized environment:

# Use specific version
docker run --rm -v "$PWD":/workspace \
  karatelabs/karate:1.5.1 test.feature

# Or use latest
docker run --rm -v "$PWD":/workspace \
  karatelabs/karate:latest test.feature

IDE Setup

VS Code

Install the official Karate extension for the best experience:

GET/vscode/extension/karatelabs.karate

Official Karate VS Code Extension

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Search for "Karate"
Install the extension by Karate Labs

Features:

✅ Syntax highlighting
✅ Auto-completion
✅ Run tests from editor
✅ Debug support
✅ Test results in sidebar

IntelliJ IDEA

Install the Cucumber for Java plugin
Associate .feature files with Cucumber
Configure run configurations for Karate tests

Project Structure

Recommended project structure for Karate:

my-project/
├── src/
│   └── test/
│       └── java/
│           ├── karate-config.js       # Global configuration
│           ├── features/              # Feature files
│           │   ├── users/
│           │   │   └── users.feature
│           │   └── products/
│           │       └── products.feature
│           └── TestRunner.java        # JUnit runner
├── pom.xml or build.gradle
└── README.md

Quick Test

Create your first test to verify the installation:

hello-world.feature

Verify your Karate installation

Feature: Hello World

Scenario: Verify Karate is working

- print 'Hello from Karate!'
- def myName = 'World'
- print 'Hello', myName
- assert 2 + 2 == 4

Run with Maven:

mvn test -Dtest=HelloWorldTest

Run with Gradle:

gradle test --tests HelloWorldTest

Run standalone:

java -jar karate.jar hello-world.feature

Configuration

karate-config.js

Global configuration for all environments

function fn() {
var env = karate.env || 'dev';

var config = {
  env: env,
  baseUrl: 'https://api.example.com',
  apiKey: 'default-key',
  timeout: 5000
};

// Environment-specific configuration
if (env === 'dev') {
  config.baseUrl = 'http://localhost:8080';
  config.apiKey = 'dev-api-key';
} else if (env === 'staging') {
  config.baseUrl = 'https://staging-api.example.com';
  config.apiKey = 'staging-api-key';
} else if (env === 'prod') {
  config.baseUrl = 'https://api.example.com';
  config.apiKey = 'prod-api-key';
}

// Global Karate configuration
karate.configure('connectTimeout', config.timeout);
karate.configure('readTimeout', config.timeout);
karate.configure('retry', { count: 2, interval: 1000 });

// Custom logging
karate.log('Environment:', env);
karate.log('Base URL:', config.baseUrl);

return config;
}

Environment Switching

Karate supports dynamic environment switching through the karate.env system property. By default, karate.env is null when accessed within karate-config.js.

Maven Environment Switching

# Set environment via argLine (recommended)
mvn test -DargLine="-Dkarate.env=staging"

# Run specific test with environment
mvn test -DargLine="-Dkarate.env=e2e" -Dtest=CatsRunner

# Multiple system properties
mvn test -DargLine="-Dkarate.env=prod -Dkarate.options='--tags @smoke'"

You can also configure this in your pom.xml:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <systemProperties>
            <karate.env>staging</karate.env>
            <karate.options>--tags @regression</karate.options>
        </systemProperties>
    </configuration>
</plugin>

Gradle Environment Switching

# Set environment directly
./gradlew test -Dkarate.env=staging

# Run specific test with environment
./gradlew test -Dkarate.env=e2e --tests *CatsRunner

# Multiple properties
./gradlew test -Dkarate.env=prod -Dkarate.options="--tags @smoke"

Ensure your build.gradle passes system properties (as shown in the Gradle configuration above):

test {
    systemProperty "karate.env", System.properties.getProperty("karate.env")
    systemProperty "karate.options", System.properties.getProperty("karate.options")
}

Programmatic Environment Setting

You can also set the environment programmatically in your Java runner:

// Set before running tests
System.setProperty("karate.env", "pre-prod");

// Or use the parallel runner API (recommended)
Results results = Runner.path("classpath:features")
    .karateEnv("staging")
    .parallel(5);

Advanced Configuration

Maven Profiles for Environment Management

For complex projects, use Maven profiles to manage environment-specific configurations:

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <karate.env>dev</karate.env>
            <karate.options>--tags ~@slow</karate.options>
        </properties>
    </profile>
    <profile>
        <id>ci</id>
        <properties>
            <karate.env>ci</karate.env>
            <karate.options>--tags @smoke</karate.options>
        </properties>
    </profile>
</profiles>

Then run with: mvn test -P ci

Gradle Environment Profiles

For Gradle, you can use similar approach with different tasks:

task testDev(type: Test) {
    systemProperty "karate.env", "dev"
    systemProperty "karate.options", "--tags ~@slow"
}

task testCI(type: Test) {
    systemProperty "karate.env", "ci"
    systemProperty "karate.options", "--tags @smoke"
}

Then run with: ./gradlew testCI

Troubleshooting

Common Issues

Java Version Error

Error: Karate requires Java 17 or higher

Solution: Update your Java version:

java -version  # Check current version
# Install Java 17 or higher
# Karate works fine with OpenJDK

Maven-Specific Issues

No Tests Executed

[ERROR] No tests were executed!

Solutions:

Ensure test classes follow naming convention (*Test.java):
```
@Karate.Test
class UsersTest {
    // Test methods
}
```

Check Maven Surefire plugin configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <includes>
            <include>**/*Test.java</include>
        </includes>
    </configuration>
</plugin>

Dependency Conflicts

NoClassDefFoundError or ClassNotFoundException

Solution: Use the "all" classifier to avoid conflicts:

<dependency>
    <groupId>io.karatelabs</groupId>
    <artifactId>karate-core</artifactId>
    <version>1.5.1</version>
    <classifier>all</classifier>
    <scope>test</scope>
</dependency>

Maven Archetype Fails

[ERROR] Failed to execute archetype

Solutions:

Corporate Proxy: Temporarily disable Maven settings.xml

Windows PowerShell: Use quotes around property values:

mvn archetype:generate \
  "-DarchetypeGroupId=io.karatelabs" \
  "-DarchetypeArtifactId=karate-archetype"

System Properties Not Working

karate.env or karate.options not recognized

Solution: Use argLine for system properties:

mvn test -DargLine="-Dkarate.env=staging -Dkarate.options='--tags @smoke'"

Gradle-Specific Issues

System Properties Not Passed

karate.env or karate.options ignored

Solution: Ensure your build.gradle passes system properties:

test {
    systemProperty "karate.options", System.properties.getProperty("karate.options")
    systemProperty "karate.env", System.properties.getProperty("karate.env")
    outputs.upToDateWhen { false }  // Ensure tests always run
}

Tests Not Running (Up-to-Date)

Task :test UP-TO-DATE

Solution: Disable up-to-date checks for test task:

test {
    outputs.upToDateWhen { false }
}

Feature Files Not Found

Feature file not found in classpath

Solution: Configure sourceSet to include test resources:

sourceSets {
    test {
        resources {
            srcDir file('src/test/java')
            exclude '**/*.java'
        }
    }
}

Gradle Task Not Found

Task 'testRunner' not found

Solution: Use the correct syntax:

# Correct
./gradlew test --tests *CatsRunner
# Or
./gradlew test -Dtest.single=CatsRunner

General Build Issues

OutOfMemoryError During Tests

Maven Solution:

mvn test -DargLine="-Xmx2g -XX:MaxMetaspaceSize=512m"

Gradle Solution:

test {
    jvmArgs '-Xmx2g', '-XX:MaxMetaspaceSize=512m'
}

Feature File Not Found

Feature file not found: test.feature

Solutions:

Place feature files in src/test/java (recommended) or src/test/resources
Use classpath reference: classpath:features/test.feature
Check file path in runner class

IDE Integration Issues

IntelliJ Not Recognizing Feature Files

Solution: Install Cucumber for Java plugin and associate .feature files

VS Code Karate Extension Not Working

Solution:

Install the official Karate extension by Karate Labs
Ensure Java is properly configured
Reload VS Code window

Performance Issues

Slow Test Execution

Solutions:

Use parallel execution:

Results results = Runner.path("classpath:features")
    .parallel(5);  // Use 5 threads

Configure timeouts:

// In karate-config.js
karate.configure('connectTimeout', 5000);
karate.configure('readTimeout', 5000);

Use tags to run subset of tests:

mvn test -Dkarate.options="--tags @smoke"

Next Steps

Now that Karate is installed, explore these topics:

Need help? Join our Discord community or check the FAQ.

Prerequisites​

Installation Methods​

Maven​

Basic Dependency (Recommended)​

Core Dependency (Minimal)​

Fat JAR (For Dependency Conflicts)​

Quick Start with Archetype​

Recommended Build Configuration​

Maven Command Line Examples​

Gradle​

Basic Dependency (Recommended)​

Core Dependency (Minimal)​

Recommended Build Configuration​

Gradle Command Line Examples​

NPM / Node.js​

NPM Installation

Standalone JAR​

Docker​

IDE Setup​

VS Code​

IntelliJ IDEA​

Project Structure​

Quick Test​

hello-world.feature

Configuration​

karate-config.js

Environment Switching​

Maven Environment Switching​

Gradle Environment Switching​

Programmatic Environment Setting​

Advanced Configuration​

Maven Profiles for Environment Management​

Gradle Environment Profiles​

Troubleshooting​

Common Issues​

Java Version Error​

Maven-Specific Issues​

No Tests Executed​

Dependency Conflicts​

Maven Archetype Fails​

System Properties Not Working​

Gradle-Specific Issues​

System Properties Not Passed​

Tests Not Running (Up-to-Date)​

Feature Files Not Found​

Gradle Task Not Found​

General Build Issues​

OutOfMemoryError During Tests​

Feature File Not Found​

IDE Integration Issues​

IntelliJ Not Recognizing Feature Files​

VS Code Karate Extension Not Working​

Performance Issues​

Slow Test Execution​

Next Steps​

Prerequisites

Installation Methods

Maven

Basic Dependency (Recommended)

Core Dependency (Minimal)

Fat JAR (For Dependency Conflicts)

Quick Start with Archetype

Recommended Build Configuration

Maven Command Line Examples

Gradle

Basic Dependency (Recommended)

Core Dependency (Minimal)

Recommended Build Configuration

Gradle Command Line Examples

NPM / Node.js

Standalone JAR

Docker

IDE Setup

VS Code

IntelliJ IDEA

Project Structure

Quick Test

Configuration

Environment Switching

Maven Environment Switching

Gradle Environment Switching

Programmatic Environment Setting

Advanced Configuration

Maven Profiles for Environment Management

Gradle Environment Profiles

Troubleshooting

Common Issues

Java Version Error

Maven-Specific Issues

No Tests Executed

Dependency Conflicts

Maven Archetype Fails

System Properties Not Working

Gradle-Specific Issues

System Properties Not Passed

Tests Not Running (Up-to-Date)

Feature Files Not Found

Gradle Task Not Found

General Build Issues

OutOfMemoryError During Tests

Feature File Not Found

IDE Integration Issues

IntelliJ Not Recognizing Feature Files

VS Code Karate Extension Not Working

Performance Issues

Slow Test Execution

Next Steps