Why child threads must not inherit your WebDriver

A test creates Chrome on the JUnit worker, then starts a child task to save a screenshot. Both threads now hold the same driver and send commands to one session. The failure appears later as a missing window or dead session, long after the ownership mistake.

See what the child thread actually inherits

InheritableThreadLocal<T> sounds like it transfers context safely. It does not clone arbitrary objects. When Java creates a child thread, the child receives initial values derived from the parent’s inheritable thread locals. The default childValue returns the parent value itself, so a WebDriver reference points to the same Java object and the same remote browser session in both threads.

A driver is not passive context such as a trace ID or locale. It is a mutable command client with a current window, current frame, cookies, timeouts, alert state, and a session lifecycle. A command from one thread can change the state assumed by the other. Even if the underlying HTTP calls happen to serialize, the test-level sequence is no longer owned by one flow.

Imagine the parent waiting for a checkout button while the child captures page source. The child command can run between the parent’s find and click. Another child might switch windows to inspect a popup while the parent locates an element in the original window. One thread may call quit during teardown while an asynchronous artifact task still asks for a screenshot. None of those interleavings represents a user journey you intended to test.

The mechanism is easy to prove without a browser. This JUnit test sets one mutable object in an InheritableThreadLocal, constructs a child thread, and compares object identity. The assertion would fail if the child received a distinct value.

package example.threads;

import static org.junit.jupiter.api.Assertions.assertSame;

import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.Test;

final class InheritanceMechanismTest {
  @Test
  void child_receives_the_same_reference_by_default() throws InterruptedException {
    InheritableThreadLocal<Object> local = new InheritableThreadLocal<>();
    Object parentValue = new Object();
    AtomicReference<Object> childValue = new AtomicReference<>();
    local.set(parentValue);

    try {
      Thread child = new Thread(() -> childValue.set(local.get()), "artifact-child");
      child.start();
      child.join();

      assertSame(parentValue, childValue.get());
    } finally {
      local.remove();
    }
  }
}

Timing matters. The initial value is captured when the child Thread is created, not when start is called and not whenever a task runs. If the parent changes its local after constructing the thread, the child does not magically follow that change. If the parent removes its value, that removal affects the parent’s entry, not a child entry already created.

Overriding childValue is not a good driver factory. Java invokes it in the parent during child creation. Creating a browser there would still construct the driver on the parent thread and then hand it to the child, which conflicts with the ownership you need. Returning a wrapper around the same driver also preserves the same session. Driver creation belongs inside the thread that will use it.

Virtual or platform thread choices do not turn a shared driver into a thread-safe one. Modern Java builders can disable inheritable-thread-local propagation, which can reduce accidental context transfer. The simpler framework rule remains stronger: do not put WebDriver in inheritable context at all.

Expect thread pools to make the bug intermittent

Executors execute tasks on new threads, existing pooled threads, or sometimes another strategy chosen by the implementation. InheritableThreadLocal copies at thread creation, while executors submit tasks many times. Those lifecycle models do not line up.

A fixed pool often creates workers lazily. Suppose test A sets its driver and submits the pool’s first task. The executor creates worker 1 under test A’s thread, so worker 1 inherits driver A. The task appears to work. Test A quits the driver, but worker 1 remains alive with the inherited reference.

Test B later sets driver B and submits another task. The pool reuses worker 1. No new child thread is created, so no new inheritance occurs. Worker 1 still holds driver A, which is now closed. The task receives an old session and fails. If the pool had been prestarted before either test, the worker might see null instead. That is why the same code can pass alone and fail in a full run.

Increasing the pool size changes which stale value appears. It does not fix the design. One worker may have inherited driver A, another driver C, and a third no driver. Test order, load, and whether the pool had to create a worker determine the symptom. Retries move the task to another worker and make the suite look flaky.

CompletableFuture.runAsync adds uncertainty because the default executor is not specified as “create a child of the submitting test for every task.” A shared worker normally outlives one test. Relying on inherited test context inside that task is wrong even if a local experiment returns the expected value.

