Karate cache persistence across scenarios and its impact on test reliability

Direct answer

Karate does not automatically clear the response cache between scenarios. The cache lives for the entire JVM process, so a response stored in one scenario will be returned in later scenarios unless you explicitly reset it.

Confirmed behavior (both 0.9.x and 1.4.x)

• The cache key comprises HTTP method, full URL, request headers (except those listed in cacheHeaders), and request body.
• Enabling the cache with karate.configure('cache', true) makes it global to the test run.
• No automatic invalidation occurs when a scenario ends or when a feature finishes.

Version‑specific reset methods

Karate 0.9.x

There is no programmatic clear() API. The only reliable way to flush the cache is to toggle the setting off and back on:

karate.configure('cache', false);
karate.configure('cache', true);

Place these two lines in a Background section (or a callonce feature) so they execute before every scenario.

Karate 1.4.x (and later 1.x releases)

A direct clear method was added. The exact name may vary by minor release (karate.cache.clear() or karate.getCache().clear()). Use the one that exists in your version:

// Preferred in 1.4.x
karate.cache.clear();

Again, call this in a Background step or a @BeforeScenario hook to isolate each scenario while keeping caching enabled for repeated calls within the same scenario (e.g., Scenario Outline iterations).

Practical steps for per‑scenario isolation

1. Determine your Karate version (mvn dependency:tree or Gradle equivalent).
2. If you are on 0.9.x, add the toggle snippet to Background.
3. If you are on 1.4.x, add karate.cache.clear() (or karate.getCache().clear()) to Background or a @BeforeScenario hook.
4. Optionally exclude volatile headers (e.g., rotating tokens) from the cache key:

   karate.configure('cacheHeaders', ['Authorization']);

5. Run a quick verification: create two scenarios where the first POSTs a resource and the second GETs it. Without the reset the GET returns a stale response; with the reset it reflects the POST.

Verification you can run locally

• Enable debug logging: -Dkarate.log.level=DEBUG – you will see “cache hit” / “cache miss” lines.
• Compare suite execution time with and without the reset step to confirm the performance impact is negligible.

Caveats

• Parallel execution (karate.parallel()) shares the same cache across threads. Resetting in one thread clears it for all threads, which can cause race conditions. For parallel suites consider disabling the cache entirely or accepting the shared‑cache behavior.
• The karate.cache.clear() API may be absent in early 1.x releases (e.g., 1.0.0‑1.2.0). Verify the method name against the CHANGELOG for your exact minor version.
• Cache persistence can mask flaky tests that depend on backend mutations (POST → GET). Always reset when a scenario modifies server state.

Missing diagnostic detail: Are you running scenarios in parallel with karate.parallel()? If yes, the recommendation changes to disabling the cache for the parallel run.