test(js-sdk): run the full unit test suite in a browser

[mishushakov]

Caution

The upstream fix this depended on was abandoned. infra#3389 was closed unmerged on 2026-08-04, and so was its successor infra#3565; the cors package does not exist on infra main. The 15 stopped-sandbox tests below are therefore not waiting on a deploy — they are waiting on work that was dropped.

Since the browser leg is not continue-on-error, it feeds the required SDK Tests Status check, which gates merges and the release publish step. This PR cannot merge until that is resolved, either by reviving the infra fix or by re-adding a canObserveStoppedSandbox gate so the affected tests report as skipped.

needs	blocks	symptom
infra#3388	6 Sandbox.list({ limit }) pagination tests	rolled out — these pass
infra#3389 — closed, not merged	14 stopped-sandbox tests + the traffic-access-token one	14 × TypeError: Failed to fetch, 1 × SandboxError instead of TimeoutError

Current browser leg: 8 failed files, 67 passed, 1 skipped — every failing test is in the row above.

What

Promotes the browser leg from a single React smoke test to the full unit + connectionConfig suite running inside a real headless Chromium (@vitest/browser + Playwright) — the same coverage test:bun / test:deno / test:cf get. 69 files / 343 tests green locally against production.

pnpm test:browser   # installs Chromium via pretest:browser, then runs the suite

React is gone as requested — the smoke test (tests/runtimes/browser/run.test.tsx) and its seven devDependencies (react, react-dom, @types/react, @types/react-dom, @testing-library/react, @vitejs/plugin-react, vitest-browser-react). Chromium installation moves off the default pretest hook onto pretest:browser, so plain pnpm test no longer downloads a browser.

The one thing the smoke test uniquely covered — the SDK driven with no process global at all, the way a real browser bundle runs — is kept as a dedicated test, since the rest of the suite runs against a process.env shim that would mask a regression there:

// tests/runtimes/browser/noProcessGlobal.test.ts
Reflect.deleteProperty(globalThis, 'process')
const sandbox = await Sandbox.create(template, { apiKey, domain })
await sandbox.files.write('hello.txt', 'Hello World')

Failure screenshots are off (browser.screenshotFailures: false): these tests never render anything, so vitest's default would write a PNG of a blank page per failed test into .vitest-attachments/.

Test bugs the leg surfaced

1. Two assertions were vacuous. commands/kill and pty/kill asserted rejects.toThrowError(ProcessExitError) — but ProcessExitError has never been exported from src. Vite's SSR transform resolves the missing named import to undefined, so toThrowError(undefined) asserted nothing on any runtime; real ESM in the browser turns it into a hard SyntaxError. Now CommandExitError.

2. files/read.test.ts ran three tests twice — a byte-identical duplicated block, provisioning a second real sandbox for each on every runtime leg.

3. A cold-cache-only flake, root-caused. api/http2 and envd/http2 carried dead vi.doUnmock('undici') / vi.doUnmock('../../src/utils') calls from an old refactor (neither file mocks anything any more). The bare 'undici' one made Vite discover and pre-bundle a Node HTTP client mid-run, reloading the browser page under the running suite and breaking whichever file was being collected. Verified: 1-in-4 failure before, three cold-cache runs green after.

Node-only test APIs are replaced with cross-runtime equivalents: node:crypto randomUUID/createHash → WebCrypto, Buffer → TextEncoder/TextDecoder, path.basename → inline.

Two real browser bugs found

Both verified over the wire; neither was fixable in the SDK alone.

Pagination silently truncated — the cursor lives in the x-next-token response header, which the API didn't name in Access-Control-Expose-Headers, so a browser withheld it and every page looked like the last:

const paginator = Sandbox.list({ limit: 10 })
const all = []
while (paginator.hasNext) all.push(...(await paginator.nextItems()))
// Node: all 200 sandboxes.  Browser (before the fix): 10, hasNext === false, no error.

Fixed upstream in infra#3388, so the tests are un-gated here and just need the prod rollout (see the callout above). SDK-293.

