Does Karate automatically map process.env.KARATE_ENV to karate.env in CI?

Question

In Karate, the karate-config.js file typically uses the karate.env variable to assign a baseUrl based on the target environment (e.g., dev, staging, or prod). While this configuration works reliably during local execution where the environment is explicitly passed, it can lead to failures in production or CI/CD pipelines if the variable is not correctly resolved.

In containerized environments, there is often a discrepancy between system-level environment variables and the variables accessible within the Karate framework. While newer versions of Karate 1.x and 2.x provide access to process.env, it is unclear if karate.env is automatically populated from process.env.KARATE_ENV without explicit mapping logic inside the configuration file.

Which mechanism is recommended to ensure the baseUrl is correctly resolved when the execution context changes from local to CI? Does Karate provide a built-in fallback that maps system environment variables to karate.env, or must this be manually implemented in karate-config.js?

Tasadduq Burney · Answer

Direct answer
No. Karate does not automatically map process.env.KARATE_ENV to karate.env. In CI, karate.env is normally set only when the JVM is launched with the matching system property, for example -Dkarate.env=staging. Exporting KARATE_ENV in the container shell is not sufficient by itself.

What is typically true

karate.env is resolved from a JVM system property, not directly from an OS environment variable.
process.env.KARATE_ENV is accessible only if the Karate version and JavaScript engine expose process.env; older releases may not.
Karate has no built-in fallback that copies an uppercase shell variable into the lowercase karate.env property.

Likely explanation
CI container variables are visible to the operating system process, but the JVM running Karate sees only system properties passed on the launcher command line. The name case also differs: pipelines usually export KARATE_ENV, while Karate reads karate.env.

Steps for this case

Pass -Dkarate.env=staging (or dev/prod) to the test JVM in CI.
Read karate.env in karate-config.js to select baseUrl.

// karate-config.js
function fn() {
  var env = karate.env || 'dev';
  var baseUrl = {
    dev: 'https://dev.example.com',
    staging: 'https://staging.example.com',
    prod: 'https://prod.example.com'
  }[env] || 'https://dev.example.com';
  return { baseUrl: baseUrl };
}

Maven surefire/failsafe: configure systemPropertyVariables with karate.env.
Gradle test task: use systemProperty 'karate.env', 'staging' or pass -Dkarate.env=staging.
Java launcher: set JAVA_OPTS="-Dkarate.env=staging" before running the runner.

Verification
Run a minimal configuration with only KARATE_ENV=staging exported and no -Dkarate.env. Log karate.env and process.env.KARATE_ENV. If karate.env is null or undefined while the shell variable is defined, automatic mapping is not occurring. Then add -Dkarate.env=ci and confirm baseUrl follows the system property.

Assumption: this covers standard JVM-based Karate 1.x/2.x. Non-JVM ports or future releases may behave differently; check the release notes for your exact version before relying on process.env inside karate-config.js.

Does Karate automatically map process.env.KARATE_ENV to karate.env in CI?

1 answer

Direct answer

What is typically true

Likely explanation

Steps for this case

Verification

Your perspective belongs here.

0 question comments