Cucumber JVM parallel execution: hook thread-affinity guarantee for scenario-scoped @Before/@After

Thread Affinity Guarantee

Cucumber JVM does not provide a formal, documented guarantee that scenario-scoped @Before and @After hooks execute on the same thread as the scenario body during parallel execution. While this behavior is often observed in sequential runs or specific legacy configurations, relying on this affinity for ThreadLocal resource management is unsafe.

Interaction with JUnit 5 and Versioning

The behavior varies based on the version of Cucumber and the JUnit 5 execution mode used:

• Cucumber 6.x vs 7.x: Cucumber 7.x introduced a more decoupled executor pipeline. While 6.x exhibited more consistent thread affinity in certain modes, 7.x is more prone to dispatching hooks via pooled threads, increasing the risk of thread-local mismatch.
• JUnit 5 Execution Modes:
  • SAME_THREAD: Attempts to keep execution within a shared thread, but this does not override Cucumber's internal hook dispatcher logic.
  • CONCURRENT: Explicitly allows parallel execution, where the likelihood of hooks and scenario bodies being assigned to different threads from a pool is significantly higher.

Recommended Resource Management

Because there is no supported mechanism to enforce or query hook thread affinity, you should avoid ThreadLocal for scenario-scoped state. Instead, use the following patterns:

1. Dependency Injection (DI): Use a DI container (like PicoContainer, Spring, or Guice) to inject a scenario-scoped context object into both the hook classes and the step definition classes. The container manages the lifecycle, ensuring the same instance is shared regardless of the thread.
2. Scenario Context Objects: Maintain a state object that is passed or injected, rather than relying on the execution thread's identity to retrieve a resource.

Verification Steps

To verify the actual behavior in your specific environment, implement a thread-logging check:

@Before
public void logBefore() {
    System.out.println("Before Hook Thread: " + Thread.currentThread().getName());
}

@Then("I verify thread affinity")
public void verifyThread() {
    System.out.println("Scenario Step Thread: " + Thread.currentThread().getName());
}

@After
public void logAfter() {
    System.out.println("After Hook Thread: " + Thread.currentThread().getName());
}

Run your tests with --threads 2 (or your JUnit 5 parallel config). If the thread names differ between the hook and the step, your environment does not maintain thread affinity.

Diagnostic Note: To provide a more tailored recommendation, please specify if you are using a custom ExecutorService or a specific DI framework (e.g., Spring) for your glue code.