Karate-config.js silent fallback when karate.env is missing

Trade-offs of a fail-fast guard

Karate does not require karate.env; when the system property is absent, karate-config.js receives undefined and typically falls back to a default (often dev or local). This permissive behavior causes silent mis-execution in CI if the property is forgotten—tests pass against the wrong host.

Fail-fast advantages: immediate detection of missing configuration, prevents false-positive integration results, forces explicit environment selection in pipelines.

Fail-fast disadvantages: breaks local runs where developers rely on the default, adds friction for quick debugging against remote endpoints, may require CI-specific logic to avoid false positives when the build tool already injects a default.

Guard implementation that preserves local workflows

Add a conditional throw inside karate-config.js that only activates in CI environments:

function() {
  var env = karate.env; // undefined if -Dkarate.env not supplied
  var inCi = !! (java.lang.System.getenv('CI') 
                || java.lang.System.getenv('GITHUB_ACTIONS')
                || java.lang.System.getenv('GITLAB_CI')
                || java.lang.System.getenv('BUILDKITE')
                || java.lang.System.getenv('TEAMCITY_VERSION'));
  if (!env && inCi) {
    throw new java.lang.Error('karate.env system property is required in CI. Set -Dkarate.env=staging|prod|etc.');
  }
  // permissive default for local runs
  var resolved = env || 'local';
  karate.log('Resolved karate.env:', resolved);
  return { env: resolved, baseUrl: 'https://' + resolved + '.example.com' };
}

This uses Java interop to read process environment variables (available in Karate's Nashorn/GraalVM JS engine). The guard triggers only when a known CI variable is present, leaving local IDE/Gradle/Maven runs unaffected.

Recommended fallback strategy

1. CI-only fail-fast as shown above—catches missing property in pipelines without disturbing developers.
2. Explicit local profile: document that developers must run with -Dkarate.env=local (or configure IDE run configurations) so the resolved environment is always visible in logs.
3. Startup log line: always emit the resolved environment (karate.log('Resolved karate.env:', resolved)) so mis-configuration is obvious in any execution log.
4. Validate in CI script: add a pre-test check that karate.env is set in the pipeline YAML (e.g., if [ -z "$KARATE_ENV" ]; then exit 1; fi) for defense in depth.

Verification steps

1. Create a minimal karate-config.js with the guard and a karate.log of karate.env.
2. Run locally without -Dkarate.env—expect local default and no error.
3. Run locally with -Dkarate.env=staging—expect staging logged.
4. Execute in a CI job (GitHub Actions, GitLab CI, etc.) without setting the property—expect the build to fail with the explicit error message.
5. Confirm the same CI job passes when karate.env is provided via pipeline variable or -Dkarate.env in the test command.

One diagnostic detail that would change the recommendation: does your build tool (Maven/Gradle) already inject a default karate.env in CI? If yes, the CI-only guard may never trigger; verify the actual value received in the script under CI before finalizing.