Browser mode tester can hang forever after reconnect if waitForConnection() is awaiting the first socket attempt

[jkieboom]

Describe the bug

In browser mode, the tester can hang forever if the first tester websocket stays in CONNECTING long enough for the client to start awaiting waitForConnection(), then drops before open, and Vitest reconnects. This problem was triggered when running vitest through browserstack. I'm not sure what exactly triggers it, but something around the way local tunnel networking is setup causes it to consistently end up in a wrong state.

What I expect is for waitForConnection() to follow the current websocket attempt across reconnect, or at least not leave existing waiters stuck on the first failed attempt.

What actually happens is that the tester iframe loads, the browser reconnects, but the original waiter can stay attached to the first socket's unresolved openPromise, so the tester never processes prepare or execute and the run stalls indefinitely.

From inspecting Vitest 4.1.4, this appears to come from @vitest/browser storing a per-attempt openPromise inside registerWS(). When reconnect replaces client.ws, it also replaces openPromise, but callers that were already awaiting the old promise are still stuck on the first socket attempt. In the built tester bundle, message handling starts by awaiting client.waitForConnection(), which is why the iframe can reconnect and still never start running tests.

Reproduction

Reproduction repository: https://github.com/jkieboom/vitest-waitforconnection-repro

The reproduction is a minimal standalone Vitest browser-mode project. It uses a local reverse proxy in front of the Vitest server. In the broken case, that proxy forwards everything normally except the first tester __vitest_browser_api__ websocket upgrade: it holds that socket in CONNECTING for 1500 ms and then drops it before the handshake completes. The browser then reconnects naturally, but the original waitForConnection() waiter remains stuck.

Steps:

npm install
npx playwright install chromium
node ./run-repro.mjs

Expected output:

• the control case exits successfully
• the broken case should also eventually proceed after reconnect

Actual output:

• the control case exits successfully
• the broken case logs that the first tester websocket was dropped and then hangs until the harness timeout kills it

I reproduced this consistently across repeated local runs.

System Info

System:
  OS: macOS 26.4.1
  CPU: (12) arm64 Apple M2 Pro
  Memory: 130.44 MB / 32.00 GB
  Shell: 5.9 - /bin/zsh
Binaries:
  Node: 24.12.0 - /Users/jess7953/.nvm/versions/node/v24.12.0/bin/node
  npm: 11.6.2 - /Users/jess7953/.nvm/versions/node/v24.12.0/bin/npm
  pnpm: 10.33.0 - /Users/jess7953/.nvm/versions/node/v24.12.0/bin/pnpm
Browsers:
  Chrome: 147.0.7727.56
  Chrome Canary: 149.0.7793.0
  Edge: 147.0.3912.60
  Firefox: 149.0.2
  Safari: 26.4
  Safari Technology Preview: 26.0
npmPackages:
  @vitest/browser: 4.1.4 => 4.1.4
  @vitest/browser-playwright: 4.1.4 => 4.1.4
  vitest: 4.1.4 => 4.1.4

Used Package Manager

npm

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[dokson]

@jkieboom I've opened a PR with a fix: #10251. It replaces the per-attempt openPromise with a single persistent promise plus shared resolve/reject handles that survive reconnects, so existing waitForConnection() waiters follow the current attempt instead of being stuck on the first failed socket. Verified end-to-end against your reproduction repo — thanks for the excellent minimal repro!

[luontola]

I encountered a similar bug. The "task stays queued after the timeout fires" finding may be relevant additional information to this issue.

Claude's analysis of whether this and that are same issues:

Likely yes — same root cause. Both describe a non-deterministic race in @vitest/browser where the tester iframe's first WebSocket attempt stays in CONNECTING and the orchestrator-side waitForConnection() ends up parked on a stale openPromise, so the run hangs and (eventually) the 60s connect timeout fires.
Matches what we saw: same error string, same project, same "stalls until the harness timeout expires" behavior, same non-determinism.