SDK-294 — isRunning() threw instead of returning false. A stopped sandbox's 502 came from the edge without CORS headers, so the probe rejected opaquely (running: 204 + ACAO: * / paused: 502 + no ACAO). Because a browser always preflights the SDK's envd requests (they carry E2b-Sandbox-Id/E2b-Sandbox-Port) and a preflight needs an ok status, adding the header to the 502 alone wasn't enough — the OPTIONS path needed a 2xx too. This also silently downgraded the kill-mid-request error from the actionable TimeoutError to a generic SandboxError across 24 call sites.

Fixed upstream in infra#3389, which also fixes the content negotiation the investigation turned up: the proxy chose HTML over JSON by User-Agent sniffing, and browser fetch can't override its UA, so an SDK call from a browser got the HTML error page where it expects JSON (Accept was ignored). Both are un-gated here.

How limitations are handled

No capability flags — nothing is skipped for being a browser. The five tests that read a response from a server the test itself starts in the sandbox now start a CORS-enabled one, via corsHttpServerCmd in tests/setup.ts:

// was: 'python3 -m http.server 8000' — no CORS headers, so a browser hands the
// test an opaque `TypeError: Failed to fetch` instead of the response
await sandbox.commands.run(corsHttpServerCmd(8000), { background: true })

This was originally gated behind a canFetchSandboxServers flag as an inherent browser limitation. It isn't one: the server is the test's own, and a real browser app's server opts into CORS exactly the same way — so the gate was hiding coverage of getHost and the proxy path rather than documenting a wall. Access-Control-Allow-Headers plus do_OPTIONS also covers the traffic-access-token test, whose custom header the browser preflights.

Confirmed on the browser leg (run): of the five tests this un-gates, three now pass — ping server in running sandbox, sandbox works without token, auto-resume wakes paused sandbox on http request. That's the CORS server working end-to-end through the proxy against production. The other two are the two infra#3389 needs anyway: pause and resume a sandbox with http server calls isRunning() on a paused sandbox, and sandbox requires traffic access token reads a proxy-synthesized 403 (which 3389 gives CORS headers) after a preflight that can't carry the token (which 3389 answers on the getDestination error path).

The exclude list is only for genuinely Node-only suites (tests/bundle/** reads dist via node:fs, tests/undici.test.ts resolves packages off process.versions.node) plus the two msw suites, whose msw/node entry pulls in node:http and can't be served to a browser. Porting those needs setupWorker plus a service worker from a public dir — tracked as a follow-up on SDK-292, and worth doing since cancellation is the most runtime-divergent part of this SDK.

A real bug the leg caught

main added toUploadBody leaves an async-iterable foreign stream alone while this branch was in review, and it failed in Chromium with expected '[object ReadableStream]' to be 'hello'. Not a test artifact — the mechanism, confirmed directly:

const asyncIterable = { async *[Symbol.asyncIterator]() { yield new TextEncoder().encode('hello') } }
await new Response(asyncIterable).text()
// Node:     'hello'                    (undici accepts any async iterable)
// Chromium: '[object ReadableStream]'   (the web platform does not)

toDispatchableStream treats async-iterability as "the platform will accept this", which is an undici extension rather than web behavior. So buffering a stream via new Response(stream) in a browser stringified it, and this silently uploaded 23 bytes of text instead of the file:

import { ReadableStream } from 'web-streams-polyfill' // or any replaced global / other realm

await sandbox.files.write('data.bin', new ReadableStream({ /* ... */ }))
// Before: the file contains the literal text "[object ReadableStream]"
// After:  the file contains the data

