call vs callonce for Auth Setup Reuse in Karate DSL

Answer the exact question first

In a Karate test suite that runs locally, in CI, and with Maven/Gradle forks, callonce caches per JVM/thread, not across Maven forks, so a single token isn’t reused automatically. call re‑executes the login for every scenario, guaranteeing a fresh token but increasing API traffic and risking rate‑limit throttling. The only way to get a single, shared token without duplicating login logic is to combine callonce with a conditional re‑authentication step that runs inside the same JVM (or test thread) and refreshes the token when the TTL expires.

Likely explanation

• Cache scope of callonce: per‑JVM, not across Maven/Gradle forks. Parallel threads inside the same JVM still see separate caches.
• Token expiry: callonce does not automatically refresh; you must add a check that re‑calls the login if the stored token is older than the TTL.
• Pattern to use: callonce in a Background to get the token once per JVM, then a background step that checks karate.get('authToken') and karate.get('authTokenTimestamp') and re‑calls the login if needed.
• Documentation: Karate 1.4+ release notes confirm that callonce is scoped to the running process; no cross‑fork sharing is guaranteed.

Steps for a reliable, non‑duplicated auth flow

1. Create a feature file login.feature that returns the token and the timestamp.

   Feature: Login
   Scenario:
     Given url 'https://api.example.com/auth/login'
     And request { \"user\": \"alice\", \"pass\": \"secret\" }
     When method post
     Then status 200
     And def token = response.token
     And def ts = now
     And set karate.env = { 'authToken': token, 'authTokenTs': ts }
     And match response contains { token: '#string' }
   

2. In your test suite’s Background use callonce to get the token once per JVM.

   Background:
     * def auth = callonce('classpath:login.feature')
     * def authToken = auth.token
     * def authTokenTs = auth.ts
   

3. Add a helper step that refreshes the token only when the TTL (e.g., 15 min) is exceeded.

   * def now = now
   * def elapsed = now - authTokenTs
   * if (elapsed > 15 * 60 * 1000) {
       * def newAuth = call('classpath:login.feature')
       * def authToken = newAuth.token
       * def authTokenTs = now
     }
   

4. Use authToken in all subsequent requests via Authorization: Bearer ${authToken}.

What to check in your environment

• Are you using Maven Surefire with forkCount>1 or Gradle’s maxParallelForks? If so, each fork will have its own callonce cache.
• Is your token TTL short enough that a single JVM could hit the expiry during a long test run? If yes, the conditional refresh step above is essential.
• Do you have rate‑limit constraints on the auth endpoint? Using callonce reduces the number of calls but you still need the refresh guard.

Ask for missing diagnostic detail

Could you confirm whether your test execution uses Maven Surefire/Gradle with multiple forks or simply parallel threads within a single JVM? Knowing the fork/parallel strategy will help fine‑tune the caching strategy.