One nuance: the diagnostics we pulled show that even after the timeout fires the file task stays at mode: "queued" — the error becomes an unhandled rejection instead of failing the file. PR #10251 would probably mask that by preventing the connect failure in the first place (the persistent-promise fix means the
reconnect succeeds and the iframe actually runs). But the "timeout fires → file not failed → run hangs" path is a second latent bug. If you only get the upstream fix, you'd likely stop seeing the hang; the secondary issue would only resurface if a tester ever genuinely fails to connect for unrelated reasons.

Claude's full bug report:

Vitest hangs forever when a browser test iframe fails to connect within 60s

Summary

When the browser-mode tester iframe fails to establish its WebSocket back to the Vitest server ("Cannot connect to the server in 60 seconds" from @vitest/browser/dist/client.js), the error is surfaced via state.getUnhandledErrors() but the file's task is never marked as failed. It stays at mode: "queued" with result: undefined indefinitely. The parent Vitest process keeps waiting for a result that will never come, so vitest run never exits.

Environment

• vitest@4.1.4
• @vitest/browser@4.1.4
• @vitest/browser-playwright@4.1.4
• Playwright chromium (chromium_headless_shell-1217), headless
• Node v24.14.1, macOS 26.4.1 (Darwin 25.4.0, arm64)
• Three projects in one run: unit (vmForks), unit-forks (forks), browser (chromium) (forks)
• 61 *.browser.test.tsx files in the browser project
• Command: vitest run --project unit --project unit-forks --project browser

What happens

After ~5 minutes the run reached 444/445 files passed. The remaining file stayed queued and never completed. CPU on the parent and all 12 chromium renderer processes dropped to ~0%. The process did not exit.

Expected behavior

If the orchestrator's "Cannot connect to the server in 60 seconds" timeout fires for a test file, that file should be marked failed (or retried) and the run should terminate with a non-zero exit code. Vitest should never silently hang because a tester iframe didn't phone home.

Reproduction

Not deterministic — re-running the same suite did not reproduce. Suspected trigger: contention while many chromium tabs initialize in parallel (each registers an MSW service worker), causing one tester iframe to miss the 60s connect window.

If a minimal repro is needed, artificially delaying the tester WS upgrade by >60s for one file should reproduce the same terminal state.

Diagnostic evidence

The process was diagnosed live via the Node inspector (kill -SIGUSR1 <pid> → CDP on 127.0.0.1:9229) by walking [[Scopes]] of the setupBrowserRpc HTTP upgrade listener to reach the Vitest instance, then reading vitest.state.

Main thread state

• process._getActiveHandles().length === 60 (1 server, 1 child process, 55 sockets, 2 write streams, 1 read stream)
• process._getActiveRequests().length === 0
• Top JS frame: processTimers (Node internal — pure event-loop idle, no pending I/O)

Vitest state

{
  "totalFiles": 445,
  "byState": { "pass": 444, "unset": 1 },
  "unhandledErrors": 1
}

The single unhandled error:

Error: Cannot connect to the server in 60 seconds
    at http://localhost:63315/node_modules/.pnpm/@vitest+browser@4.1.4_…/node_modules/@vitest/browser/dist/client.js?v=630ba3a0:433:12

The single not-passing file (full task dump):

{
  "filepath": ".../src/.../XyzPage.browser.test.tsx",
  "projectName": "browser (chromium)",
  "dump": {
    "type": "suite",
    "name": "src/.../XyzPage.browser.test.tsx",
    "mode": "queued",
    "errors": [],
    "children": []
  }
}

Note: result is unset, errors is empty on the task even though state.getUnhandledErrors() knows about the timeout. The error is not routed back to the failing file.

Browser sessions

12 _browserSessions entries are still alive, all projectName: "browser (chromium)", none have a resolve/reject callback retained:

{ "files": [], "hasResolve": false, "hasReject": false,
  "filesKeys": ["project", "connected", "fail"] }

So the sessions reached a state where the file list is gone and there's nothing left to settle, yet the parent still treats one file as pending.

Suspected fix location

@vitest/browser/dist/client.js line ~433 throws the connect-timeout error. That error needs to propagate as a session failure rather than an unhandled rejection — i.e. session.fail(err) (or equivalent on the orchestrator side) should be invoked so the file's task transitions to fail and the run can complete.

