Karate (karatelabs/karate)

Karate

https://github.com/karatelabs/karate
Admin
Karate is an open-source framework that combines API testing, mocks, performance testing, and UI...

Tokens:116,776
Snippets:945
Trust Score:8.7
Update:1 week ago
Show doc for...
Context Summary (auto-generated)
Raw
# Karate

Karate is an open-source framework that combines API testing, mocks, performance testing, and UI automation into a single, unified tool. Built on Java 21+ with virtual threads for massive parallelism, Karate uses a Gherkin-based DSL that makes test automation accessible without requiring programming expertise while still providing full JavaScript and Java interoperability for advanced use cases.

The framework consists of several modules: `karate-core` provides the HTTP client/server, match assertions, and test runtime; `karate-js` offers a lightweight thread-safe JavaScript engine; `karate-gatling` enables performance testing with Gatling integration; and `karate-junit6` provides JUnit integration. Karate v2 is a complete ground-up rewrite featuring an embedded JS engine, declarative authentication, Chai-style BDD assertions, and comprehensive browser automation via Chrome DevTools Protocol and W3C WebDriver.

## Running Karate Tests Programmatically

The `Runner` class is the main entry point for executing Karate tests from Java. It provides a fluent builder API to configure paths, tags, environments, and parallel execution settings.

```java
import io.karatelabs.core.Runner;
import io.karatelabs.core.SuiteResult;

// Run tests from a directory with tag filtering and parallel execution
SuiteResult result = Runner.path("src/test/resources/features")
    .tags("@smoke")
    .karateEnv("dev")
    .parallel(5);

// Check results
System.out.println("Features passed: " + result.getFeaturesPassed());
System.out.println("Scenarios failed: " + result.getScenariosFailed());
if (result.getFailCount() > 0) {
    System.exit(1);
}
```

## Basic HTTP API Testing

Karate feature files use Gherkin syntax with built-in HTTP keywords. The `url`, `path`, `request`, `method`, and `status` keywords handle HTTP operations while `match` provides powerful JSON assertions.

```gherkin
Feature: Cats CRUD Operations

  Background:
    * url 'http://localhost:8080/api'

  Scenario: Create and read a cat
    # Create a new cat
    Given path 'cats'
    And request { name: 'Fluffy', age: 3 }
    When method post
    Then status 201
    And match response contains { id: '#string', name: 'Fluffy', age: 3 }
    * def catId = response.id

    # Read the created cat
    Given path 'cats', catId
    When method get
    Then status 200
    And match response == { id: '#(catId)', name: 'Fluffy', age: 3 }
```

## Match Assertions and Fuzzy Markers

Karate provides powerful assertion capabilities with fuzzy markers for flexible matching. Markers like `#string`, `#number`, `#array`, `#boolean`, `#null`, `#present`, `#notpresent`, `#uuid`, `#regex`, and `#ignore` enable schema validation and partial matching.

```gherkin
Feature: Match Examples

  Scenario: Various match operations
    * def response = { id: 123, name: 'Test', items: [1, 2, 3], active: true }

    # Exact match
    * match response.name == 'Test'

    # Fuzzy type matching
    * match response == { id: '#number', name: '#string', items: '#array', active: '#boolean' }

    # Contains matching
    * match response contains { name: 'Test' }
    * match response.items contains 2

    # Each element matching
    * match each response.items == '#number'

    # Regex matching
    * match response.name == '#regex [A-Z][a-z]+'

    # Not contains
    * match response !contains { missing: '#present' }

    # Schema validation with optional fields
    * match response == { id: '#number', name: '#string', items: '#array', active: '#boolean', optional: '##string' }
```

## HTTP Configuration and Authentication

Karate supports declarative authentication including Basic, Bearer, and OAuth2 with automatic token refresh. SSL configuration, proxy settings, and custom headers are configured using the `configure` keyword.

