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

.changeset/olive-jars-tap.md

@@ -0,0 +1,5 @@
+---
+'e2b': patch
+---
+
+Fix uploads of non-native `ReadableStream`s in the browser silently sending the text `[object ReadableStream]` instead of the data. Buffering a stream drained it with `new Response(stream)`, which accepts any async iterable on Node (an undici extension) but only its own stream class in a browser, stringifying anything else. Streams are now drained through the reader, which every implementation supports.

.changeset/soft-moons-repeat.md

@@ -0,0 +1,5 @@
+---
+'e2b': patch
+---
+
+Report a sandbox killed mid-request as an actionable `TimeoutError` in the browser. When the connection to a sandbox drops mid-request the SDK probes the sandbox's health to tell a killed sandbox apart from a transient network blip, but the probe only ran for connection-dropped wordings it recognized, and the browser's (`network error`) was missing — so killing a sandbox while a command was running surfaced a generic `SandboxError: [unknown] network error` instead of `TimeoutError: ... The sandbox was killed or reached its end of life while the request was in flight.`

.github/workflows/js_sdk_tests.yml

@@ -8,7 +8,7 @@ on:
         type: string
         default: ''
       node-only:
-        description: 'Run only the Node legs (skip Bun, Deno, and Cloudflare)'
+        description: 'Run only the Node legs (skip Bun, Deno, Cloudflare, and the browser)'
         required: false
         type: boolean
         default: false
@@ -29,14 +29,17 @@ jobs:
     strategy:
       fail-fast: false
       # With node-only (set by staging callers) the matrix collapses to the
-      # Node legs: the Bun/Deno/Cloudflare legs re-run suites the Node legs
-      # already cover and add sandbox/build load without extra backend
-      # signal, so the other runtimes are exercised against production only.
+      # Node legs: the Bun/Deno/Cloudflare/browser legs re-run suites the Node
+      # legs already cover and add sandbox/build load, so the other runtimes
+      # are exercised against production only. Note this does drop backend
+      # signal for the browser leg specifically — it's the only one that
+      # depends on the API's CORS headers — so a staging-only CORS regression
+      # surfaces on the production run rather than before merge.
       matrix:
         include: >-
           ${{ inputs.node-only
             && fromJSON('[{"runtime": "node", "os": "ubuntu-22.04"}, {"runtime": "node", "os": "windows-latest"}]')
-            || fromJSON('[{"runtime": "node", "os": "ubuntu-22.04"}, {"runtime": "node", "os": "windows-latest"}, {"runtime": "bun", "os": "ubuntu-22.04"}, {"runtime": "deno", "os": "ubuntu-22.04"}, {"runtime": "cloudflare", "os": "ubuntu-22.04"}, {"runtime": "cloudflare-deploy", "os": "ubuntu-22.04"}]') }}
+            || fromJSON('[{"runtime": "node", "os": "ubuntu-22.04"}, {"runtime": "node", "os": "windows-latest"}, {"runtime": "bun", "os": "ubuntu-22.04"}, {"runtime": "deno", "os": "ubuntu-22.04"}, {"runtime": "cloudflare", "os": "ubuntu-22.04"}, {"runtime": "cloudflare-deploy", "os": "ubuntu-22.04"}, {"runtime": "browser", "os": "ubuntu-22.04"}]') }}
     runs-on: ${{ matrix.os }}
     # The cloudflare-deploy leg is advisory: it deploys to a brand-new
     # Cloudflare preview account on every run, so it inherits that account's
@@ -82,22 +85,21 @@ jobs:
         run: |
           pnpm install --frozen-lockfile
 
-      # Only the Node runtime runs the vitest `browser` project, which drives
-      # Chromium through Playwright.
+      # Only the browser leg needs Chromium, which Playwright drives.
       - name: Get Playwright version
-        if: matrix.runtime == 'node'
+        if: matrix.runtime == 'browser'
         id: playwright-version
         run: echo "version=$(node -p "require('playwright/package.json').version")" >> "$GITHUB_OUTPUT"
 
       - name: Cache Playwright browsers
-        if: matrix.runtime == 'node'
+        if: matrix.runtime == 'browser'
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
-          path: ${{ matrix.os == 'windows-latest' && '~/AppData/Local/ms-playwright' || '~/.cache/ms-playwright' }}
+          path: ~/.cache/ms-playwright
           key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
 
       - name: Install Playwright Chromium
-        if: matrix.runtime == 'node'
+        if: matrix.runtime == 'browser'
         run: pnpm run playwright:install
 
       # The unit bundle test and the Cloudflare deploy config fail in CI when
