Karate Testing Framework

Karate is an open-source unified framework designed to combine several testing disciplines into a single tool. It supports:

• API testing
• Mocks
• Performance testing
• UI automation

Karate v2 is a unified test automation framework that combines API testing, mocking, and performance testing. It is built on Java 21+ and features a custom, thread-safe JavaScript engine designed for parallel execution.

Key capabilities include:

• API Test Automation: Expressive Gherkin-based tests with JSON and XML assertions.
• Mock Servers: Built-in HTTP server for dynamic API mocking.
• Performance Testing: Seamless transition from functional tests to load tests.
• HTML Templating: Thymeleaf-based templating with support for HTMX and AlpineJS.
• Thread-Safe JavaScript: A lightweight JS engine for the JVM optimized for concurrency.

The karate-core framework consists of several specialized modules:

• HTTP (io.karatelabs.io.http): Provides an Apache HttpClient-based client (with request builder) and a Netty-based server. Supports Basic, Bearer, and OAuth2 (Client Credentials, Authorization Code with PKCE) authentication, session management with cookies, and CSRF protection.
• Markup (io.karatelabs.markup): A Thymeleaf-based engine featuring a custom Karate Dialect, built-in HTMX support, and integration with the karate-js engine.
• Match (io.karatelabs.match): An assertion library for JSON (with wildcards), XML, schema validation, and fuzzy matching.
• Core Runtime (io.karatelabs.core): Includes ScenarioRuntime for test execution and KarateJs as a bridge to the JavaScript engine.

The karate-js engine is a lightweight, thread-safe JavaScript engine implemented in Java. It targets idiomatic ES6 and has minimal dependencies (SLF4J and JSON-smart).

Core packages include:

• io.karatelabs.js: Core JavaScript engine (interpreter, runtime, built-in types).
• io.karatelabs.parser: Parsing infrastructure (lexer, parser, AST nodes).
• io.karatelabs.common: Shared utilities (file, OS, string operations).

The Karate match engine (io.karatelabs.match) performs deep comparisons and collects all mismatches in a single pass rather than failing on the first one. This allows for fixing multiple errors in one iteration.

It supports Fuzzy Markers for schema-like validation:

• #string, #number, #null, #notpresent
• #regex(...)
• #?<expr> (JS predicate)
• ## (optional marker)
• $ (cross-field references)

The Karate v2 CLI uses a two-tier architecture to separate system management from test execution:

1. Rust Launcher (karate binary): Handles installation and management tasks. It provides commands for setup, update, config, init, doctor, and version.
2. Java CLI (io.karatelabs.Main): Handles runtime execution and test features. It receives arguments from the Rust launcher and provides commands for run, mock, clean, and init (note: init is implemented in Rust to scaffold projects before the JVM is required).

Use the Rust launcher for environment setup and the Java CLI for running your actual test suites.

The karate-gatling module allows for performance testing by integrating Karate's functional testing capabilities with the Gatling engine.

Key Integration Details:

• DSL Strategy: Uses a Java-only DSL. Scala users should use the Java DSL directly.
• Session Variables: Accessing session variables requires using the __karate or __gatling prefix. Note that unprefixed top-level access is a breaking change from v1.
• Async Model: Integrates with Gatling's execution model using PerfHook.submit().
• Reporting: Supports both HTML (Highcharts) and JSON formats (--format json).
• Scope: The CLI scope is limited to features only (no --simulation class support).

Karate's execution model follows a hierarchical structure: a Suite orchestrates the execution, which manages FeatureRuntime instances. Each feature contains ScenarioRuntime instances, which in turn use a StepExecutor to dispatch actions. The StepExecutor interacts with specialized engines for matching, HTTP communication, and other actions.

Suite → FeatureRuntime → ScenarioRuntime → StepExecutor
                                               ↓
                              ┌────────────────┼────────────────┐
                              ▼                ▼                ▼
                         Match Engine    Http Client    Other Actions