```gherkin
Feature: HTTP Configuration

  Background:
    * url 'https://api.example.com'

    # Basic authentication
    * configure auth = { type: 'basic', username: 'user', password: 'pass' }

    # Or Bearer token
    * configure auth = { type: 'bearer', token: 'my-jwt-token' }

    # Or OAuth2 with automatic token refresh
    * configure auth = { type: 'oauth2', tokenUrl: 'https://auth.example.com/token', clientId: 'my-client', clientSecret: 'secret' }

    # SSL configuration - trust all certificates
    * configure ssl = true

    # Or with keystore for mTLS
    * configure ssl = { keyStore: 'classpath:client.pfx', keyStorePassword: 'secret', keyStoreType: 'pkcs12' }

    # Custom headers for all requests
    * configure headers = { 'X-Api-Key': 'my-api-key', 'Accept': 'application/json' }

    # Proxy configuration
    * configure proxy = { host: 'proxy.example.com', port: 8080, username: 'proxyuser', password: 'proxypass' }

  Scenario: Make authenticated request
    Given path '/secure/data'
    When method get
    Then status 200
```

## Mock Server with Feature Files

Karate's mock server allows creating API test-doubles using feature files. Scenarios act as request matchers with JavaScript expressions determining routing. The Background executes once on startup, and variables persist across requests for stateful mocks.

```gherkin
Feature: Cats API Mock

  Background:
    * def cats = {}
    * def counter = { value: 0 }
    * configure cors = true
    * configure responseHeaders = { 'Content-Type': 'application/json' }

  Scenario: pathMatches('/cats/{id}') && methodIs('get')
    * def cat = cats[pathParams.id]
    * def response = cat ? cat : { error: 'Cat not found' }
    * def responseStatus = cat ? 200 : 404

  Scenario: pathMatches('/cats/{id}') && methodIs('delete')
    * def cat = cats[pathParams.id]
    * if (cat) delete cats[pathParams.id]
    * def response = cat ? { deleted: true } : { error: 'Cat not found' }
    * def responseStatus = cat ? 200 : 404

  Scenario: pathMatches('/cats') && methodIs('post')
    * counter.value = counter.value + 1
    * def id = counter.value + ''
    * cats[id] = request
    * cats[id].id = id
    * def response = cats[id]
    * def responseStatus = 201

  Scenario: pathMatches('/cats') && methodIs('get')
    * def response = karate.valuesOf(cats)
    * def responseStatus = 200

  Scenario:
    # Catch-all for unmatched requests
    * def responseStatus = 404
    * def response = { error: 'Not found' }
```

## Starting Mock Server from Java

The `MockServer` class provides a Java API for starting mock servers programmatically. It supports SSL, dynamic ports, watch mode for hot-reload, and can be used for integration testing.

```java
import io.karatelabs.core.MockServer;

// Start mock server from feature file
MockServer server = MockServer.feature("classpath:mocks/api.feature")
    .port(8080)
    .ssl(true)
    .arg(Map.of("baseData", initialData))
    .start();

// Start from inline feature string
MockServer server = MockServer.featureString("""
    Feature: Test Mock
    Scenario: methodIs('get')
      * def response = { hello: 'world' }
    """)
    .port(0)  // Dynamic port allocation
    .start();

// With watch mode for development (hot-reload on file changes)
MockServer server = MockServer.feature("api.feature")
    .port(8080)
    .watch(true)
    .start();

// Get server info
int port = server.getPort();
String url = server.getUrl();  // http://localhost:8080

// Stop server
server.stopAndWait();
```

## Starting Mock Server from Feature Files

Use `karate.start()` to launch mock servers from within feature files. This is useful for setting up test fixtures or running integration tests.

```gherkin
Feature: Integration Test with Mock

  Background:
    # Start mock server
    * def mockServer = karate.start({ mock: 'classpath:mocks/api.feature', port: 0 })
    * url mockServer.url

  Scenario: Test against mock
    Given path '/cats'
    And request { name: 'Fluffy' }
    When method post
    Then status 201
    And match response contains { id: '#string', name: 'Fluffy' }

  * mockServer.stop()
```

