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

[mishushakov]

Important

Blocked on one production deploy. The SDK side is already un-gated, so no further code change is needed here — the browser leg just stays red until it rolls out (the leg only ever runs against production; staging callers pass node-only, which drops it).

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

Everything else is green: 8 failed files, 65 passed, 2 skipped — and every one of the 15 failing tests is in the table 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.

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 changeset: test-only, matching test(js-sdk): run the template test suite on Bun #1600 and the other recent test(js-sdk) commits.
• 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

Low Risk
Test and CI wiring only—no production SDK behavior changes in this diff. Residual risk is flaky or red CI until production CORS fixes land, and heavier Playwright runs on the new leg.

Overview
Expands browser coverage from a single React smoke test to the same unit + connectionConfig suites that Bun/Deno/Cloudflare already run, executed in headless Chromium via @vitest/browser + Playwright (pnpm test:browser).

Adds a dedicated tests/runtimes/browser/vitest.config.mts with a process.env → import.meta.env shim, forwards only E2B_* env into the browser, and excludes Node-only suites (bundle/undici/msw-node). noProcessGlobal.test.ts dynamically imports the SDK with process removed so create/read/command paths work like a real bundle.

CI gains a browser matrix leg; Playwright install/cache moves off Node onto that leg. Staging node-only still drops browser (documented: only leg that exercises API CORS behavior).

Removes the old vitest browser React project, run.test.tsx, and React-related devDependencies; Chromium install moves from pretest to pretest:browser.

Shared test fixes for cross-runtime: CommandExitError instead of vacuous ProcessExitError asserts; dedupe in files/read.test.ts; drop stale vi.doUnmock('undici') in http2 tests; replace node:crypto/Buffer/path with Web APIs; corsHttpServerCmd for in-sandbox fetches; browser-aware skips/assertions for stable sandbox host / envdApiUrl.

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

[github-actions]

Package Artifacts

Built from 915c003. Download artifacts from this workflow run.

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

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

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

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

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

pip install ./e2b-2.35.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".

[chatgpt-codex-connector]

Import the SDK after removing the process shim

Because this static import is evaluated during test-file collection, after processEnv.setup.ts has already installed globalThis.process, this browser-only test no longer exercises SDK module evaluation in a real no-process environment. A regression that adds a bare top-level process read anywhere under ../../../src would pass here but still crash for browser users before Sandbox.create() runs; dynamically import the SDK inside the test after Reflect.deleteProperty(globalThis, 'process') (or run this file without the setup shim) to preserve the smoke test's original coverage.

Useful? React with 👍 / 👎.

[mishushakov]

Correct, and fixed in 4c94fca — the SDK is now imported inside the test body, after Reflect.deleteProperty(globalThis, "process"). As you say, the static import was evaluated at collection time with the shim still installed, so module-eval-time coverage was vacuous; only the call path was covered. Verified: the SDK module graph now evaluates with no process global and the test gets as far as Sandbox.create.

[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: bf5d7cf

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.}