@@ -153,3 +155,13 @@ jobs:
         env:
           E2B_API_KEY: ${{ secrets.E2B_API_KEY }}
           E2B_DOMAIN: ${{ inputs.E2B_DOMAIN }}
+
+      # Full unit + connectionConfig suite inside Chromium (vitest browser mode).
+      # Chromium comes from the cached install step above; `pretest:browser`
+      # covers local runs, where it's a no-op once installed.
+      - name: Run test suite in the browser
+        if: matrix.runtime == 'browser'
+        run: pnpm test:browser
+        env:
+          E2B_API_KEY: ${{ secrets.E2B_API_KEY }}
+          E2B_DOMAIN: ${{ inputs.E2B_DOMAIN }}

packages/js-sdk/package.json

@@ -35,6 +35,8 @@
     "generate:mcp": "json2ts -i ./../../spec/mcp-server.json -o src/sandbox/mcp.d.ts --unreachableDefinitions --style.singleQuote --no-style.semi",
     "check-deps": "knip",
     "playwright:install": "playwright install chromium",
+    "pretest:browser": "pnpm run playwright:install",
+    "test:browser": "vitest run --config tests/runtimes/browser/vitest.config.mts",
     "test:bun": "bunx --bun vitest run --project unit --project connectionConfig --project template",
     "test:cf": "vitest run --config tests/runtimes/cloudflare/vitest.config.mts",
     "test:cf:deploy": "vitest run --config tests/runtimes/cloudflare-deploy/vitest.config.mts",
@@ -46,13 +48,9 @@
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.18.7",
     "@redocly/cli": "2.46.1",
-    "@testing-library/react": "^16.3.2",
     "@types/node": "^20.19.19",
     "@types/platform": "^1.3.6",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitejs/plugin-react": "^4.3.4",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
     "dotenv": "^16.4.5",
@@ -63,12 +61,9 @@
     "npm-run-all": "^4.1.5",
     "openapi-typescript": "^7.13.0",
     "playwright": "^1.62.1",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
     "tsdown": "^0.22.14",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^4.1.10",