## Browser Automation with CDP

Karate provides browser automation via Chrome DevTools Protocol (CDP) with built-in auto-wait functionality. Configure the driver and use keywords like `driver`, `click`, `input`, `waitFor`, and `match` for UI testing.

```gherkin
Feature: Browser Automation

  Background:
    * configure driver = { type: 'chrome', headless: true, timeout: 30000 }

  Scenario: Login flow
    * driver 'http://localhost:8080/login'
    * match driver.title == 'Login Page'

    # Input credentials
    * input('#username', 'admin')
    * input('#password', 'secret123')

    # Click submit button
    * click('button[type=submit]')

    # Wait for navigation and verify
    * waitFor('#dashboard')
    * match driver.title == 'Dashboard'
    * match text('#welcome-message') contains 'Welcome, admin'

  Scenario: Element operations
    * driver serverUrl + '/form'

    # Check element existence
    * match exists('#submit-btn') == true
    * match exists('#nonexistent') == false

    # Get text and attributes
    * def headerText = text('h1')
    * def placeholder = attribute('#email', 'placeholder')

    # Execute JavaScript
    * def result = script('document.querySelectorAll("input").length')
    * assert result >= 3

    # Screenshot
    * screenshot()
```

## Wait Methods for Browser Automation

Karate provides comprehensive wait methods for reliable UI testing. Auto-wait is built into element operations, but explicit waits are available for complex scenarios.

```gherkin
Feature: Wait Methods

  Background:
    * configure driver = { type: 'chrome', headless: true, retryCount: 5, retryInterval: 500 }

  Scenario: Various wait patterns
    * driver serverUrl + '/dynamic-page'

    # Wait for element to exist
    * waitFor('#dynamic-content')

    # Wait for any of multiple elements
    * def found = waitForAny('#success-message', '#error-message')

    # Wait for specific text
    * waitForText('#status', 'Complete')

    # Wait for element to be enabled
    * waitForEnabled('#submit-btn')

    # Wait for URL to contain string
    * waitForUrl('/dashboard')

    # Wait for JavaScript condition
    * waitUntil("document.readyState == 'complete'")

    # Wait for element with JavaScript expression
    * waitUntil('#loading', '!_.classList.contains("active")')

    # Wait for specific result count
    * waitForResultCount('.item', 10)
```

## W3C WebDriver Support

Karate supports W3C WebDriver for cross-browser testing with Firefox, Safari, and Edge. Configure the driver type and optional capabilities for remote execution.

```gherkin
Feature: Cross-Browser Testing

  Scenario: Firefox via geckodriver
    * configure driver = { type: 'geckodriver', headless: true }
    * driver 'http://localhost:8080'
    * match driver.title == 'Home Page'

  Scenario: Safari via safaridriver
    * configure driver = { type: 'safaridriver' }
    * driver 'http://localhost:8080'
    * match driver.title == 'Home Page'

  Scenario: Remote WebDriver (SauceLabs/BrowserStack)
    * configure driver = { type: 'chromedriver', webDriverUrl: 'https://ondemand.saucelabs.com:443/wd/hub', capabilities: { platformName: 'Windows 10', 'sauce:options': { tunnelId: 'my-tunnel' } } }
    * driver 'http://localhost:8080'
    * match driver.title == 'Home Page'
```

## Performance Testing with Gatling

Karate integrates with Gatling for performance testing using a pure Java DSL. Define load profiles, chain feature executions, and report HTTP metrics to Gatling's StatsEngine.