The fix drains the stream through its reader — the one part every implementation shares — instead of guessing what the platform accepts. Note the obvious fix is wrong: skipping the async-iterable branch in the browser re-wraps a native stream when globalThis.ReadableStream has been replaced by a polyfill, which is precisely what that branch exists to prevent (there's a test for it). Verified in Chromium and Node.

CI

New browser matrix leg on ubuntu-22.04, with the Playwright cache moved onto it (no other leg needs Chromium any more). The leg is dropped by node-only staging callers, and it's the only leg whose result depends on the API's CORS headers — the matrix comment now says so, rather than claiming the non-Node legs add no backend signal.

Notes

• No longer test-only: carries one source fix (below) with a patch changeset. Everything else is tests and CI.
• Rebased onto main (84 commits). Playwright had meanwhile been extracted into a playwright:install script scoped to the node leg — pretest:browser now delegates to it rather than duplicating the install — and six new msw/node suites were added, which can't be served to a browser and are excluded.
• vi.stubEnv and delete process.env.X keep working in the browser because the shim aliases process.env to import.meta.env, which is where vitest puts config env and where stubEnv writes. Verified E2B_DEBUG=1 pnpm test:browser correctly skips the debug-gated tests.
• Verification for the CORS server, since a browser-side change like this is easy to get subtly wrong: ran a local instance of the exact generated command and fetched it cross-origin (different port = different origin) from real Chromium — simple GET readable, and a custom-header request survives the preflight. Negative control against a plain python -m http.server reproduces the TypeError: Failed to fetch the browser leg was showing, so the probe is meaningful rather than vacuous. Also checked there's exactly one Access-Control-Allow-Origin header — a duplicate would make browsers reject the response.
• Review feedback addressed in 4c94fca: the pause and resume a sandbox with http server test now carries the canFetchSandboxServers gate too (it fetches its own python -m http.server, so it was a real miss that the isRunning failure happened to mask), and noProcessGlobal.test.ts imports the SDK dynamically inside the test body — a static import is evaluated at collection time, while the process shim is still installed, so it only covered the call path and not module evaluation.
• No new type errors: 22 pre-existing test type errors before and after (the 2 that went away are the ProcessExitError ones this fixes).
• Not addressed, pre-existing, flagged in case you want a follow-up: tests/api/list.test.ts duplicates five tests byte-for-byte (only the three betaPause ones intentionally differ, instance vs static), and files/write.test.ts:130 repeats write file as a strict subset of the test at :6 — together ~7 redundant sandboxes per run per leg. Left alone rather than deleting tests outside this change's scope.

Closes SDK-292

🤖 Generated with Claude Code

[linear-code]

SDK-292

[cursor]

PR Summary

Medium Risk
Touches the file-upload body conversion used by all runtimes, so a drain bug can corrupt or fail uploads. Browser tests now depend on production CORS behavior that staging does not exercise.

Overview
toBlob never releases the stream reader if read() throws, so a failed drain leaves the stream locked. Gzip uploads in the browser still go through new Response(compressed).blob(), which is the same brand-check path this change was meant to avoid. The new browser CI leg is skipped on staging (node-only), so CORS regressions only show up against production.

^{Reviewed by Cursor Bugbot for commit 3a3a3f9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Package Artifacts

Built from c6127d6. Download artifacts from this workflow run.

JS SDK (e2b@2.45.1-browser-test-suite.0):

npm install ./e2b-2.45.1-browser-test-suite.0.tgz

CLI (@e2b/cli@2.17.2-browser-test-suite.0):

npm install ./e2b-cli-2.17.2-browser-test-suite.0.tgz

Python SDK (e2b==2.45.1+browser.test.suite):

pip install ./e2b-2.45.1+browser.test.suite-py3-none-any.whl

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5626cfff60

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[claude]

LGTM — test-only PR that expands the browser CI leg to the full unit suite, with no production code changes.

Extended reasoning...

Overview

This PR touches only test infrastructure: the browser vitest config, test files (replacing Node-only APIs like Buffer/node:crypto with WebCrypto/TextEncoder), the CI workflow matrix, package.json devDependencies (dropping React test tooling), and pnpm-lock.yaml. No files under packages/js-sdk/src/ are modified.

Security risks

None. No auth, crypto business logic, or user-facing behavior changes — only test harness and CI configuration.

Level of scrutiny

Low-to-moderate scrutiny is appropriate: this is a test-only change with no production code path affected. I spot-checked the PR's own claims against src/: CommandExitError is indeed exported (ProcessExitError never existed, confirming the described vacuous-assertion bug fix), and the browser-specific skip flags (canFetchSandboxServers, canReadPaginationToken, canObserveStoppedSandbox) correctly mirror existing runtime !== 'browser' CORS-avoidance logic already present in src/connectionConfig.ts. The new capability-gated skips are a reasonable way to surface browser limitations without silently dropping coverage.

Other factors

The bug hunting system found no issues. The PR description is thorough and self-documents the rationale for each test change (duplicate test removal, flaky mock cleanup, Node-API replacements). No changeset is needed since this is test-only, consistent with prior similar PRs (#1600) per CLAUDE.md guidance.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5ca9d31

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit afe3fb8. Configure here.}