karate/
├── karate-js/
├── karate-core/
├── karate-gatling/          # NEW
│   ├── pom.xml
│   ├── src/main/java/io/karatelabs/gatling/
│   │   ├── KarateDsl.java           # Public Java DSL entry point
│   │   ├── KarateProtocol.java      # Gatling protocol implementation
│   │   ├── KarateProtocolBuilder.java
│   │   ├── KarateFeatureAction.java # Feature execution action
│   │   ├── KarateFeatureBuilder.java
│   │   ├── KarateSetAction.java     # Session variable injection
│   │   ├── KarateUriPattern.java    # URI pattern + pause config
│   │   └── MethodPause.java         # Method/pause data class
│   ├── src/test/java/
│   │   └── io/karatelabs/gatling/
│   │       ├── GatlingSimulation.java  # Comprehensive test simulation
│   │       └── MockServer.java         # Test mock using v2 native mocks
│   ├── src/test/resources/
│   │   ├── karate-config.js
│   │   ├── features/                # Test feature files
│   │   └── logback-test.xml
│   └── README.md                    # Ported from v1 with updates
└── pom.xml                          # Add karate-gatling to modules

<dependencies>
    <!-- Karate -->
    <dependency>
        <groupId>io.karatelabs</groupId>
        <artifactId>karate-core</artifactId>
        <version>${project.version}</version>
    </dependency>

    <!-- Gatling 3.13.x -->
    <dependency>
        <groupId>io.gatling</groupId>
        <artifactId>gatling-core-java</artifactId>
        <version>3.13.5</version>
    </dependency>
    <dependency>
        <groupId>io.gatling.highcharts</groupId>
        <artifactId>gatling-charts-highcharts</artifactId>
        <version>3.13.5</version>
    </dependency>

    <!-- Scala 3 (for Gatling compatibility) -->
    <dependency>
        <groupId>org.scala-lang</groupId>
        <artifactId>scala3-library_3</artifactId>
        <version>3.4.0</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Scala 3 compiler -->
        <plugin>
            <groupId>net.alchim31.maven</groupId>
            <artifactId>scala-maven-plugin</artifactId>
            <version>4.9.0</version>
            <configuration>
                <scalaVersion>3.4.0</scalaVersion>
            </configuration>
        </plugin>

        <!-- Gatling Maven plugin -->
        <plugin>
            <groupId>io.gatling</groupId>
            <artifactId>gatling-maven-plugin</artifactId>
            <version>4.20.16</version>
        </plugin>
    </plugins>
</build>

package io.karatelabs.gatling;

public final class KarateDsl {

    // URI pattern builder
    public static KarateUriPattern.Builder uri(String pattern) { ... }

    // Protocol builder
    public static KarateProtocolBuilder karateProtocol(KarateUriPattern... patterns) { ... }

    // Feature action builder
    public static KarateFeatureBuilder karateFeature(String name, String... tags) { ... }

    // Session variable injection
    public static ActionBuilder karateSet(String key, Function<Session, Object> supplier) { ... }

    // Method pause helper
    public static MethodPause method(String method, int pauseMillis) { ... }
}

package io.karatelabs.gatling;

public class KarateProtocol implements Protocol {

    public static final String KARATE_KEY = "__karate";
    public static final String GATLING_KEY = "__gatling";

    private final Map<String, List<MethodPause>> uriPatterns;
    private BiFunction<HttpRequest, ScenarioRuntime, String> nameResolver = (req, sr) -> null;
    private Runner.Builder runner = Runner.builder();

    // Default name resolver using URI pattern matching
    public String defaultNameResolver(HttpRequest req, ScenarioRuntime sr) {
        String path = extractPath(req.getUrl());
        return uriPatterns.keySet().stream()
            .filter(pattern -> pathMatches(pattern, path))
            .findFirst()
            .orElse(path);
    }

    // Pause lookup
    public int pauseFor(String requestName, String method) { ... }

    // URI pattern matching (port from v1)
    public boolean pathMatches(String pattern, String path) { ... }
}

package io.karatelabs.gatling;

public class KarateFeatureAction implements Action {

    private final String featurePath;
    private final String[] tags;
    private final KarateProtocol protocol;
    private final StatsEngine statsEngine;
    private final Action next;
    private final boolean silent;

