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

[mishushakov]

Note

Both upstream blockers have rolled out — the browser leg is green, with nothing gated or skipped for being a browser.

needed	blocked	status
infra#3388	6 Sandbox.list({ limit }) pagination tests	rolled out 2026-07-24
belt#2068	13 stopped-sandbox tests	rolled out 2026-08-26
belt#2068 on the traffic-token path	sandbox requires traffic access token	rolled out — the test passes as of 2026-09-09

The 15th failure was not an infra problem and is fixed in this PR (1964dde) — see the browser's connection-drop wording below.

pnpm test:browser against production, 2026-09-09: 77 files (76 passed, 1 skipped), 424 tests (420 passed, 4 skipped), 0 failing, 143s. The last gap — the proxy answering a traffic-token 403 and its preflight without CORS headers — is closed on the orchestrator side, so sandbox requires traffic access token now reads the 403 from Chromium as intended. It was deliberately left un-gated rather than skipped, so the leg went green on its own the moment the rollout completed. The Node suite is green on the same tree (--project unit --project connectionConfig: 88 files, 614 passed, 1 skipped). Staging Node legs may still fail repo-wide for reasons unrelated to this branch (staging template builder returning template builder not found, staging auto-pause losing sandboxes).

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. 77 files, 76 passing against production, nothing red. The one skipped file is tests/runtime.test.ts, whose two tests assert Node/Workers runtime detection off process.release and so have nothing to assert on a browser host.

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, rolled out 2026-07-24 — the six tests are un-gated here and pass. 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. Fixed upstream in belt#2068 and confirmed on production: isRunning() now returns false for a stopped sandbox in the browser, and the 13 tests that depended on it pass.

The kill-mid-request error was a separate, SDK-side bug — originally filed under SDK-294 as another symptom of the missing CORS headers. It isn't: belt#2068 rolled out, the other 13 went green, and killing the sandbox while a command is running throws an actionable error still failed with SandboxError: 2: [unknown] network error. When the connection drops mid-request the SDK probes the sandbox's health to tell a killed sandbox from a transient blip, but the probe is gated on the connection-dropped message, whose wording is runtime-specific — and the browser's was missing:

const CONNECTION_TERMINATED_MESSAGES = [
  'terminated',                                     // Node (undici)
  'The socket connection was closed unexpectedly',  // Bun
  'error reading a body from connection',           // Deno
  'Network connection lost',                        // Cloudflare Workers
  'network error',                                  // Browser  ← added
]

So the probe never ran and the error stayed generic. The fragment is broad, which is fine by construction: matching only earns a health probe, and the error stays generic unless the probe confirms the sandbox is gone. A browser reports every failed request identically on purpose, so this is the only wording available. Both entry points (handleRpcErrorWithHealthCheck for RPC, handleEnvdApiFetchError for the envd HTTP API) share the predicate, so one edit covers both; the per-runtime tables in handleRpcError.test.ts and handleEnvdApiError.test.ts gain a Browser row. No Python counterpart — it detects this by exception type, not message wording, and has no browser runtime.

belt#2068 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). That is un-gated here too.

How limitations are handled

