Repository navigation
Commit 80496c0
test(js-sdk): run the full unit test suite in a browser (#1609)
> [!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](e2b-dev/runtime@e832b1ed40f488dd1159fdece027bad004522be0)~~
| ~~6 `Sandbox.list({ limit })` pagination tests~~ | **rolled out
2026-07-24** |
> | ~~[belt#2068](e2b-dev/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](#sdk-294)
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.
```bash
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:
```ts
// 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:
```ts
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](e2b-dev/runtime@e832b1e),
**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](e2b-dev/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.
<a id="sdk-294"></a>
**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:
```ts
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`:
```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:
```ts
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:
```ts
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](https://claude.com/claude-code)
---------
Co-authored-by: Claude <[email protected]>1 parent e1fbe86 commit 80496c0
35 files changed
Lines changed: 358 additions & 747 deletions
File tree
- .changeset
- .github/workflows
- packages/js-sdk
- src
- envd
- tests
- api
- envd
- runtimes/browser
- sandbox
- commands
- files
- git
- pty
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
11 | | - | |
| 11 | + | |
12 | 12 | | |
13 | 13 | | |
14 | 14 | | |
| |||
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
34 | | - | |
35 | | - | |
36 | | - | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
37 | 38 | | |
38 | | - | |
39 | | - | |
40 | | - | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
41 | 45 | | |
42 | 46 | | |
43 | 47 | | |
44 | 48 | | |
45 | | - | |
| 49 | + | |
46 | 50 | | |
47 | 51 | | |
48 | 52 | | |
| |||
90 | 94 | | |
91 | 95 | | |
92 | 96 | | |
93 | | - | |
94 | | - | |
| 97 | + | |
95 | 98 | | |
96 | | - | |
| 99 | + | |
97 | 100 | | |
98 | 101 | | |
99 | 102 | | |
100 | 103 | | |
101 | | - | |
| 104 | + | |
102 | 105 | | |
103 | 106 | | |
104 | | - | |
| 107 | + | |
105 | 108 | | |
106 | 109 | | |
107 | 110 | | |
108 | | - | |
| 111 | + | |
109 | 112 | | |
110 | 113 | | |
111 | 114 | | |
| |||
163 | 166 | | |
164 | 167 | | |
165 | 168 | | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
35 | 35 | | |
36 | 36 | | |
37 | 37 | | |
| 38 | + | |
| 39 | + | |
38 | 40 | | |
39 | 41 | | |
40 | 42 | | |
| |||
46 | 48 | | |
47 | 49 | | |
48 | 50 | | |
49 | | - | |
50 | 51 | | |
51 | 52 | | |
52 | | - | |
53 | | - | |
54 | 53 | | |
55 | | - | |
56 | 54 | | |
57 | 55 | | |
58 | 56 | | |
| |||
63 | 61 | | |
64 | 62 | | |
65 | 63 | | |
66 | | - | |
67 | | - | |
68 | 64 | | |
69 | 65 | | |
70 | 66 | | |
71 | | - | |
72 | 67 | | |
73 | 68 | | |
74 | 69 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
| 32 | + | |
32 | 33 | | |
33 | 34 | | |
34 | 35 | | |
35 | 36 | | |
36 | 37 | | |
37 | 38 | | |
| 39 | + | |
38 | 40 | | |
39 | 41 | | |
40 | 42 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
168 | 168 | | |
169 | 169 | | |
170 | 170 | | |
171 | | - | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
172 | 176 | | |
173 | | - | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
174 | 187 | | |
175 | 188 | | |
176 | 189 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
6 | | - | |
7 | | - | |
8 | 6 | | |
9 | 7 | | |
10 | 8 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | | - | |
3 | 2 | | |
4 | 3 | | |
5 | 4 | | |
| |||
20 | 19 | | |
21 | 20 | | |
22 | 21 | | |
23 | | - | |
| 22 | + | |
24 | 23 | | |
25 | 24 | | |
26 | 25 | | |
| |||
316 | 315 | | |
317 | 316 | | |
318 | 317 | | |
319 | | - | |
| 318 | + | |
320 | 319 | | |
321 | 320 | | |
322 | 321 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| 8 | + | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
| |||
68 | 69 | | |
69 | 70 | | |
70 | 71 | | |
71 | | - | |
72 | | - | |
73 | | - | |
74 | | - | |
75 | | - | |
76 | | - | |
77 | | - | |
78 | | - | |
79 | | - | |
80 | | - | |
81 | | - | |
82 | | - | |
83 | | - | |
84 | | - | |
85 | | - | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
86 | 92 | | |
87 | 93 | | |
88 | 94 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
126 | 126 | | |
127 | 127 | | |
128 | 128 | | |
| 129 | + | |
129 | 130 | | |
130 | 131 | | |
131 | 132 | | |
| |||
0 commit comments