Relevant code on the server side that already supports session.fail(...): @vitest/browser/dist/index.js in resolveTester (catch branch). A symmetric path is missing for the orchestrator-side connect timeout.

Workarounds in user code

None known. testTimeout / hookTimeout don't apply because no test code ran. The only reliable workaround is a wall-clock kill around the CLI invocation (gtimeout 10m pnpm vitest run …).

[austinrr]

I hit what looks like this same deadlock, with a trigger that needs no proxy — it happens whenever a browser-mode run starts while Docker is tearing containers down.

Trigger. a pre-push hook runs a Go test suite that uses testcontainers (one Postgres container per package), then runs vitest. go test returns before testcontainers has finished removing those containers, and a browser run started inside that window gets stuck or hangs, never reporting back.

Browser run started…	Containers still up	Result
as soon as go test returned	2	stuck, 2 of 2
after waiting for the containers to go	0	passed, 2 of 2

Polling docker ps -q --filter "label=org.testcontainers=true" until it is empty resolved the issue. I think the container churn stalls the first websocket upgrade long enough to hit exactly the CONNECTING → drop → reconnect sequence described here.

What it looks like while stuck, inspected after the Docker work had already finished:

• 121 ESTABLISHED sockets on the vitest process, still listening on [::1]:63315 and [::1]:63316 — so the browser did reconnect, matching the "reconnect replaces client.ws" part of the above analysis.
• Chromium burning driving high CPU usage across ~30 renderer processes.
• Node's main thread sleeping. No test files report.
• The trigger is long gone — no go test processes, no containers.

On 4.1.10 it surfaces as:

Error: Failed to connect to the browser session "9644d385-873e-43e5-b2ea-56fedb95d648" [client (chromium)] within the timeout.
 ❯ Timeout._onTimeout node_modules/vitest/dist/chunks/cli-api.BK8pd4xc.js:465:33

which is the isConnected/isReady handshake never completing — consistent with a tester that reconnected but never processed prepare. On 4.1.0 the same stall hung forever with no output; one run blocked a push for 17 minutes before we killed it by hand.

Raising the timeout does not help. browser.connectTimeout: 180_000 just moves the failure from ~64s to
~183s. The readiness signal never arrives, so it is not a case of needing more time.

Versions: vitest / @vitest/browser / @vitest/browser-playwright 4.1.10, vite 8.0.0, playwright 1.58.2, Node
24.13.0, Linux, chromium headless.

[borshua]

Written by an AI agent (Claude Code) on behalf of @borshua, who has reviewed it.

We hit this on GitHub Actions with vitest 3.2.6 / @vitest/browser@3.2.6 (built-in playwright provider, chromium headless, 115 Storybook story files, 2-core ubuntu-latest, plain localhost — no proxy or tunnel), so it does not look 4.x-only: the openPromise/registerWS shape described here is present in 3.2.6's dist/client.js. Rate is ~50% per attempt over 18 attempts, and it has never reproduced on a 12-core laptop where the same files pass in ~12s. Symptom matches: output stops mid-run, no summary, zero failed assertions, process never exits.

Because the step was already instrumented, there are resource samples taken during the stall (every 5s, for six minutes after output stopped). Every field is frozen: mem_avail 5804→5807MB, disk_avail 8359→8364MB, chromium 7 processes at 1415MB RSS, node 5 at ~960MB, all alive — none reaped, and dmesg reported no OOM kills on the three runs where we captured it. So OOM, disk exhaustion and worker contention are all excluded. The detail that seemed most relevant to this issue: chromium RSS is frozen to the megabyte, and sits at ~1415MB versus ~2900MB during normal execution — i.e. the contexts are idle rather than busy, consistent with a tester iframe that loaded but never received prepare/execute.

Two incidental observations on the same snippet, in case they are useful: setTimeout(...)?.unref?.() evaluates to undefined in a browser (where setTimeout returns a number), so timeout is undefined and the clearTimeout(timeout) on the resolve path is a no-op; and the close handler reconnects without settling the previous openPromise, which is the part that leaves an existing waiter stranded. Given the ~50% per-attempt rate, this suite can distinguish a working fix from a non-fix in a handful of runs if that is useful to anyone working on it.