Thread-local cleanup does not travel across the pool. Calling remove() in the JUnit parent clears only that thread’s value. A pooled worker holding an inherited entry keeps it for the worker’s lifetime unless code on that worker removes or replaces it. Quitting the browser closes the remote session but leaves the stale Java reference available to a later task.

This behavior produces a recognizable sequence. The first test on a fresh worker passes. A later test fails with a closed-session symptom. Running the later test alone passes because it becomes the first owner. Changing parallelism changes the failures. Logs show a test ID paired with a session ID created by an earlier test.

A plain ThreadLocal can also leak in a pool if teardown forgets remove. The evidence differs. With inheritance, a newly created child thread has the same reference as its parent. With an ordinary local leak, the same long-lived worker carries its own value from one task to a later task. Both need explicit lifecycle ownership, but replacing InheritableThreadLocal alone only fixes the first mechanism.

The near-miss that looks most similar is shared application data. Two tests can own distinct browser sessions and still edit the same account or order. If failures show different session IDs on different threads but one product entity, isolate test data. If one session ID appears on multiple threads or test IDs, investigate driver ownership first.

Make cross-thread access fail at the first command

Selenium’s Java binding provides ThreadGuard. It wraps a driver and checks that calls come from the same thread that constructed it. A cross-thread call raises a WebDriverException with a thread-safety diagnosis instead of sending the command and allowing a later mysterious failure.

Use ThreadGuard during migration and keep it in multithreaded frameworks. Its overhead is small according to Selenium’s documentation. It does not create a driver per thread, schedule tests, or clean up thread locals. Selenium explicitly notes that it does not replace ThreadLocal.

This test proves the guard is active. The child attempts a read-only-looking command, but even getTitle is a session command and violates ownership. The assertion checks the exception class and the documented thread-safety phrase, so an unrelated browser failure cannot satisfy the oracle.

package example.threads;

import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebDriverException;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ThreadGuard;

final class ThreadGuardSmokeTest {
  @Test
  void child_thread_cannot_call_parent_driver() throws InterruptedException {
    WebDriver driver = ThreadGuard.protect(new ChromeDriver());
    AtomicReference<Throwable> observed = new AtomicReference<>();

    try {
      Thread child = new Thread(
          () -> {
            try {
              driver.getTitle();
            } catch (Throwable error) {
              observed.set(error);
            }
          },
          "wrong-driver-thread"
      );
      child.start();
      child.join();

      WebDriverException error =
          assertInstanceOf(WebDriverException.class, observed.get());
      assertTrue(error.getMessage().contains("Thread safety error"));
    } finally {
      driver.quit();
    }
  }
}

Do not catch that exception in a generic retry helper. The test should fail immediately with the creation and caller thread names preserved. Retrying on the same wrong thread repeats the violation. Retrying on another worker may hide it and create a different interleaving.

Add lightweight ownership fields to driver creation and teardown logs: test ID, session ID, thread name, and thread ID. Log the same fields before framework-level browser helpers, not before every low-level command unless you need that volume. One session ID on two thread IDs is direct evidence. A quit record from one thread followed by a command on another explains the dead session.

Thread dumps help when an asynchronous task hangs, but they do not contain the WebDriver session ID automatically. Combine a Java thread dump with your ownership records. Look for the test worker waiting on a future while the future’s worker is blocked in a WebDriver call. That shape often means the test tried to parallelize browser access and then waited for itself through a shared command channel.

Grid traces or driver logs can confirm command overlap for one session. Correlate by session ID and timestamps. Do not infer thread safety from the fact that commands received separate HTTP responses. The higher-level browser state can still be wrong even when transport serialized the requests.

ThreadGuard can expose previously hidden framework behavior. A reporting library, retry callback, or page-object utility may access the driver from its own executor. Treat each exception as an ownership map. Move browser reads back to the test thread, pass captured data outward, or give that component a separate session if its work genuinely needs one.

Give each test thread an explicit driver lifecycle

