Pure Function karate-config.js vs Limited Side‑Effects: Which Keeps CI Deterministic While Permitting Local Overrides?

The Verdict: Prioritize Pure Functions

To guarantee deterministic execution in a Docker-based CI pipeline, karate-config.js should be treated as a pure function. It should take immutable inputs (environment variables or system properties) and return a configuration object without modifying any external state.

Why Side-Effects Break Parallelism

When karate.parallel is enabled, Karate executes features across multiple threads. If karate-config.js contains side-effects—such as incrementing a global counter, writing to a shared file, or modifying a static Java variable—you introduce race conditions. Because each thread may trigger the config logic independently or share a JVM state, the order of execution becomes non-deterministic, leading to flaky tests that are nearly impossible to debug in CI.

Implementing Local Overrides Without Commits

To allow developers to override values (like baseUrl or credentials) without modifying the committed karate-config.js, use Java System Properties. This keeps the configuration logic in the repo but the sensitive or environment-specific data in the local shell or IDE.

Recommended Pattern:

function fn() {
  var config = {
    baseUrl: 'https://api.staging.example.com',
    apiUser: 'default_user'
  };

  // Override via -Dkarate.env or custom system properties
  var localUrl = java.lang.System.getProperty('local.baseUrl');
  if (localUrl) {
    config.baseUrl = localUrl;
  }

  return config;
}

Developers can then run tests locally using:

mvn test -Dlocal.baseUrl=http://localhost:8080

Verification Steps for Determinism

• Parallel Stress Test: Run the suite with -Dkarate.options="--parallel". If any test fails only during parallel runs but passes in sequential mode, check for shared state in your config.
• Container Isolation: Execute the suite in a clean Docker container. If the tests fail due to missing variables that were present on a developer's machine, your config is relying on implicit local state rather than explicit system properties.
• Override Validation: Run a single feature with and without the -D flag to confirm the logic branches correctly without affecting other concurrent threads.