    @Override
    public void execute(Session session) {
        // Use PerfHook.submit() to match Gatling's execution model
        protocol.getPerfHook().submit(() -> executeFeature(session));
    }

    private void executeFeature(Session session) {
        // 1. Prepare session maps
        Map<String, Object> gatlingVars = new HashMap<>(session.attributes());
        Map<String, Object> karateVars = getOrCreate(session, KARATE_KEY);
        karateVars.put(GATLING_KEY, gatlingVars);

        // 2. Create Suite with PerfHook for metrics
        Suite suite = Suite.builder()
            .path(featurePath)
            .tags(tags)
            .perfHook(createPerfHook(session))
            .httpClientFactory(protocol.getHttpClientFactory())
            .build();

        // 3. Execute - aborts immediately on first failure
        SuiteResult result = suite.run();

        // 4. Update session and continue
        Session updated = updateSession(session, result);
        next.execute(updated);
    }

    private PerfHook createPerfHook(Session session) {
        return new PerfHook() {
            private HttpClient currentClient;

            @Override
            public String getPerfEventName(HttpRequest req, ScenarioRuntime sr) {
                String customName = protocol.getNameResolver().apply(req, sr);
                if (customName != null) return customName;
                return protocol.defaultNameResolver(req, sr);
            }

            @Override
            public void reportPerfEvent(PerfEvent event) {
                if (silent) return; // Skip for warm-up

                Status status = event.isFailed() ? KO : OK;
                statsEngine.logResponse(
                    session.scenario(),
                    session.groups(),
                    event.getName(),
                    event.getStartTime(),
                    event.getEndTime(),
                    status,
                    Option.apply(String.valueOf(event.getStatusCode())),
                    event.getMessage() != null ? Option.apply(event.getMessage()) : Option.empty()
                );

                // Apply pause after request
                int pauseMs = protocol.pauseFor(event.getName(), event.getMethod());
                if (pauseMs > 0) {
                    pause(pauseMs);
                }
            }

            @Override
            public void submit(Runnable runnable) {
                // Matches Gatling's execution model
                runnable.run();
            }

            @Override
            public void pause(Number millis) {
                // Use Gatling's non-blocking pause mechanism
                try {
                    Await.result(Future.never(), Duration.apply(millis.longValue(), TimeUnit.MILLISECONDS));
                } catch (TimeoutException e) {
                    // Expected - this is how Gatling's pause works
                }
            }

            @Override
            public void setHttpClient(HttpClient client) {
                this.currentClient = client;
            }

            @Override
            public void abortCurrentRequest() {
                // Called on Gatling timeout - abort mid-request
                if (currentClient != null) {
                    currentClient.abort();
                }
            }
        };
    }
}

// In PerfHook implementation
@Override
public void pause(Number millis) {
    // Gatling's non-blocking pause - waits without consuming threads
    try {
        Await.result(Future.never(), Duration.apply(millis.longValue(), TimeUnit.MILLISECONDS));
    } catch (TimeoutException e) {
        // Expected - timeout is the pause completion signal
    }
}

# Non-blocking pause - integrates with Gatling
* karate.pause(5000)

// io/karatelabs/core/PerfContext.java
package io.karatelabs.core;

/**
 * Interface for capturing custom performance events.
 * Used primarily for Gatling integration but designed as a NO-OP
 * when not in a performance testing context.
 */
public interface PerfContext {
    void capturePerfEvent(String name, long startTime, long endTime);
}

// In KarateJs.java
public class KarateJs extends KarateJsBase implements PerfContext {

    private Consumer<PerfEvent> perfEventHandler;

    @Override
    public void capturePerfEvent(String name, long startTime, long endTime) {
        if (perfEventHandler != null) {
            perfEventHandler.accept(new PerfEvent(name, startTime, endTime));
        }
        // NO-OP when perfEventHandler is null (normal Karate execution)
    }

    public void setPerfEventHandler(Consumer<PerfEvent> handler) {
        this.perfEventHandler = handler;
    }
}

// Simple data class
public record PerfEvent(String name, long startTime, long endTime) {}

// In KarateFeatureAction, before running feature
karateJs.setPerfEventHandler(event -> {
    if (!silent) {
        statsEngine.logResponse(
            session.scenario(), session.groups(),
            event.name(), event.startTime(), event.endTime(),
            Status.OK, 200, null
        );
    }
});