Use an ordinary ThreadLocal<WebDriver> only as a lookup mechanism for code that cannot receive the driver as a parameter. The safest design passes the driver explicitly through fixtures or test objects. When a local is necessary, open it on the test thread, guard it, use it on that same thread, quit it there, and remove it in finally.

Avoid ThreadLocal.withInitial(ChromeDriver::new) in framework code. A stray call to current() on a reporting or child thread can silently start another browser. Explicit open makes session creation visible and allows the framework to reject duplicate setup.

The following scope owns one protected driver per current thread. It refuses reads before setup and refuses a second open on the same worker. Cleanup removes the local even if quit throws. The JUnit test’s lifecycle and commands remain on the runner’s test thread.

package example.threads;

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ThreadGuard;

final class DriverScope {
  private static final ThreadLocal<WebDriver> CURRENT = new ThreadLocal<>();

  static void open() {
    if (CURRENT.get() != null) {
      throw new IllegalStateException("Driver already exists on " + Thread.currentThread());
    }
    WebDriver driver = ThreadGuard.protect(new ChromeDriver());
    CURRENT.set(driver);
  }

  static WebDriver current() {
    WebDriver driver = CURRENT.get();
    if (driver == null) {
      throw new IllegalStateException("No driver owned by " + Thread.currentThread());
    }
    return driver;
  }

  static void close() {
    WebDriver driver = CURRENT.get();
    try {
      if (driver != null) {
        driver.quit();
      }
    } finally {
      CURRENT.remove();
    }
  }
}

final class AccountPageTest {
  @BeforeEach
  void createSession() {
    DriverScope.open();
  }

  @AfterEach
  void closeSession() {
    DriverScope.close();
  }

  @Test
  void account_heading_is_visible() {
    WebDriver driver = DriverScope.current();
    driver.get(System.getenv("ACCOUNT_PAGE_URL"));
    String heading = driver.findElement(By.cssSelector("main h1")).getText();
    org.junit.jupiter.api.Assertions.assertEquals("Account", heading);
  }
}

Passing the driver as a JUnit parameter or storing it on a per-test instance can be cleaner than a static local. Choose the simplest shape supported by the runner. The invariant matters more than the container: the thread that creates a session owns all commands and teardown for that session.

Parameterized and dynamic tests deserve an ownership check because their display cases may share one Java test instance depending on runner configuration. Do not put the driver in a field merely because each case has a different name in the report. Confirm when setup runs, which thread executes each invocation, and whether teardown follows every invocation. A per-invocation extension store or explicit parameter is often clearer than assuming instance lifecycle implies session lifecycle.

Nested tests can create a similar surprise when a parent class owns setup and a child context adds asynchronous work. The inherited Java object structure does not grant the nested task permission to use the session from another thread. ThreadGuard evaluates the actual constructing and calling threads, not JUnit's logical hierarchy. Keep the same owner rule at every nesting level.

Factory errors also need cleanup discipline. If browser creation succeeds but later setup throws before the driver is stored, a simple close() cannot find that session. Perform configuration that can fail before construction where possible. Once construction begins, hold the local reference in a guarded try and quit it if registration in the scope fails. This closes a leak path that parallel execution can amplify even though no thread inheritance occurred.

If a test intentionally needs two browsers at once, create two drivers and assign clear owners. Running both serially on the test thread may be enough for a chat or multi-user flow. If true concurrent commands are required, create each driver inside its own task and keep all commands for that driver inside the task. Exchange immutable synchronization messages between tasks, not driver references.

The cost is browser capacity. One session per parallel test consumes more memory, Grid slots, ports, and startup time than one shared static driver. That cost buys isolation and debuggability. Reduce concurrency or group scenarios deliberately if capacity is limited; do not recover capacity by sharing a live session across test threads.

Pass captured data to child work, not the driver

Artifact upload is the common excuse for inheritance. The child usually does not need browser control. Capture the screenshot, page URL, or console snapshot on the owner thread, then hand the resulting bytes or strings to an I/O task.

This example captures screenshot bytes on the owner thread and hands them to a pool thread for the file write. The child receives a private byte array that no other code mutates. It never sees WebDriver. The method then blocks on join(), so captureAndWrite returns only after the file exists and the test has a definite artifact outcome before teardown starts.