```java
import io.gatling.javaapi.core.*;
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.karatelabs.gatling.KarateDsl.*;

public class LoadTestSimulation extends Simulation {

    // Define protocol with URI patterns for metric grouping
    KarateProtocolBuilder protocol = karateProtocol(
        uri("/cats/{id}").nil(),
        uri("/cats").pauseFor(method("get", 10), method("post", 20))
    );

    // Data feeder for parameterized tests
    Iterator<Map<String, Object>> feeder = Stream.iterate(0, i -> i + 1)
        .map(i -> Map.<String, Object>of("name", "Cat" + i))
        .iterator();

    // CRUD operations scenario
    ScenarioBuilder crud = scenario("CRUD Operations")
        .exec(karateFeature("classpath:features/cats-crud.feature"));

    // Chained operations with feeders
    ScenarioBuilder chained = scenario("Chained Operations")
        .feed(feeder)
        .exec(karateSet("name", s -> s.getString("name")))
        .exec(karateFeature("classpath:features/cats-create.feature"))
        .exec(karateFeature("classpath:features/cats-read.feature"));

    // Silent warm-up (no metrics reported)
    ScenarioBuilder warmup = scenario("Warm-up")
        .exec(karateFeature("classpath:features/cats-crud.feature").silent());

    {
        setUp(
            warmup.injectOpen(atOnceUsers(1)),
            crud.injectOpen(rampUsers(5).during(5)),
            chained.injectOpen(rampUsers(10).during(30))
        ).protocols(protocol.build());
    }
}
```

## Custom Performance Events

Capture custom performance metrics for non-HTTP operations like database calls, gRPC, or external services using the `PerfContext` interface.

```java
// Java helper class
public class TestUtils {
    public static Map<String, Object> myDatabaseCall(Map<String, Object> args, PerfContext karate) {
        long start = System.currentTimeMillis();

        // Simulate database operation
        Thread.sleep(100);
        Map<String, Object> result = Map.of("success", true, "rows", 42);

        long end = System.currentTimeMillis();
        karate.capturePerfEvent("database-query", start, end);

        return result;
    }
}
```

```gherkin
Feature: Custom Performance Events

  Scenario: Database operation with perf tracking
    * def result = Java.type('utils.TestUtils').myDatabaseCall({}, karate)
    * match result.success == true
```

## JavaScript Engine Usage

Karate includes a lightweight thread-safe JavaScript engine (`karate-js`) that can be used standalone. It provides full Java interop and is optimized for concurrent execution.

```java
import io.karatelabs.js.Engine;

// Basic evaluation
Engine engine = new Engine();
Object result = engine.eval("1 + 2");  // Returns 3

// Java interop
Map<String, Object> context = new HashMap<>();
context.put("greeting", "Hello");
engine.putAll(context);
Object message = engine.eval("greeting + ' World'");  // Returns "Hello World"

// Complex operations
engine.eval("""
    function calculateTotal(items) {
        return items.reduce((sum, item) => sum + item.price, 0);
    }
    """);
Object total = engine.eval("calculateTotal([{price: 10}, {price: 20}])");  // Returns 30
```

## Calling Other Features and Variable Passing

Use `call` and `callonce` to compose features and share data. Variables from called features are available in the calling scope.

```gherkin
Feature: Feature Composition

  Background:
    * def authResult = callonce read('classpath:auth/login.feature')
    * def token = authResult.token
    * configure headers = { Authorization: '#("Bearer " + token)' }

  Scenario: Use authenticated session
    * url 'http://localhost:8080/api'
    Given path '/protected/resource'
    When method get
    Then status 200
```

```gherkin
# auth/login.feature
@ignore
Feature: Login Helper

  Scenario: Get authentication token
    * url 'http://localhost:8080/auth'
    Given path '/login'
    And request { username: 'admin', password: 'secret' }
    When method post
    Then status 200
    * def token = response.token
```

## Karate Configuration File

The `karate-config.js` file provides global configuration for all tests. It runs once per test suite and can set environment-specific variables.