No capability flags — nothing is skipped to avoid a browser failure. Four tests do skip, each on an assertion that does not exist in a browser rather than one that fails there: the two tests/runtime.test.ts detection tests above; sandbox_url defaults to stable sandbox host in production, which has a browser counterpart asserting the opposite (the stable host is deliberately not used there); and an adopted foreign stream forwards cancellation to its source, because a browser cannot stream a request body at all, so the SDK buffers instead of adopting the stream — the sibling assertion expect(streamed).toBe(streams) covers that positively. The one still-failing test is left red on purpose, waiting on the upstream rollout rather than gated around; see the callout at the top. 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: all five tests this un-gates pass — ping server in running sandbox, sandbox works without token, auto-resume wakes paused sandbox on http request, pause and resume a sandbox with http server (that one needed belt#2068, since it calls isRunning() on a paused sandbox), and sandbox requires traffic access token, which reads a proxy-synthesized 403 after a preflight that can't carry the token — the last piece of the belt#2068 rollout. That's the CORS server working end-to-end through the proxy against production.

Two in-sandbox servers are written inline by their own tests rather than started from corsHttpServerCmd — the maskRequestHost header-capturing server and the self-signed HTTPS backend behind httpsPorts — and both send Access-Control-Allow-Origin for the same reason.

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 ten suites that mock the API with msw/node, whose 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 two source fixes, each with a patch changeset — the toBlob stream drain (below) and the browser connection-drop wording (above). Everything else is tests and CI.
• Kept up to date with main by merging (four times so far; earlier revisions were rebased). What conflicted each time and how it was resolved: Playwright moved into a playwright:install script, so pretest:browser delegates to it; new msw/node suites are added to the browser suite's exclude list as they land (ten now); packages/js-sdk/package.json conflicts against every dev-dep refresh, since main still carries the seven React devDeps this branch drops — resolved to main's versions and catalog: specifiers minus those; pnpm-lock.yaml is always reset to main's and regenerated with pnpm install --lockfile-only rather than hand-merged, so its only delta from main is the React tree; main's rewrites of the shared live tests (polling assertions, vi.waitFor helpers, and hoisting this branch's local waitForHttpStatus into tests/setup.ts) are taken wholesale, keeping only the corsHttpServerCmd call sites on top. Note the Playwright bump to ^1.62 invalidates a local Chromium cache — pnpm run playwright:install; CI is unaffected.
• 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: 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. (An earlier revision also put the canFetchSandboxServers gate on pause and resume a sandbox with http server; that gate was deleted wholesale later in the branch when the tests moved to corsHttpServerCmd.)
• 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

SDK-293

SDK-294

[cursor]

PR Summary

Medium Risk
Two user-facing SDK behavior changes (upload buffering and error classification on dropped connections) ship alongside a large new browser CI path that gates on CORS-sensitive live API behavior.

Overview
The JS SDK now runs the shared unit and connectionConfig suites in headless Chromium via a dedicated test:browser config and CI matrix leg, replacing the old React smoke test and dropping React-related devDependencies. Playwright install and caching apply only to that leg.

toBlob drains ReadableStream bodies with getReader() instead of new Response(stream), so browser file uploads no longer send the literal string [object ReadableStream]. Browser mid-request disconnects are recognized by adding network error to the connection-terminated message list so health probing can surface TimeoutError when the sandbox was killed instead of a generic network error.

Tests were adjusted for the browser host: CORS-enabled sandbox HTTP helpers, Web Crypto and TextEncoder instead of Node-only APIs, CommandExitError in kill assertions, browser skips or expectations for stable sandbox host URLs, removal of duplicate stream-read tests and stale vi.doUnmock calls in http2 tests, and a test that loads the SDK with no process global.

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

[github-actions]

Package Artifacts

Built from 95f82f0. Download artifacts from this workflow run.

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

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

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

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

Code Interpreter JS SDK (@e2b/code-interpreter@2.8.1-browser-test-suite.0):

npm install ./e2b-code-interpreter-2.8.1-browser-test-suite.0.tgz

Desktop JS SDK (@e2b/desktop@2.4.1-browser-test-suite.0):

npm install ./e2b-desktop-2.4.1-browser-test-suite.0.tgz

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

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

Code Interpreter Python SDK (e2b-code-interpreter==2.10.0+browser.test.suite):

pip install ./e2b_code_interpreter-2.10.0+browser.test.suite-py3-none-any.whl

Desktop Python SDK (e2b-desktop==2.5.0+browser.test.suite):

pip install ./e2b_desktop-2.5.0+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]

🦋 Changeset detected

Latest commit: 2abaa12

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
e2b	Patch

Not sure what this means? Click here to learn what changesets are.

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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