Package io.karatelabs.core

Class Suite

java.lang.Object
io.karatelabs.core.Suite
public class Suite extends Object
Immutable suite configuration and execution engine.

Suite instances can only be created via Runner.Builder. All configuration fields are public final for inspection.

Example usage: 

 SuiteResult result = Runner.path("features/")
     .tags("@smoke")
     .parallel(4);

  • Field Details

    • KARATE_JSON_SUBFOLDER

      public static final String KARATE_JSON_SUBFOLDER
      Subfolder for JSON output (JSONL events, etc.)
      See Also:

    • features

      public final List<Feature> features

    • env

      public final String env

    • tagSelector

      public final String tagSelector

    • threadCount

      public final int threadCount

    • parallel

      public final boolean parallel

    • dryRun

      public final boolean dryRun

    • configPath

      public final String configPath

    • outputDir

      public final Path outputDir

    • workingDir

      public final Path workingDir

    • root

      public final Path root
      THE project root — see getRoot(). Computed before config discovery.

    • classpathRoot

      public final Path classpathRoot
      The classpath:-miss fallback dir — see getClasspathRoot(). Never null.

    • outputHtmlReport

      public final boolean outputHtmlReport

    • outputJsonLines

      public final boolean outputJsonLines

    • outputJunitXml

      public final boolean outputJunitXml

    • outputCucumberJson

      public final boolean outputCucumberJson

    • backupReportDir

      public final boolean backupReportDir

    • outputConsoleSummary

      public final boolean outputConsoleSummary

    • retainCallResults

      public final boolean retainCallResults

    • retainStepLogs

      public final boolean retainStepLogs

    • systemProperties

      public final Map<String,String> systemProperties

    • listeners

      public final List<RunListener> listeners

    • listenerFactories

      public final List<RunListenerFactory> listenerFactories

    • driverProvider

      public final DriverProvider driverProvider

    • httpClientFactory

      public final HttpClientFactory httpClientFactory

    • skipTagFiltering

      public final boolean skipTagFiltering

    • lineFilters

      public final Map<String,Set<Integer>> lineFilters

    • scenarioName

      public final String scenarioName

    • debugInterceptor

      public final io.karatelabs.js.RunInterceptor<?> debugInterceptor

    • debugPointFactory

      public final io.karatelabs.js.DebugPointFactory<?> debugPointFactory

    • baseResource

      public final io.karatelabs.common.Resource baseResource

    • configResource

      public final io.karatelabs.common.Resource configResource

    • configEnvResource

      public final io.karatelabs.common.Resource configEnvResource

  • Method Details

    • run

      public SuiteResult run()

    • registerExtListener

      public void registerExtListener(Ext ext)
      Register an Ext as a RunListener on this Suite. Called from BootBinding.ext(String) during karate-boot.js evaluation, before SUITE_ENTER fires. Ext will see every event from SUITE_ENTER onward.

    • getWorkingDir

      public Path getWorkingDir()
      The launch/output anchor. Equals getRoot() when the project declares boot.classpath.

    • getRoot

      public Path getRoot()
      THE root — the single anchor every path reference resolves against: a leading / means this directory, a bare ref is relative to it, and a classpath: miss falls back under getClasspathRoot(). Resolution is fully deterministic — no filesystem probing — so one spelling lands on the same file on every machine.

      Assigned before config discovery and before karate-boot.js evaluates, from the explicit configDir (a *.js value contributes its parent), else a classloader probe of the config path (a Java project's target/test-classes), else the explicit workingDir, else the process CWD. It is deliberately NOT derived from where the config file was found, so a mapped config dir cannot silently move the root.

    • getClasspathRoot

      public Path getClasspathRoot()
      The directory a classpath: reference retries against when the classloader misses, declared by boot.classpath(dir) in karate-boot.js. Equals getRoot() when nothing is declared — so a bare-folder project needs no declaration at all. Never null.

    • getConfigDir

      public Path getConfigDir()
      The directory of the resolved karate-config.js. Retained for reporting/diagnostics only — getRoot() is the anchor for path references; this value can differ from it (a project that maps its resources keeps its config under the mapped dir).

    • getBootBinding

      public BootBinding getBootBinding()
      Returns the karate-boot.js BootBinding populated during construction, or null when no boot file is present in the workdir. Surfaced so SuiteRunEvent.toJson() can attach exts[] manifests to SUITE_ENTER — receivers read this to know which exts were active and which embed names to expect.

    • registerChannelFactory

      public void registerChannelFactory(String type, ChannelFactory factory)
      Register a ChannelFactory for an async channel type (e.g. "grpc", "kafka"). Called by an ext from Ext.onBoot(Suite) — typically right after its license gate passes — so karate.channel('grpc') resolves to the ext-supplied factory instead of the io.karatelabs.ext.<type>.<Type>ChannelFactory name-convention fallback. The factory instance is suite-scoped, giving the ext a home for suite/JVM-wide init (shared channels, pools). Last registration for a type wins.

    • getChannelFactory

      public ChannelFactory getChannelFactory(String type)
      Ext-registered ChannelFactory for the given type, or null if none — in which case karate.channel() falls back to the built-in name->FQCN map.

    • registerGlobal

      public void registerGlobal(String name, Object instance)
      Register an ext global under name, seeded into every scenario's JS scope before karate-config.js evaluates. Called by an Ext from Ext.onBoot(Suite); the instance is typically a SimpleObject so members cross into JS natively (no reflection). Throws — and so fails the Suite at boot — when the name is blank or collides with a built-in global (karate, read, match, driver).

    • registerGlobal

      public void registerGlobal(String name, ExtGlobalFactory factory)
      Register a per-scenario ext global: the ExtGlobalFactory is invoked once per scenario at seed time to mint a fresh instance bound with the scenario's KarateJsContext. Prefer this over the singleton registerGlobal(String, Object) when the global carries per-scenario mutable state or needs runtime / path access — see ExtGlobalFactory.

    • getGlobal

      public Object getGlobal(String name)
      The ext global registered under name, or null if none.

    • getGlobals

      public Map<String,Object> getGlobals()
      Immutable view of all ext globals, in registration order.

    • registerReportAssets

      public void registerReportAssets(ReportAssets assets, ClassLoader classLoader)
      Register an ext's report-asset contribution. Called by an Ext from Ext.onBoot(Suite) with a fluent ReportAssets spec, e.g. suite.registerReportAssets(ReportAssets.named("image").js("static/ext.js"), getClass().getClassLoader()). Validates the spec against the classloader (referenced resources must exist); any failure throws and so fails the Suite loud at boot (see EXT.md § Report assets).

    • getReportAssets

      public Map<String,ReportAssets> getReportAssets()
      Immutable view of all registered ext report-asset specs, in registration order.

    • addSummaryCard

      public void addSummaryCard(Map<String,Object> card)
      Contribute one KPI summary card to the summary-page hero (a key/value tile, e.g. {label:'Coverage', value:'53%', sub:'8/15 endpoints'}). Called by an Ext from Ext.onShutdown() (the values are post-run), which the run loop invokes before the report listener writes the summary, so cards are inlined into the page. Optional keys the renderer understands: sub (a second line), href (click-through), and status (ok/warn/fail, for accent colour).

    • getSummaryCards

      public List<Map<String,Object>> getSummaryCards()
      The contributed KPI summary cards, in registration order (empty when no ext added any).

    • fireEvent

      public boolean fireEvent(RunEvent event)

    • getOutputDir

      public String getOutputDir()

    • getCallSingleCache

      public Map<String,Object> getCallSingleCache()

    • getCallSingleLock

      public ReentrantLock getCallSingleLock()

    • getCallOnceCache

      public Map<String,Object> getCallOnceCache(String featureKey)
      Get the callOnce cache for the given feature key (its resource URI). The cache is created on first access and reused across all FeatureRuntimes for the same feature within this Suite — and across Suites when the underlying store was injected via Runner.Builder.

    • getCallOnceLock

      public ReentrantLock getCallOnceLock(String featureKey)

    • getSetupOnceCache

      public Map<String,Object> getSetupOnceCache(String featureKey)

    • getLockManager

      public ScenarioLockManager getLockManager()

    • getScenarioExecutor

      public ExecutorService getScenarioExecutor()

    • getScenarioSemaphore

      public Semaphore getScenarioSemaphore()

    • acquireLane

      public void acquireLane()

    • releaseLane

      public void releaseLane()

    • getCurrentLaneName

      public String getCurrentLaneName()

    • abort

      public void abort()

    • isAborted

      public boolean isAborted()

    • getResult

      public SuiteResult getResult()

    • canReleaseCallResultsAtScenarioEnd

      public boolean canReleaseCallResultsAtScenarioEnd()
      Whether a scenario's nested call trees can be dropped the moment the scenario ends, rather than waiting for its feature to finish.

      This is what bounds memory for the shape that actually hurts: a single feature holding thousands of scenarios — a Scenario Outline — where feature end is the end of the whole run and releasing there frees nothing.

      Only safe when nothing will want the detail later. The report writers build their output per feature, so they need every scenario's nesting still attached when the feature completes; a suite with any result listener therefore holds on until then. With no listeners — load runs, karate-gatling, reporting explicitly disabled — nothing ever reads it and it can go immediately. Custom listeners count as consumers, since there is no way to know what a caller's listener reads.

    • getResultListeners

      public List<ResultListener> getResultListeners()

    • getSystemProperties

      public Map<String,String> getSystemProperties()
      Get system properties for karate.properties.

      A live view, not a copy: reading one key does not walk the JVM's whole property table, which karate.sysprop('x') and every karate.properties['x'] used to do — a fresh HashMap of every system property, per access. Iteration still materializes.

    • getSystemProperty

      public String getSystemProperty(String key)
      One property, without building the map — what karate.sysprop(name) wants. Builder-supplied properties win over the JVM's, matching the merge order of the view.

    • getDriverProvider

      public DriverProvider getDriverProvider()

    • getPerfHook

      public PerfHook getPerfHook()

    • getHttpClientFactory

      public HttpClientFactory getHttpClientFactory()

    • isPerfMode

      public boolean isPerfMode()

    • isCaptureStepLogs

      public boolean isCaptureStepLogs()
      Whether each step's Karate output is collected into StepResult.log — see Runner.Builder.captureStepLogs(boolean).

      Unset, this answers "yes, unless this is a Gatling run": under Gatling there is no HTML report and nothing else reads the buffer, so building the text (which re-parses and pretty-prints every response body) would be pure waste. Resolved lazily rather than in the constructor because setPerfHook(io.karatelabs.core.PerfHook) runs after the Suite is built.

    • isSkipTagFiltering

      public boolean isSkipTagFiltering()