Package io.karatelabs.core

Interface Ext

All Superinterfaces:
RunListener
public interface Ext extends RunListener
Karate ext SPI — singletons-per-Suite that observe the run via RunListener.

Exts are loaded from a karate-boot.js file at the workdir root, once per Suite, by BootLoader. Activation example:

 // karate-boot.js
 const openapi = boot.ext('openapi');
 openapi.path = 'api/openapi.yaml';
 openapi.excludes = ['/health/**'];

The boot.ext('foo') call resolves foo to io.karatelabs.ext.foo.FooExt by name convention, instantiates the class, invokes onBoot(Suite) immediately, registers the ext as a listener on the Suite, and returns the instance so the boot script can configure it.

Exts coexist with the per-call channel pattern (karate.channel(...)) — channels are per-call; exts are singleton-per-Suite. See AGENT_KARATE.md K43 for the design rationale.

Lifecycle:

  1. karate-boot.js evaluates → each boot.ext('name') call constructs the ext and fires onBoot(Suite).
  2. Suite registers the ext as a RunListener; it sees every event.
  3. SUITE_ENTER.data.exts[] carries each ext's getManifest().
  4. After SUITE_EXIT, onShutdown() fires.

Failure mode: exceptions during onBoot fail the Suite loudly. Exceptions inside onEvent(io.karatelabs.core.RunEvent) are logged WARN and dropped — the run continues, that one signal is lost.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Map<String,Object>
    getManifest()
    Manifest entry recorded under SUITE_ENTER.data.exts[] so receivers know which exts were active for this run and with what config.
    default void
    onBoot(Suite suite)
    Called once per Suite when the boot.ext('name') expression evaluates in karate-boot.js.
    default boolean
    onEvent(RunEvent event)
    Default RunListener.onEvent(RunEvent) returns true (continue execution).
    default void
    onShutdown()
    Called after SUITE_EXIT fires.
    default boolean
    requiresJsonlEvents()
    An ext whose output is computed from the karate-events.jsonl stream (e.g. a coverage analyzer) returns true so the Suite auto-enables the JSONL event writer — exactly as if -f karate:jsonl / Runner...outputJsonLines(true) had been passed.

  • Method Details

    • onBoot

      default void onBoot(Suite suite)
      Called once per Suite when the boot.ext('name') expression evaluates in karate-boot.js. Throws from here fail the Suite.

      The Suite is still under construction here — boot runs before config discovery and feature resolution, because boot.classpath(dir) is what those honour. Suite.getRoot() is final and is the anchor an ext must resolve its configured paths against; Suite.getWorkingDir(), Suite.features and the config*Resource fields are not yet assigned. Resolve lazily (at first use, or from onEvent) if you need anything beyond the root.

      Default no-op so exts that only need to observe events (onEvent) can stay terse.

    • onShutdown

      default void onShutdown()
      Called after SUITE_EXIT fires. Use to release file handles, flush buffers, etc. Exceptions are logged and dropped.

    • requiresJsonlEvents

      default boolean requiresJsonlEvents()
      An ext whose output is computed from the karate-events.jsonl stream (e.g. a coverage analyzer) returns true so the Suite auto-enables the JSONL event writer — exactly as if -f karate:jsonl / Runner...outputJsonLines(true) had been passed. Without this, a run that boots such an ext would pass green yet silently produce none of the ext's output. Evaluated once, after karate-boot.js evaluation and before the writer is wired.

    • getManifest

      default Map<String,Object> getManifest()
      Manifest entry recorded under SUITE_ENTER.data.exts[] so receivers know which exts were active for this run and with what config. Returned map is serialised to JSON verbatim — keep keys primitive (String, Number, Boolean, nested maps).

      Standard entries: name, version. Ext-specific summary fields are flat under the top-level map. Default returns an empty map; exts with meaningful manifests should override.

    • onEvent

      default boolean onEvent(RunEvent event)
      Default RunListener.onEvent(RunEvent) returns true (continue execution). Exts that only need lifecycle hooks (onBoot / onShutdown / manifest) without observing events can rely on this and skip the override.
      Specified by:
      onEvent in interface RunListener
      Parameters:
      event - the event containing type, runtime objects, and results
      Returns:
      true to continue execution, false to skip (only meaningful for *_ENTER events)