package example.threads;

import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.CompletableFuture;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;

final class AsyncArtifactWriter {
  static Path captureAndWrite(WebDriver driver, Path target) {
    byte[] screenshot = ((TakesScreenshot) driver).getScreenshotAs(OutputType.BYTES);

    return CompletableFuture.supplyAsync(
        () -> {
          try {
            Path parent = target.toAbsolutePath().getParent();
            if (parent != null) {
              Files.createDirectories(parent);
            }
            return Files.write(target, screenshot);
          } catch (IOException error) {
            throw new UncheckedIOException(error);
          }
        }
    ).join();
  }
}

The blocking join() is deliberate rather than an oversight, and it is worth naming because the method's shape invites the opposite reading. Nothing here hands a pending future back to the caller: the future is created and joined in one expression, so this method is synchronous from the test's point of view and only the file write happens off the test thread. Returning the CompletableFuture instead would let a test overlap the write with other work, but it would move the waiting obligation into teardown. Quit the driver while an unjoined future is still queued and a failed write becomes an unobserved exception on a pool thread, which is exactly the class of missing evidence this pattern exists to prevent. If you do return a future, join or cancel it in the same fixture that owns the driver, before quit. Either shape is defensible; what must not change is the ownership rule, which is that the bytes cross the thread boundary and the driver does not.

The screenshot command can still fail, but it fails on the owner thread where the original browser state and test stack are available. The file write can fail independently without touching the session. If upload is optional, handle the write failure as an artifact failure without replacing the product assertion. If the screenshot is required evidence, fail with both outcomes preserved.

Reporting callbacks should receive a small record such as test ID, session ID, URL origin, screenshot path, and assertion result. Read any browser-derived value before constructing the record. A child that calls DriverScope.current() should receive “no driver,” and that is the desired boundary.

For a network observer or event subscription that must stay active during navigation, keep subscription setup and browser commands on the owner thread unless the Selenium API explicitly manages its own internal callbacks. Do not confuse library-managed protocol event threads with permission for your test code to call the driver from arbitrary callback threads.

If a child task truly owns a browser, create the session inside its Callable, run the whole sub-journey there, and quit in that same callable. Return only an immutable result. This costs another Grid slot and requires synchronization, but it maintains one owner per session.

Never solve the issue by synchronizing on the shared driver. A synchronized block may prevent simultaneous Java calls, but it does not restore a single coherent journey. Thread A can navigate, release the lock, and expect its page; thread B can switch windows before thread A’s next locked command. Serialization at command granularity is not ownership.

Migrate a shared framework without a flag day

Begin with an inventory of every place that can return a driver. Search for static WebDriver fields, ThreadLocal, InheritableThreadLocal, singleton factories, base-test getters, dependency-injection scopes, and calls to getDriver() inside reporters. The number of factory classes is less important than the number of independent ownership paths. Two “temporary” managers can hand different references to the same test.

Add ThreadGuard at the point of creation before changing storage. This makes existing cross-thread access visible while the old framework still runs. Record creation thread, session ID, and test ID. Do not swallow the new exceptions to keep the build green. Route them to a migration report and fix the highest-volume caller first.

Artifact collectors are usually the first callers to move. Capture screenshots, page source, current URL, and browser logs on the test thread while the session is valid. Package only the reviewed results into an immutable failure record. Let background workers compress, write, or upload that record. This often removes most reasons the framework adopted inheritance in the first place.

Next replace InheritableThreadLocal with an explicit ordinary local or per-test field while parallelism is still low. Make current() fail when setup has not opened a driver. A silent null encourages callers to create an emergency global driver or skip cleanup. A clear ownership exception turns hidden lifecycle assumptions into searchable failures.

Move quit and remove into one teardown owner. Shutdown hooks are a poor primary owner because they run much later, may execute on another thread, and cannot tell which test left the session behind. They can report leaked sessions as a last resort, but normal teardown should close the browser immediately after the owning test.