Scenario: Custom RPC
  * def result = Java.type('mock.MockUtils').myRpc({ sleep: 100 }, karate)

// MockUtils.java - clean typed API (same as v1!)
public static Map<String, Object> myRpc(Map<String, Object> args, PerfContext context) {
    long start = System.currentTimeMillis();
    // ... custom logic (database, gRPC, etc.) ...
    long end = System.currentTimeMillis();

    context.capturePerfEvent("myRpc", start, end);
    return Map.of("success", true);
}

Gatling Session                    Karate Context
─────────────────                  ──────────────
userId: 1                    →     __gatling.userId
name: "Fluffy"              →     __gatling.name
__karate: { catId: 123 }    ←     catId (from feature)

# Access Gatling variables
* def userId = karate.get('__gatling.userId', 0)

# Access previous Karate results
* def catId = __karate.catId

package io.karatelabs.gatling;

public class GatlingSimulation extends Simulation {

    // Start mock server using v2's Server class (dogfooding)
    static {
        MockServer.start();
    }

    KarateProtocolBuilder protocol = karateProtocol(
        uri("/cats/{id}").nil(),
        uri("/cats").pauseFor(method("get", 10), method("post", 20))
    );

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

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

    // Scenario 2: Chained 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"));

    // Scenario 3: Silent warm-up
    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(3).during(5))
        ).protocols(protocol.build());
    }
}

# features/cats-crud.feature
Feature: CRUD Operations

Scenario: Create and read cat
  Given url baseUrl
  And path 'cats'
  And request { name: 'Fluffy' }
  When method post
  Then status 201
  * def catId = response.id

  Given path 'cats', catId
  When method get
  Then status 200
  And match response.name == 'Fluffy'

package io.karatelabs.gatling;

import io.karatelabs.core.Server;

public class MockServer {
    private static Server server;

    public static void start() {
        // Using v2's Server class - dogfooding our own mock server
        server = Server.builder()
            .feature("classpath:mock/mock.feature")
            .build();
        System.setProperty("mock.port", String.valueOf(server.getPort()));
    }

    public static void stop() {
        if (server != null) server.stop();
    }
}

// V1
import com.intuit.karate.gatling.javaapi.*;
import static com.intuit.karate.gatling.javaapi.KarateDsl.*;

// V2
import io.karatelabs.gatling.*;
import static io.karatelabs.gatling.KarateDsl.*;

// No change - still extends Gatling's Simulation
public class MySimulation extends Simulation { ... }

// V1 - works unchanged in V2!
public static void myRpc(Map args, PerfContext ctx) {
    ctx.capturePerfEvent("name", start, end);
}

┌─────────────────────────────────────────────────────────────┐
│  Rust Launcher (karate binary)                              │
│  - Constructs classpath: karate.jar + ext/*.jar             │
│  - Delegates to Java CLI                                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Java CLI (Main.java)                                       │
│  - Uses ServiceLoader to discover CommandProvider           │
│  - Finds GatlingCommandProvider from karate-gatling-bundle  │
│  - Registers 'perf' subcommand                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  PerfCommand (in karate-gatling)                            │
│  - Generates dynamic Gatling simulation from features       │
│  - Runs Gatling with specified load profile                 │
└─────────────────────────────────────────────────────────────┘

// io/karatelabs/cli/CommandProvider.java
package io.karatelabs.cli;

/**
 * SPI for modules to register CLI subcommands.
 * Discovered via ServiceLoader when JARs are on classpath.
 */
public interface CommandProvider {
    String getName();           // e.g., "perf"
    String getDescription();    // e.g., "Run performance tests"
    Object getCommand();        // PicoCLI command instance
}

// In Main.java - discover and register commands
ServiceLoader<CommandProvider> providers = ServiceLoader.load(CommandProvider.class);
for (CommandProvider provider : providers) {
    spec.addSubcommand(provider.getName(), provider.getCommand());
}

@Command(name = "perf", description = "Run performance tests with Gatling")
public class PerfCommand implements Callable<Integer> {

    @Parameters(description = "Feature files or directories")
    List<String> paths;

    @Option(names = {"-u", "--users"}, description = "Number of concurrent users")
    int users = 1;

    @Option(names = {"-d", "--duration"}, description = "Test duration (e.g., 30s, 5m)")
    String duration = "30s";