-    "vitest-browser-react": "^2.2.0",
     "wrangler": "^4.123.0"
   },
   "files": [

packages/js-sdk/src/envd/rpc.ts

@@ -29,12 +29,14 @@ export type SandboxHealthCheck = () => Promise<boolean | undefined>
  *   - Bun:                 `The socket connection was closed unexpectedly`
  *   - Deno:                `error reading a body from connection`
  *   - Cloudflare Workers:  `Network connection lost`
+ *   - Browser:             `network error`
  */
 const CONNECTION_TERMINATED_MESSAGES = [
   'terminated',
   'The socket connection was closed unexpectedly',
   'error reading a body from connection',
   'Network connection lost',
+  'network error',
 ]
 
 /**

packages/js-sdk/src/utils.ts

@@ -168,9 +168,22 @@ export async function toBlob(
   if (isBlobLike(data)) {
     return new Blob([await data.arrayBuffer()], { type: data.type })
   }
-  // ReadableStream - must consume to get Blob
+  // ReadableStream - must consume to get Blob. Drained through the reader
+  // rather than `new Response(stream)`: the platform only accepts a body it
+  // recognizes, and what counts differs per runtime (undici takes any async
+  // iterable, a browser takes only its own stream class and stringifies the
+  // rest to "[object ReadableStream]"). The reader is the portable part.
   if (isReadableStreamLike(data)) {
-    return new Response(toDispatchableStream(data)).blob()
+    const reader = data.getReader()
+    const chunks: BlobPart[] = []
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) {
+        break
+      }
+      chunks.push(value)
+    }
+    return new Blob(chunks)
   }
   // String or ArrayBuffer - create Blob. A cross-realm ArrayBuffer needs no
   // special handling: buffer sources are recognized by V8, not by brand.

packages/js-sdk/tests/api/http2.test.ts

@@ -3,8 +3,6 @@ import { afterEach, expect, test, vi } from 'vitest'
 afterEach(() => {
   vi.restoreAllMocks()
   vi.resetModules()
-  vi.doUnmock('undici')
-  vi.doUnmock('../../src/utils')
   delete process.env.E2B_API_CONNECTIONS
   delete process.env.E2B_API_INFLIGHT_REQUESTS
 })

packages/js-sdk/tests/api/list.test.ts

@@ -1,5 +1,4 @@
 import { assert } from 'vitest'
-import { randomUUID } from 'crypto'
 
 import { Sandbox, SandboxInfo } from '../../src'
 import { sandboxTest, isDebug } from '../setup.js'
@@ -20,7 +19,7 @@ sandboxTest.skipIf(isDebug)(
 )
 
 sandboxTest.skipIf(isDebug)('list sandboxes with filter', async () => {
-  const uniqueId = randomUUID()
+  const uniqueId = crypto.randomUUID()
   const extraSbx = await Sandbox.create({ metadata: { uniqueId } })
 
   try {
@@ -316,7 +315,7 @@ sandboxTest.skipIf(isDebug)(
 )
 
 sandboxTest.skipIf(isDebug)('list sandboxes with filter', async () => {
-  const uniqueId = randomUUID()
+  const uniqueId = crypto.randomUUID()
   const extraSbx = await Sandbox.create({ metadata: { uniqueId } })
 
   try {

packages/js-sdk/tests/connectionConfig.test.ts

@@ -4,6 +4,7 @@ import {
   setupRequestController,
   wrapStreamWithConnectionCleanup,
 } from '../src/connectionConfig'
+import { runtime } from '../src/utils'
 
 // Store original env vars to restore after tests
 let originalEnv: { [key: string]: string | undefined }
@@ -60,21 +61,26 @@ test('api_url has correct priority', () => {
   assert.equal(config.apiUrl, 'http://localhost:8080')
 })
 
-test('sandbox_url defaults to stable sandbox host in production', () => {
-  delete process.env.E2B_SANDBOX_URL
-  delete process.env.E2B_DOMAIN
-  delete process.env.E2B_DEBUG
-
-  const config = new ConnectionConfig()
-
-  assert.equal(
-    config.getSandboxUrl('sbx-test', {
-      sandboxDomain: 'e2b.app',
-      envdPort: 49983,
-    }),
-    'https://sandbox.e2b.app'
-  )
-})
+// The stable host is deliberately not used in a browser (CORS); the browser
+// side of this branch is asserted in connectionConfig.browser.test.ts.
+test.skipIf(runtime === 'browser')(
+  'sandbox_url defaults to stable sandbox host in production',
+  () => {
+    delete process.env.E2B_SANDBOX_URL
+    delete process.env.E2B_DOMAIN
+    delete process.env.E2B_DEBUG
+
+    const config = new ConnectionConfig()
+
+    assert.equal(
+      config.getSandboxUrl('sbx-test', {
+        sandboxDomain: 'e2b.app',
+        envdPort: 49983,
+      }),
+      'https://sandbox.e2b.app'
+    )
+  }
+)
 
 test('sandbox_direct_url keeps per-sandbox host in production', () => {
   delete process.env.E2B_SANDBOX_URL

packages/js-sdk/tests/envd/handleEnvdApiError.test.ts

@@ -126,6 +126,7 @@ describe('handleEnvdApiFetchError', () => {
     Bun: new Error('The socket connection was closed unexpectedly'),
     Deno: new TypeError('error reading a body from connection'),
     'Cloudflare Workers': new Error('Network connection lost.'),
+    Browser: new TypeError('network error'),
   }
 
   for (const [runtime, error] of Object.entries(runtimeTerminatedErrors)) {

packages/js-sdk/tests/envd/handleRpcError.test.ts

@@ -70,6 +70,7 @@ describe('handleRpcErrorWithHealthCheck', () => {
     Bun: 'The socket connection was closed unexpectedly',
     Deno: 'error reading a body from connection',
     'Cloudflare Workers': 'Network connection lost.',
+    Browser: 'network error',
   }
 
   test('returns a TimeoutError when the health check says the sandbox is not running', async () => {

packages/js-sdk/tests/envd/http2.test.ts

@@ -3,8 +3,6 @@ import { afterEach, expect, test, vi } from 'vitest'
 afterEach(() => {
   vi.restoreAllMocks()
   vi.resetModules()
-  vi.doUnmock('undici')
-  vi.doUnmock('../../src/utils')
   delete process.env.E2B_ENVD_RPC_CONNECTIONS
   delete process.env.E2B_ENVD_INFLIGHT_REQUESTS
   delete process.env.E2B_ENVD_RPC_INFLIGHT_REQUESTS

packages/js-sdk/tests/runtime.test.ts

@@ -1,12 +1,13 @@
 import { afterEach, expect, test, vi } from 'vitest'
 
-// The unit project also runs under Bun, Deno, and Cloudflare's workerd, where
-// the host runtime's own unstubbable marker (globalThis.Bun / globalThis.Deno /
-// the Cloudflare-Workers user agent) correctly wins detection — these
-// scenarios only exist on a Node host.
+// The unit project also runs under Bun, Deno, Cloudflare's workerd, and a real
+// browser, where the host runtime's own unstubbable marker (globalThis.Bun /
+// globalThis.Deno / the Cloudflare-Workers user agent / `window`) correctly
+// wins detection — these scenarios only exist on a Node host.
 const isNodeHost =
   typeof (globalThis as any).Bun === 'undefined' &&
   typeof (globalThis as any).Deno === 'undefined' &&
+  typeof (globalThis as any).window === 'undefined' &&
   (globalThis as any).navigator?.userAgent !== 'Cloudflare-Workers'
 
 afterEach(() => {

packages/js-sdk/tests/runtimes/browser/importMeta.d.ts

@@ -0,0 +1,7 @@
+// Vite exposes the runner's `env` config on `import.meta.env`, which the
+// browser suite reads instead of `process.env`. The canonical types live in
+// `vite/client`, but vite is only a transitive dependency here (via vitest) and
+// isn't resolvable from this package, so declare the shape the suite uses.
+interface ImportMeta {
+  readonly env: Record<string, string | undefined>
+}

packages/js-sdk/tests/runtimes/browser/noProcessGlobal.test.ts

@@ -0,0 +1,50 @@
+import { assert, test } from 'vitest'
+
+import { template } from '../../template'
+
+// Bundlers don't give browser apps a `process` unless asked to, so the SDK has
+// to be fully configurable through explicit options — `getEnvVar`
+// (src/api/metadata.ts) returns '' when `process` is missing rather than
+// throwing. The rest of this suite runs against the `process.env` shim from
+// processEnv.setup.ts, which would mask a regression that reintroduces a bare
+// `process` read on the create path, so this test drops the shim entirely and
+// drives a real sandbox the way a browser app has to.
+//
+// The SDK is imported dynamically inside the test, after the shim is gone: a
+// static import is evaluated at collection time, while the shim is still
+// installed, which would let a top-level `process` read anywhere in the module
+// graph pass here and still crash a browser app on import.
+//
+// Config comes from `import.meta.env` (where vitest puts the config's `env`),
+// which is also how a Vite app would hand its own build-time values over.
+const apiKey = import.meta.env.E2B_API_KEY
+const domain = import.meta.env.E2B_DOMAIN || undefined
+const isDebug = import.meta.env.E2B_DEBUG !== undefined
+
+test.skipIf(isDebug)(
+  'drives a sandbox with no process global',
+  async () => {
+    const shim = Reflect.getOwnPropertyDescriptor(globalThis, 'process')
+    Reflect.deleteProperty(globalThis, 'process')
+    assert.equal(typeof process, 'undefined')
+
+    try {
+      const { Sandbox } = await import('../../../src')
+      const sandbox = await Sandbox.create(template, { apiKey, domain })
+
+      try {
+        await sandbox.files.write('hello.txt', 'Hello World')
+        assert.equal(await sandbox.files.read('hello.txt'), 'Hello World')
+
+        const result = await sandbox.commands.run('echo "from the browser"')
+        assert.equal(result.exitCode, 0)
+        assert.equal(result.stdout.trim(), 'from the browser')
+      } finally {
+        await sandbox.kill()
+      }
+    } finally {
+      if (shim) Reflect.defineProperty(globalThis, 'process', shim)
+    }
+  },
+  60_000
+)

packages/js-sdk/tests/runtimes/browser/processEnv.setup.ts

@@ -0,0 +1,15 @@
+// Browsers have no `process`: `getEnvVar` (src/api/metadata.ts) resolves to ''
+// there, so E2B_* can only reach a browser app through whatever shim its
+// bundler injects. Provide that shim — the same thing workerd's nodejs_compat
+// gives the Cloudflare suite for free — so the shared suites can configure the
+// SDK from the environment like they do on every other runtime.
+//
+// `process.env` aliases Vite's `import.meta.env`, which is where vitest puts
+// the config's `env` and what `vi.stubEnv` writes to in browser mode, so env
+// reads and stubbing both behave as they do on Node.
+//
+// Only `env` is defined: `process.release` must stay absent or the SDK would
+// detect the runtime as 'node' instead of 'browser'. Tests that need a
+// browser without any `process` at all delete it themselves — see
+// noProcessGlobal.test.ts.
+Object.assign(globalThis, { process: { env: import.meta.env } })