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.

  • 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.

      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.

    • 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)