Skip to main content

ADVANCED

Extensions & karate-boot.js

Karate v2 has a suite-lifetime extension mechanism for integrations that participate in the full run — from SUITE_ENTER through SUITE_EXIT. Extensions are turned on declaratively from a karate-boot.js file at your working-directory root: no file means no extensions and zero overhead.

The first OSS extension to ship on this surface is Image Comparison.

Experimental

This API is experimental and may change. Most users only ever use an extension (e.g. add karate-image and configure it); authoring one is an advanced topic.

Using an extension​

Drop a karate-boot.js in your working directory and activate an extension by name with boot.ext(...). It runs once, before any feature, and returns the extension object so you can set its configuration:

// karate-boot.js — runs once per suite, before SUITE_ENTER
const image = boot.ext('image');
image.baselineDir = 'baselines';
image.threshold = 0.5;

An activated extension also puts its object into every scenario's scope (so image.compare(...) is available in your features). The boot object provides:

MemberDescription
boot.ext(name)Activate + configure an extension by name; returns the instance
boot.envThe current Karate environment (from karate.env)
boot.sysenv(name, [default])Read an OS environment variable
boot.sysprop(name, [default])Read a JVM system property
boot.read(path)Read a file relative to the working directory
boot.log(msg)Log a message with the [boot] prefix

Authoring an extension​

An extension is a Java class implementing the Ext interface, resolved by name convention (boot.ext('image') → io.karatelabs.ext.image.ImageExt). It can contribute a JS-scope object, observe every event via RunListener, and add report assets / UI. The full authoring contract — globals, report assets, embeds, the report render hook, and a step-by-step checklist — lives in EXT.md on GitHub, with karate-image as the worked example.

Relationship to karate.channel()​

Extensions coexist with karate.channel():

  • karate.channel() — per-call, request/response style integrations (gRPC, Kafka, WebSocket)
  • Extensions — suite-lifetime observers/integrations configured at boot

Both can be used together: extensions are for cross-cutting concerns spanning the whole suite; channels are for per-scenario protocol interactions.

See Also​

On This Page