Package io.karatelabs.core

Class Runner.Builder

java.lang.Object
io.karatelabs.core.Runner.Builder
Enclosing class:
Runner
public static class Runner.Builder extends Object

  • Method Details

    • path

      public Runner.Builder path(String... values)
      Add paths to search for .feature files. Can be directories or individual files.

    • path

      public Runner.Builder path(List<String> values)
      Add paths to search for .feature files.

    • features

      public Runner.Builder features(Feature... values)
      Add Feature objects directly.

    • features

      public Runner.Builder features(Collection<Feature> values)
      Add Feature objects directly.

    • karateEnv

      public Runner.Builder karateEnv(String env)
      Set the karate environment (karate.env).

    • tags

      public Runner.Builder tags(String... tagExpressions)
      Set tag filter expressions. Multiple arguments are AND-ed together (each must match). Commas within a single argument mean OR (any must match).

      Examples:

      • tags("@smoke") — run scenarios tagged @smoke
      • tags("~@slow") — exclude scenarios tagged @slow
      • tags("@smoke,@fast") — run scenarios tagged @smoke OR @fast
      • tags("~@slow", "~@ignore") — exclude @slow AND @ignore
      • tags("@smoke", "~@slow") — must have @smoke AND must not have @slow

    • scenarioName

      public Runner.Builder scenarioName(String name)
      Filter by scenario name (exact match, whitespace-trimmed on both sides). When set, only scenarios whose name equals this value will run, and tag filters (@ignore, @env) are bypassed for matches — the same semantics as the file.feature:LINE line filter.

    • configDir

      public Runner.Builder configDir(String dir)
      Set the directory containing karate-config.js.

    • systemProperty

      public Runner.Builder systemProperty(String key, String value)
      Set a system property that will be available via karate.properties in scripts. Multiple properties can be set by calling this method multiple times.

    • logLevel

      public Runner.Builder logLevel(LogLevel level)
      Set the minimum log level for report capture. Logs below this level will be filtered from reports.

    • logLevel

      public Runner.Builder logLevel(String level)
      Set the minimum log level by name (case-insensitive). Valid values: trace, debug, info, warn, error

    • consoleLevel

      public Runner.Builder consoleLevel(String level)
      Set the SLF4J/console log level for the "karate" logger. Distinct from logLevel(String) which is the report-buffer threshold. Valid values: trace, debug, info, warn, error. If null/unset the level is inherited from logback.xml (typically INFO).

    • outputDir

      public Runner.Builder outputDir(String dir)
      Set the output directory for reports.

    • outputDir

      public Runner.Builder outputDir(Path dir)
      Set the output directory for reports.

    • workingDir

      public Runner.Builder workingDir(String dir)
      Set the working directory for relative path resolution. This affects how feature file paths are displayed in reports.

    • workingDir

      public Runner.Builder workingDir(Path dir)
      Set the working directory for relative path resolution. This affects how feature file paths are displayed in reports.

    • outputHtmlReport

      public Runner.Builder outputHtmlReport(boolean enabled)
      Enable/disable HTML report generation.

    • outputJsonLines

      public Runner.Builder outputJsonLines(boolean enabled)
      Enable/disable JSON Lines streaming output. Streams lifecycle events to karate-json/karate-events.jsonl as they fire, with one record per line and a per-line flush so external tools (e.g. IDE test runners) can tail the file in real time.

    • outputJunitXml

      public Runner.Builder outputJunitXml(boolean enabled)
      Enable/disable JUnit XML report generation.

    • outputCucumberJson

      public Runner.Builder outputCucumberJson(boolean enabled)
      Enable/disable Cucumber JSON report generation.

    • backupOutputDir

      public Runner.Builder backupOutputDir(boolean enabled)
      Enable/disable backup of existing output directory. When enabled, the existing output directory is renamed with a timestamp suffix (e.g., karate-reports_2025-01-15_143022) before new reports are written.

    • retainCallResults

      public Runner.Builder retainCallResults(boolean enabled)
      Keep the nested karate.call() result trees reachable after the run.

      Off by default. Every call attaches the callee's whole result tree to the calling step, and the suite holds every feature until it ends, so retaining them makes memory scale with total scenarios times calls per scenario — enough to exhaust the heap on a long suite. They are released once each feature has completed and every listener has consumed it.

      Reports are unaffected either way: the HTML report extracts its page model, nested step detail included, while the result is still whole. Turn this on only to walk into a called feature's steps from a SuiteResult programmatically after the run.

    • retainStepLogs

      public Runner.Builder retainStepLogs(boolean enabled)
      Keep each step's captured log text and embeds reachable after the run.

      Off by default. The log holds the rendered HTTP request and response for every step and an embed holds raw bytes — a screenshot, a document — and the suite holds every feature until it ends, so retaining them makes memory scale with total steps times payload size. They are released once each feature has completed and every listener has consumed it.

      Reports are unaffected either way: HTML, Cucumber JSON, JUnit XML and the JSONL stream all serialize the feature while it is still whole. Turn this on only to read StepResult.getLog() or getEmbeds() from a SuiteResult programmatically after the run.

      Ignored under karate-gatling, where nothing is retained past one execution anyway and logReplay reads the log after the feature returns.

    • outputConsoleSummary

      public Runner.Builder outputConsoleSummary(boolean enabled)

    • captureStepLogs

      public Runner.Builder captureStepLogs(boolean enabled)
      Collect each step's Karate output — HTTP request / response blocks, print — into StepResult.log, which is what the HTML report, the JSONL / JUnit / Cucumber writers and karate-gatling's log replay all read.

      Unset by default, which means on for a normal run and off under Gatling: that lane writes no HTML report, so the text would be built — the response body re-parsed and pretty-printed for every request — only to be retained and discarded. Set it explicitly to override in either direction.

      This is capture, not logging: print and karate.log() reach SLF4J either way, at whatever level the Logback config allows.

    • dryRun

      public Runner.Builder dryRun(boolean enabled)
      Enable dry-run mode (parse but don't execute).

    • global

      public Runner.Builder global(String name, Object instance)
      Bind a JS global (an ext-global-shaped object, typically a SimpleObject) into every scenario of this run — the run-free / programmatic equivalent of an Ext calling Suite.registerGlobal(String, Object) in onBoot. Lets an embedder stand up a one-off Runner.features(...) run that binds a global without authoring an ext or a karate-boot.js — e.g. a synthesizer whose single synthetic step replays recorded events through
      invalid reference 
      LogContext#step
      . Seeded before karate-config.js; a reserved-name collision fails the suite loud at construction.

    • listener

      public Runner.Builder listener(RunListener listener)
      Add a run event listener.

    • listeners

      public Runner.Builder listeners(Collection<RunListener> values)
      Add multiple run event listeners.

    • listenerFactory

      public Runner.Builder listenerFactory(RunListenerFactory factory)
      Add a run listener factory for per-thread listeners. The factory's create() method is called once per execution thread.

    • listenerFactory

      public Runner.Builder listenerFactory(String className)
      Add a run listener factory by class name (supports no-arg constructor). Used for CLI --listener-factory option.
      Parameters:
      className - fully qualified class name

    • resultListener

      public Runner.Builder resultListener(ResultListener listener)
      Add a result listener for streaming test results.

    • resultListeners

      public Runner.Builder resultListeners(Collection<ResultListener> values)
      Add multiple result listeners.

    • driverProvider

      public Runner.Builder driverProvider(DriverProvider provider)
      Set a driver provider for managing browser driver lifecycle.

      When set, the provider is used to acquire/release drivers for scenarios instead of creating a new driver per scenario.

      Example: 

       Runner.path("features/")
     .driverProvider(new PooledDriverProvider())
     .parallel(4);  // Pool size auto-detected

    • pool

      public Runner.Builder pool()
      Enable browser driver pooling for parallel UI tests. Creates a PooledDriverProvider that reuses browser instances across scenarios.

      Pool size is auto-detected from the parallel thread count.

      Example: 

       Runner.path("features/")
     .pool()       // Enable pooling
     .parallel(4); // Pool size = 4

    • pool

      public Runner.Builder pool(int size)
      Enable browser driver pooling with explicit pool size. Creates a PooledDriverProvider that reuses browser instances across scenarios.

      Example: 

       Runner.path("features/")
     .pool(2)      // Pool of 2 browsers
     .parallel(4); // 4 threads share 2 browsers
      Parameters:
      size - number of browser instances to pool

    • httpClientFactory

      public Runner.Builder httpClientFactory(HttpClientFactory factory)
      Set the HTTP client factory for custom/mock HTTP clients. When set, this factory is used instead of the default HTTP client.

    • skipTagFiltering

      public Runner.Builder skipTagFiltering(boolean skip)
      Skip tag filtering (@env, @ignore) so all scenarios run regardless of tags. Use this for unit tests that need to run scenarios with any tags.

    • debugSupport

      public <T> Runner.Builder debugSupport(io.karatelabs.js.RunInterceptor<T> interceptor, io.karatelabs.js.DebugPointFactory<T> factory)
      Set debug support with interceptor and factory. Used for IDE debugging integration.

    • callSingleCache

      public Runner.Builder callSingleCache(Map<String,Object> cache, ReentrantLock lock)
      Inject a pre-allocated callSingle cache (and its companion lock). When set, Suites built from this builder reuse the cache instead of creating their own — so the cache outlives any single Suite. Used by karate-gatling to share callSingle results across the virtual users of one simulation.

      Pass a matching lock so all Suites sharing the cache also share its write lock; otherwise concurrent virtual users can race.

    • callOnceCacheStore

      public Runner.Builder callOnceCacheStore(Map<String,Map<String,Object>> cacheStore, Map<String,ReentrantLock> lockStore)
      Inject pre-allocated callOnce/setupOnce stores (keyed by feature URI). Same lifetime semantics as callSingleCache — used by karate-gatling so a feature's callOnce/setupOnce runs once per simulation, not once per virtual user.

    • setupOnceCacheStore

      public Runner.Builder setupOnceCacheStore(Map<String,Map<String,Object>> cacheStore)

    • getResolvedFeatures

      public List<Feature> getResolvedFeatures()
      Provisional API — may change or be removed without notice. Exposed to support advanced runtime scenario discovery (e.g. sequential retry against an expensive grid session) until in-suite orchestration hooks land.

      Note: callers that filter the returned Features themselves (e.g. by walking sections and evaluating a TagSelector) bypass FeatureRuntime.shouldSelect and will miss @ignore, @setup, suite-level line/name filters, and @envnot. Mirror that logic if you need parity with what would actually run.

    • parallel

      public SuiteResult parallel(int threadCount)
      Execute the tests with the specified thread count. This is the terminal operation that runs the tests.
      Parameters:
      threadCount - number of threads (1 for sequential)
      Returns:
      the test results

    • buildSuite

      public Suite buildSuite()
      Build the Suite without running it. Useful for advanced scenarios where you need to configure the Suite further or run it manually.

    • toString

      public String toString()
      Overrides:
      toString in class Object