    @Option(names = {"-r", "--ramp"}, description = "Ramp-up time (e.g., 10s)")
    String rampUp = "0s";

    @Option(names = {"-t", "--tags"}, description = "Tag expression filter")
    String tags;

    @Option(names = {"-o", "--output"}, description = "Output directory")
    String outputDir = "target/gatling";

    @Option(names = {"--format"}, description = "Report format: html (default) or json")
    String format = "html";

    @Override
    public Integer call() {
        // Generate dynamic simulation from features
        // (No --simulation option - features only for simplicity)
        return runDynamicSimulation(paths, users, duration, rampUp, tags, format);
    }
}

// Generates Gatling simulation at runtime from feature files
public class DynamicSimulation extends Simulation {

    public DynamicSimulation() {
        // Read config from system properties (set by PerfCommand)
        String[] paths = System.getProperty("karate.perf.paths").split(",");
        int users = Integer.getInteger("karate.perf.users", 1);
        Duration duration = parseDuration(System.getProperty("karate.perf.duration", "30s"));
        Duration rampUp = parseDuration(System.getProperty("karate.perf.rampUp", "0s"));
        String tags = System.getProperty("karate.perf.tags");

        KarateProtocolBuilder protocol = karateProtocol();

        ScenarioBuilder scenario = scenario("Performance Test")
            .exec(karateFeature(paths).tags(tags));

        setUp(
            scenario.injectOpen(
                rampUsers(users).during(rampUp),
                constantUsersPerSec(users).during(duration)
            )
        ).protocols(protocol.build());
    }
}

# Setup: Download and install the Gatling bundle
# Option A: Manual download
curl -L https://github.com/karatelabs/karate/releases/download/v2.0.0/karate-gatling-bundle.jar \
  -o ~/.karate/ext/karate-gatling-bundle.jar

# Option B: Via karate CLI (future)
karate plugin install gatling

# Run performance tests
karate perf features/api.feature

# With load profile
karate perf --users 10 --duration 60s --ramp 10s features/

# Filter by tags
karate perf --users 5 --duration 30s -t @smoke features/

# JSON output for CI/CD
karate perf --users 10 --duration 30s --format json features/

# If bundle JAR is missing:
$ karate perf features/
Error: Gatling bundle not found.
Run: karate plugin install gatling
Or download manually from: https://github.com/karatelabs/karate/releases

{
  "paths": ["features/"],
  "tags": ["@api"],
  "perf": {
    "users": 10,
    "duration": "60s",
    "rampUp": "10s",
    "output": "target/gatling-reports",
    "format": "html"
  }
}

# Reads perf config from karate-pom.json
# Config discovery matches 'karate test' behavior
karate perf

<!-- In karate-gatling/pom.xml -->
<profile>
    <id>bundle</id>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <configuration>
                    <artifactSet>
                        <includes>
                            <include>io.karatelabs:karate-gatling</include>
                            <include>io.gatling:*</include>
                            <include>io.gatling.highcharts:*</include>
                            <include>org.scala-lang:*</include>
                            <!-- Gatling transitive deps -->
                        </includes>
                        <excludes>
                            <!-- Don't include karate-core - user already has it -->
                            <exclude>io.karatelabs:karate-core</exclude>
                            <exclude>io.karatelabs:karate-js</exclude>
                        </excludes>
                    </artifactSet>
                </configuration>
            </plugin>
        </plugins>
    </build>
</profile>

mvn package -Pbundle -DskipTests
# Output: karate-gatling/target/karate-gatling-bundle.jar

// ~/.karate/karate-cli.json
{
  "jvm_opts": "-Xmx2g"
}

// In PerfCommand
if (users > 100) {
    System.setProperty("karate.jvm.opts.extra", "-Xmx2g");
}

#!/bin/bash
set -e

# Build all modules
echo "Building karate-core fatjar..."
mvn clean package -DskipTests -Pfatjar -pl karate-core -am

echo "Building karate-gatling bundle..."
mvn package -DskipTests -Pbundle -pl karate-gatling

# Setup test environment
TEST_HOME="home/.karate"
mkdir -p "$TEST_HOME/ext"

# Copy JARs
cp karate-core/target/karate.jar "$TEST_HOME/dist/"
cp karate-gatling/target/karate-gatling-bundle.jar "$TEST_HOME/ext/"