Page objects need review during this step. A page object cached in a static field can retain elements or a driver from an earlier session even after the manager is fixed. Construct page objects per test or per session, and avoid static WebElement fields. If the ownership log is clean but a stale session still appears, inspect objects that captured the driver outside the manager.

Then address intentional concurrency one workflow at a time. A two-user messaging test may need two sessions, but it does not need both sessions in one inheritable local. Give each participant a callable that creates, uses, and quits its own driver. Coordinate with latches or application-visible events. Return immutable results to the test coordinator. This design is more verbose, but its session count and cleanup are reviewable.

Third-party callbacks require a boundary decision. If a reporting SDK calls a supplied screenshot function on its own executor, do not let that function close over the driver. Supply previously captured bytes or configure the SDK to request artifacts synchronously on the test thread if it supports that mode. If neither is possible, disable that feature rather than weakening driver ownership for the whole suite.

After the storage change, run sequentially and look for two kinds of breakage. A “no driver owned” error reveals code that depended on implicit inheritance. A session left open reveals teardown that depended on a parent removing a value it never actually cleared in the child. Fix those before enabling parallel execution, because concurrency only makes their order harder to see.

Raise parallelism in measured steps and compare three counts: active test workers, active browser sessions, and completed teardown records. During steady test execution, sessions should reflect intentional browser-owning work. A session count above the design limit suggests hidden creation. A count that never falls after tests complete suggests missed quit. Distinct counts are operational evidence, not performance measurements, so record the actual run rather than publishing invented targets.

Finally, delete compatibility accessors that return a driver from anywhere. Leaving LegacyDriverManager.getDriver() as an alias to the new scope lets new code preserve the old ambiguity. Pass the driver explicitly in new components, mark the old accessor for removal, and make code review reject new static ownership. The migration is finished when inheritable storage is gone, not when most tests happen to use the replacement.

Turn parallel CI into an ownership check

Run a dedicated ThreadGuard smoke test before the broad suite. Then enable the same parallelism used in production CI and keep ThreadGuard around every created driver. A hidden cross-thread helper fails close to its first command instead of appearing as random browser state.

name: selenium-thread-ownership

on:
  pull_request:
  push:
    branches: [main]

jobs:
  junit-parallel:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "21"
          cache: maven
      - name: Prove ThreadGuard is active
        run: ./mvnw -B -Dtest=ThreadGuardSmokeTest test
      - name: Exercise the suite with fixed parallelism
        run: |
          ./mvnw -B test \
            -Djunit.jupiter.execution.parallel.enabled=true \
            -Djunit.jupiter.execution.parallel.mode.default=concurrent \
            -Djunit.jupiter.execution.parallel.config.strategy=fixed \
            -Djunit.jupiter.execution.parallel.config.fixed.parallelism=4

Start the rollout at parallelism two. Log test, thread, and session ownership. Fix every guard violation and every missing teardown. Then increase toward the Grid capacity. Jumping directly to high concurrency can create application-data collisions and infrastructure saturation that obscure the thread issue.

Disable automatic retries while diagnosing ownership. A retry can land on a different worker with a fresh thread-local state and pass, turning a deterministic architecture defect into a green report. After the framework is clean, retries should still not cover ThreadGuard exceptions.

Watch Grid session counts. One driver per test thread means maximum concurrent sessions should match intentional parallelism, not the total test count. A sudden extra session can reveal withInitial creating browsers on helper threads. Fewer sessions than workers can reveal shared static state.

Test teardown failures as first-class results. If quit fails, still remove the local. If setup fails before setting the local, teardown should do nothing. If a child task is still running, join or cancel it before driver teardown, but structure tasks so they never own the driver reference.

Do not use inheritable driver state for sequential suites either. It may appear harmless until a library introduces an executor or the runner changes scheduling. An ordinary explicit scope is no harder to read and does not transmit a live session accidentally.

The design is complete when one log line can answer who owns a session, ThreadGuard rejects every other caller, teardown runs on the owner, and child work receives data rather than control. At that point, parallel failures can be investigated as product, data, or capacity problems instead of undefined driver sharing.