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.

    • outputConsoleSummary

      public Runner.Builder outputConsoleSummary(boolean enabled)
      Enable/disable console summary output after test execution. When disabled, no summary is printed to console, but results are still available in the returned SuiteResult.

    • dryRun

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

    • 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