GET STARTED

Standalone Execution

Run Karate tests without Maven or Gradle using the standalone JAR file - perfect for non-Java teams, quick local execution, or CI/CD pipelines.

Benefits of Standalone Execution

• No build tool required: Skip Maven and Gradle setup entirely
• Cross-platform: Works on Windows, macOS, and Linux with just Java installed
• Quick setup: Download once, run anywhere with a single command
• CI/CD friendly: Easy integration into any pipeline or script
• Team accessible: Ideal for teams not comfortable with Java build tools

Prerequisites

You need Java 17 or higher installed. Verify your installation:

Terminal

java -version

If you need to install Java, see the Install Dependencies guide.

Download the Standalone JAR

Download the latest karate.jar from the GitHub Releases page.

Look for the file named karate-<version>.jar (for example, karate-1.5.1.jar) under the Assets section of the latest release.

Version Compatibility

The standalone JAR version should match your feature file syntax. Always use the latest stable release for the best experience and newest features.

Basic Execution

Run a single feature file with this simple command:

Terminal

java -jar karate.jar users.feature

Run all feature files in a directory:

Terminal

java -jar karate.jar src/test/java/features

The command will execute your tests and generate an HTML report in the target/karate-reports directory.

Feature: User API Test

Scenario: Get user by ID
  Given url 'https://jsonplaceholder.typicode.com'
  And path 'users/1'
  When method get
  Then status 200
  And match response.name == '#string'

Save this as user-api.feature and run:

Terminal

java -jar karate.jar user-api.feature

Parallel Execution

Run tests in parallel to dramatically reduce execution time using the --threads or -T flag:

Terminal

# Run with 4 parallel threads
java -jar karate.jar --threads 4 src/test/java/features

# Short form
java -jar karate.jar -T 4 src/test/java/features

The parallel execution is a core feature and works identically to the JUnit parallel runner.

Tag Filtering

Run only tests with specific tags using the --tags or -t flag:

Terminal

# Run only @smoke tagged scenarios
java -jar karate.jar --tags @smoke src/test/java/features

# Run @smoke OR @regression
java -jar karate.jar --tags @smoke,@regression src/test/java/features

# Run @smoke AND @api
java -jar karate.jar --tags @smoke --tags @api src/test/java/features

# Exclude @slow tests
java -jar karate.jar --tags ~@slow src/test/java/features

Feature: User Management

@smoke @api
Scenario: Quick health check
  Given url baseUrl
  And path 'health'
  When method get
  Then status 200

@regression
Scenario: Complete user flow
  Given url baseUrl
  And path 'users'
  And request { name: 'John', email: 'john@example.com' }
  When method post
  Then status 201

Environment Configuration

Pass environment variables and system properties to configure your tests:

Terminal

# Set environment (used in karate-config.js)
java -jar karate.jar -Dkarate.env=qa src/test/java/features

# Set custom properties
java -jar karate.jar -Dbaseurl=https://api.example.com -Dkarate.env=prod src/test/java/features

# Combine with parallel execution and tags
java -jar karate.jar -Dkarate.env=staging -T 5 --tags @smoke src/test/java/features

Your karate-config.js can access these properties:

karate-config.js

function fn() {
  var env = karate.env; // 'qa', 'staging', 'prod', etc.
  var config = {
    baseUrl: 'https://api-dev.example.com'
  };

  if (env === 'qa') {
    config.baseUrl = 'https://api-qa.example.com';
  } else if (env === 'prod') {
    config.baseUrl = 'https://api.example.com';
  }

  return config;
}

Custom Report Directory

Specify a custom output directory for test reports:

Terminal

java -jar karate.jar --output reports/test-results src/test/java/features

This creates reports in reports/test-results instead of the default target/karate-reports.

Running Specific Scenarios

Run a single scenario by specifying the line number:

Terminal

# Run scenario starting at line 12
java -jar karate.jar user-api.feature:12

CI/CD Integration

The standalone JAR integrates easily into any CI/CD system.

GitHub Actions Example

.github/workflows/api-tests.yml

name: API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Download Karate JAR
        run: |
          wget https://github.com/karatelabs/karate/releases/download/v1.5.1/karate-1.5.1.jar
          mv karate-1.5.1.jar karate.jar

      - name: Run API Tests
        run: java -jar karate.jar -T 4 --tags @smoke src/test/java/features

      - name: Upload Test Reports
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: test-reports
          path: target/karate-reports

GitLab CI Example

.gitlab-ci.yml

api-tests:
  image: openjdk:17-slim
  stage: test
  script:
    - wget https://github.com/karatelabs/karate/releases/download/v1.5.1/karate-1.5.1.jar -O karate.jar
    - java -jar karate.jar -Dkarate.env=qa -T 4 src/test/java/features
  artifacts:
    when: always
    paths:
      - target/karate-reports
    reports:
      junit: target/karate-reports/*.xml

Jenkins Pipeline Example

Jenkinsfile

pipeline {
    agent any

    stages {
        stage('Test') {
            steps {
                sh '''
                    wget https://github.com/karatelabs/karate/releases/download/v1.5.1/karate-1.5.1.jar -O karate.jar
                    java -jar karate.jar -Dkarate.env=staging -T 5 --tags @regression src/test/java/features
                '''
            }
        }
    }

    post {
        always {
            publishHTML([
                reportDir: 'target/karate-reports',
                reportFiles: 'karate-summary.html',
                reportName: 'Karate Test Report'
            ])
        }
    }
}

Standalone vs Build Tools

Understanding when to use the standalone JAR versus Maven or Gradle:

Aspect	Standalone JAR	Maven/Gradle
Setup complexity	Minimal - just download	Requires project configuration
Dependency management	None	Full dependency resolution
IDE integration	Basic	Excellent with plugins
Build lifecycle	Not integrated	Fully integrated
Team familiarity	Accessible to all	Requires Java knowledge
CI/CD integration	Simple scripts	Standardized commands
Best for	Quick tests, non-Java teams, scripting	Java projects, complex builds, team workflows

When to Use Standalone

• Quick local testing: Run tests without setting up a project
• Non-Java teams: Frontend, Python, or Ruby teams testing APIs
• Simple CI/CD: Straightforward pipeline integration
• Scripting: Automation scripts and cron jobs
• Learning: Getting started with Karate quickly

When to Use Maven/Gradle

• Java projects: Already using Java build tools
• Complex dependencies: Custom Java code or libraries
• IDE workflows: Full IDE integration and debugging
• Team standards: Team already uses Maven or Gradle
• Advanced features: Custom test lifecycle integration

Next Steps

• Learn about parallel execution strategies: Parallel Execution
• Explore command-line options with Maven and Gradle: Command Line
• Configure test environments: Configuration
• Set up your IDE for better developer experience: VS Code or IntelliJ