```javascript
function fn() {
  var env = karate.env || 'dev';
  karate.log('karate.env =', env);

  var config = {
    baseUrl: 'http://localhost:8080',
    timeout: 5000
  };

  if (env === 'dev') {
    config.baseUrl = 'http://dev.example.com';
  } else if (env === 'staging') {
    config.baseUrl = 'https://staging.example.com';
    config.timeout = 10000;
  } else if (env === 'prod') {
    config.baseUrl = 'https://api.example.com';
    config.timeout = 30000;
  }

  // Configure driver for UI tests
  karate.configure('driver', { type: 'chrome', headless: true });

  // Configure SSL for all requests
  karate.configure('ssl', true);

  // Set default headers
  karate.configure('headers', { 'Accept': 'application/json' });

  return config;
}
```

## CLI Usage

Run Karate tests from the command line with the `karate run` command. Supports tag filtering, parallel execution, environment selection, and multiple output formats.

```bash
# Run all tests in a directory
karate run src/test/features

# Run with tag filtering
karate run -t @smoke -t ~@slow features/

# Run with specific environment and parallel threads
karate run -e staging -T 5 features/

# Run specific scenario by line number
karate run tests/users.feature:10

# Enable multiple report formats
karate run -f cucumber:json,junit:xml features/

# Run with log masking for sensitive data
karate run --log-mask PASSWORDS,CREDIT_CARDS features/

# Clean output before run
karate run -C -o target/reports features/

# Start mock server
karate mock -m api.feature -p 8080

# Mock server with SSL and watch mode
karate mock -m api.feature -p 8443 --ssl -W
```

## JUnit 6 Integration

Use `@Karate.Test` annotation for IDE integration and running individual features as JUnit tests.

```java
import io.karatelabs.junit6.Karate;

class UsersTest {

    @Karate.Test
    Karate testUsers() {
        return Karate.run("users").relativeTo(getClass());
    }

    @Karate.Test
    Karate testUsersWithTags() {
        return Karate.run("classpath:features/users.feature")
            .tags("@smoke")
            .karateEnv("dev");
    }
}
```

## Maven and Gradle Dependencies

Add Karate to your project using Maven or Gradle. The `karate-core` module includes all essential functionality.

```xml
<!-- Maven -->
<dependency>
    <groupId>io.karatelabs</groupId>
    <artifactId>karate-core</artifactId>
    <version>2.0.1.RC1</version>
    <scope>test</scope>
</dependency>

<!-- For JUnit 6 integration -->
<dependency>
    <groupId>io.karatelabs</groupId>
    <artifactId>karate-junit6</artifactId>
    <version>2.0.1.RC1</version>
    <scope>test</scope>
</dependency>

<!-- For Gatling performance testing -->
<dependency>
    <groupId>io.karatelabs</groupId>
    <artifactId>karate-gatling</artifactId>
    <version>2.0.1.RC1</version>
    <scope>test</scope>
</dependency>
```

```groovy
// Gradle
testImplementation 'io.karatelabs:karate-core:2.0.1.RC1'
testImplementation 'io.karatelabs:karate-junit6:2.0.1.RC1'
```

Karate is ideal for teams seeking a unified testing solution that spans API testing, service virtualization, performance testing, and UI automation. Its Gherkin-based syntax enables collaboration between technical and non-technical team members while the powerful Java and JavaScript interoperability satisfies advanced testing requirements. The framework integrates seamlessly with CI/CD pipelines through JUnit, generates comprehensive HTML reports, and supports parallel execution with virtual threads for efficient test runs.

For API testing, Karate excels at contract testing, schema validation, and integration testing with its declarative HTTP client and powerful match assertions. The mock server capability enables service virtualization for isolated testing and development without external dependencies. Browser automation via CDP and W3C WebDriver supports end-to-end testing across Chrome, Firefox, Safari, and Edge with cloud provider integration for BrowserStack and SauceLabs. Performance testing with Gatling integration allows teams to reuse functional tests for load testing, providing a complete testing pyramid solution within a single framework.