echo "Test environment ready at $TEST_HOME"

home/test-project/
├── karate-pom.json
├── karate-config.js
├── features/
│   ├── hello.feature      # Simple GET request
│   └── crud.feature       # CRUD operations
└── mock/
    └── mock.feature       # Mock server

{
  "paths": ["features/"],
  "perf": {
    "users": 5,
    "duration": "20s",
    "rampUp": "5s"
  }
}

// CORRECT: Parallel via Gatling scenarios
ScenarioBuilder cats = scenario("Cats").exec(karateFeature("cats.feature"));
ScenarioBuilder dogs = scenario("Dogs").exec(karateFeature("dogs.feature"));
setUp(
    cats.injectOpen(rampUsers(10).during(10)),
    dogs.injectOpen(rampUsers(10).during(10))
);

@Override
public io.gatling.core.action.builder.ActionBuilder asScala() {
    Function<Session, Session> sessionFunc = toSessionFunction();
    // Create Scala Function1 that wraps Java function
    scala.Function1<io.gatling.core.session.Session,
                    io.gatling.commons.validation.Validation<io.gatling.core.session.Session>> scalaFunc =
            scalaSession -> {
                Session javaSession = new Session(scalaSession);
                Session result = sessionFunc.apply(javaSession);
                // Direct instantiation of Scala Success case class
                return new io.gatling.commons.validation.Success<>(result.asScala());
            };
    return new io.gatling.core.action.builder.SessionHookBuilder(scalaFunc, true);
}

karate/karate-gatling/
├── pom.xml                    # Maven module config
└── src/main/java/io/karatelabs/gatling/
    ├── KarateDsl.java           # Public API entry point
    ├── KarateProtocol.java      # Protocol with URI pattern matching
    ├── KarateProtocolBuilder.java
    ├── KarateUriPattern.java    # URI pattern + pause config
    ├── MethodPause.java         # Method/pause record
    ├── KarateFeatureAction.java # Feature execution via v2 Suite
    ├── KarateFeatureBuilder.java # ActionBuilder implementation
    ├── KarateSetAction.java     # Session variable logic
    └── KarateSetBuilder.java    # ActionBuilder implementation

Gatling Session                    Runner.runFeature(path, arg)
─────────────────                  ────────────────────────────
karateSet("name", ...)       →     arg["__gatling"]["name"]
karateSet("age", ...)        →     arg["__gatling"]["age"]

FeatureRuntime(callArg=arg)  →     ScenarioRuntime.initEngine()
                                   └─ engine.put("__gatling", ...)
                                   └─ engine.put("__karate", ...)

Feature access:
  * def name = __gatling.name    ✅ Works
  * request { name: '#(name)' }  ✅ Works (after fix)

> cats-create-fail.feature:14 response.name == 'WRONG_NAME...'    2 (100%)

Gatling executes scenario
    └─> KarateScalaAction.execute(session)
        └─> Creates PerfHook that reports to statsEngine
        └─> Runner.runFeature(path, arg, perfHook)
            └─> Suite.perfHook(hook)
            └─> FeatureRuntime.call()
                └─> ScenarioRuntime.call()
                    └─> StepExecutor.executeMethod()
                        └─> perfHook.getPerfEventName(request)
                        └─> http().invoke(method)
                        └─> runtime.capturePerfEvent(event)
                    └─> [more steps...]
                    └─> logLastPerfEvent(failureMessage)  // in finally block

---- Requests ------------------------------------------------------------------
> Global                                                   (OK=12     KO=2     )
> POST /cats                                               (OK=5      KO=2     )
> GET /cats/{id}                                           (OK=5      KO=0     )
> custom-rpc                                               (OK=2      KO=0     )
---- Errors --------------------------------------------------------------------
> cats-create-fail.feature:14 response.name == 'WRONG...'  2 (100%)

// In Java helper
public static Object myDatabaseCall(Map args, PerfContext karate) {
    long start = System.currentTimeMillis();
    // ... database operation ...
    long end = System.currentTimeMillis();
    karate.capturePerfEvent("database-query", start, end);
    return result;
}

# In feature file
* def result = Java.type('utils.DbHelper').myDatabaseCall({}, karate)

mvn test -pl karate-gatling           # Smoke test (no reports)
mvn verify -Pcicd -pl karate-gatling  # Full CICD test with HTML reports