Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/bun-runtime.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"e2e": patch
---

The CLI runs on Bun 1.4.3 or newer without Node.js: `bunx --bun e2e run`. In a Bun project, `e2e init` registers the MCP server with `bunx`. An older Bun gets the version to upgrade to. [What differs on Bun](https://e2e.com/docs/reference/cli#bun).
30 changes: 29 additions & 1 deletion .github/workflows/spec.yml
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,34 @@ jobs:
- name: Unit and integration tests
run: pnpm test

# The built CLI on Bun with no Node.js on its PATH
# (packages/e2e/tests/integration/bun-runtime.test.ts): the floor
# runtime.ts names, and the newest release. Vitest itself runs on Node.js.
bun:
runs-on: blacksmith-4vcpu-ubuntu-2404
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
bun: [1.4.3, latest]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: pnpm/action-setup@9fd676a19091d4595eefd76e4bd31c97133911f1 # v4.2.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 26
cache: pnpm
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: ${{ matrix.bun }}
- run: pnpm install --frozen-lockfile
- run: pnpm --filter e2e run build
- name: The CLI on Bun ${{ matrix.bun }}
run: pnpm --filter e2e exec vitest run tests/integration/bun-runtime.test.ts
env:
# Requires Bun rather than skipping without it.
E2E_BUN: bun

# A new user's first install of the packed packages, which pnpm 11 and
# later fail on any dependency build script (scripts/install-smoke.ts).
install:
Expand All @@ -133,7 +161,7 @@ jobs:
# passes (the change cannot reach it); a failed or cancelled one fails it.
gate:
name: spec gate
needs: [check, test, install]
needs: [check, test, bun, install]
if: ${{ always() }}
runs-on: blacksmith-4vcpu-ubuntu-2404
timeout-minutes: 5
Expand Down
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -612,8 +612,9 @@ trees, on both platforms, without a device.

- CI: `.github/workflows/spec.yml` runs lint, typecheck, and the testbed on
Node 26, `pnpm test` on the newest Node 22, 24, and 26 and on the
`engines.node` floors (22.22.3, 24.8.0), and `scripts/install-smoke.ts`, a
fresh install of the packed packages with pnpm 11 and 12; `benchmark.yml` runs the
`engines.node` floors (22.22.3, 24.8.0), the CLI on Bun 1.4.3 and the
latest Bun, and `scripts/install-smoke.ts`, a fresh install of the packed
packages with pnpm 11 and 12; `benchmark.yml` runs the
web benchmark's two suites; `mobile.yml` runs the mobile benchmark's on an
iOS simulator and an Android emulator (KVM on x64 Linux); `docs.yml`
checks the docs. All four run on pull requests and in the merge queue
Expand Down
5 changes: 3 additions & 2 deletions docs/ci.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@ description: Run e2e on GitHub Actions, GitLab CI/CD, Expo Workflows, Bitrise, C
---

e2e runs on each CI service that can run Node 24.8 or later (22.22.3 or
later on Node 22). Each job installs the dependencies, starts the app or a
device, runs `npx e2e run`, and uploads `.e2e/`.
later on Node 22), or [Bun](/reference/cli#bun) 1.4.3 or later for web tests.
Each job installs the dependencies, starts the app or a device, runs the
tests, and uploads `.e2e/`.

## Pick your CI service

Expand Down
2 changes: 1 addition & 1 deletion docs/mcp-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ step with no recording.
`e2e init` offers to register the server in `.mcp.json` (Claude Code),
`.cursor/mcp.json` (Cursor), and `.codex/config.toml` (Codex). Install the
project dependencies and start the MCP client in the project directory so
`npx` uses the installed e2e version. By hand:
`npx` (`bunx` in a Bun project) uses the installed e2e version. By hand:

<Tabs>
<Tab title="Claude Code">
Expand Down
2 changes: 1 addition & 1 deletion docs/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ The agent installs the [e2e skill](/coding-agents), so later prompts such as
"add a test for checkout" need no more setup.

<Note>
Use Node.js 24.8 or newer (22.22.3 or newer on Node.js 22). On Windows, run inside WSL. Mobile tests also
Use Node.js 24.8 or newer (22.22.3 or newer on Node.js 22), or [Bun](/reference/cli#bun) 1.4.3 or newer for web tests. On Windows, run inside WSL. Mobile tests also
need Xcode with an iOS simulator runtime, or the Android SDK with an emulator.
</Note>

Expand Down
41 changes: 33 additions & 8 deletions docs/reference/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,11 @@ bunx e2e run tests/signup.e2e.ts --headed # one file, with a visible browser
</CodeGroup>

<Note>
The CLI needs Node.js 24.8 or newer, or 22.22.3 or newer on Node.js 22. Any
package manager installs it: npm, pnpm, Yarn with or without Plug'n'Play, or
Bun. The CLI runs on Node.js, not on the Bun or Deno runtimes; `bunx e2e`
runs it on Node.js. Under Yarn Plug'n'Play on Node.js 24.8 through 24.11.0, a
`.cts` file fails to load: Node.js rejects the source Yarn's loader hands on.
24.11.1 and later load it.
The CLI needs Node.js 24.8 or newer (22.22.3 or newer on Node.js 22), or
[Bun](#bun) 1.4.3 or newer. Any package manager installs it: npm, pnpm, Yarn
with or without Plug'n'Play, or Bun. Under Yarn Plug'n'Play on Node.js 24.8
through 24.11.0, a `.cts` file fails to load: Node.js rejects the source
Yarn's loader hands on. 24.11.1 and later load it.
</Note>

## Reference
Expand Down Expand Up @@ -414,7 +413,7 @@ bunx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
| `--config <path>` | The config every session loads unless `open_session` names one. Default: the nearest `e2e.config.ts`, `.mts`, `.js`, or `.mjs`. |
| `--target <name>` | The target every session opens on. Default: the only target, or the one `open_session` names. |
| `--headed` | Shows the UI in sessions whose `open_session` does not set `headed`, when the engine supports it. |
| `--max-sessions <n>` | Sessions open at once, each with its own browser or device, 1 through 16. Default: 4. |
| `--max-sessions <n>` | Sessions open at once, each with its own browser or device, 1 through 16. Default: 4. On [Bun](#bun), 1. |

The [MCP server](/reference/mcp) page covers these options in full, plus the
tools and the session rules.
Expand Down Expand Up @@ -1006,7 +1005,7 @@ bunx e2e doctor --target web --headed

| Check | Status |
| --- | --- |
| `node` | `pass`: the Node.js version. On an unsupported runtime, `--json` still prints a report with `node` as `fail`. |
| `node` | `pass`: the Node.js or Bun version. On an unsupported runtime, `--json` still prints a report with `node` as `fail`. |
| `config` | `pass` with `path` and `targets` (`name`, `platform`, `engine`), or `fail` with the `CONFIG_*` or `UNKNOWN_TARGET` code. A failed `config` is the last check. |
| Engine checks, with `target` | What the target's engine reports, such as the web engine's `browser`: `pass` when installed, `warn` when the first run will download it, `skip` with a browser provider or `connect`; or the mobile engine's agent-device checks (`agent-device`, `toolchain`, `ios-runner-cache`, `device` per configured device, `target-app`) and `app-path`, with only `device`, as `skip`, for a device provider. An engine that reports nothing adds no check. `engine` is `skip` when the engine has no `doctor` hook, and `fail` when the hook threw, timed out, or returned a malformed check. |
| `model`, with `agent` | `model` and `judge` as `provider` and `modelId`, the names the AI SDK instance reports. `pass` or `fail` for a model on an [`e2e login`](/subscriptions), from the stored login or the provider's API key variable, with `login` set when the agent's models read one login. `unknown` for any other model, because the model reads its own credential. With `--check-model`, `pass` when every model answered, else `fail` with the error code, its message prefixed `model:` or `judge:` when the agent has both. `skip` when the agent has no model. `unknown` with `executor` when a custom executor brings its own agent and declares no model or judge; any model it declares is checked like an agent's. |
Expand Down Expand Up @@ -1330,3 +1329,29 @@ E2E_TELEMETRY_DEBUG=1 bunx e2e run
exports.
- A model credential the provider rejects names the variable the provider
reads.

## Bun

On Bun 1.4.3 or newer, the CLI runs without Node.js. When Node.js is
installed, `bunx e2e` and `bun run` follow the CLI's `node` shebang and run it
on Node.js. `bunx --bun e2e` and `bun --bun run` run it on Bun. Without
Node.js, all of them run it on Bun. The web engine runs on Bun.
`@e2e-dev/mobile` and the integrations are not verified on Bun yet.

Bun compiles the config and test files with its own TypeScript support. Where
that differs from Node.js:

- A `#` import that maps to a directory does not load its index. Map the
import to the file.
- A legacy decorator in a `.cts` file fails to load. Move the class to a `.ts`
file.
- `e2e run --watch` and `e2e mcp` read `tsconfig.json` one time, and load a
file that an `import()` or `require()` names with a computed path one time.
Restart them after you edit either, or after you add a file that an import
did not find.
- `e2e mcp` opens one session at a time and ignores `--max-sessions`.
- [`e2e/runner`](/reference/runner) needs Node.js.
- An app `command` with `executable: 'node'` needs Node.js, unless `bun run`
or `bunx` started the CLI. They put a `node` on `PATH` that runs Bun.
- A test that a helper declares after an `await` reports the line in the
helper.
2 changes: 1 addition & 1 deletion docs/reference/errors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ These appear in terminal output and in the report as plain string codes.
| `WORKER_EXIT` | A worker exited unexpectedly while running a file. The test in flight fails with `WORKER_CRASH`, and the file's other tests are skipped. Attempts that finished before the exit stay in the report, including a retry's earlier attempts and a serial group's finished members. The crash is recorded as the attempt after them, or on the last attempt when it came after it (an `afterAll`). When an unhandled rejection ends the worker (see `UNHANDLED_REJECTION`), the rejection is the run error, not this one | infrastructure | 3 |
| `WORKER_CRASH` | A worker exited during a specific test | infrastructure | 3 |
| `WORKER_ENTRY_MISSING` | The worker entry module could not be resolved. Packaging fault. | infrastructure | 3 |
| `NODE_UNSUPPORTED` | The runtime cannot run e2e's TypeScript loader: a Node.js outside `^22.22.3 \|\| >=24.8.0`, Bun (no `module.registerHooks`), or Deno. The CLI checks this before it starts and exits 2 with the same sentence. The loader checks again where it registers its hooks, for a host that runs e2e's runner without the CLI | infrastructure | 3 |
| `NODE_UNSUPPORTED` | The runtime cannot run e2e: a Node.js outside `^22.22.3 \|\| >=24.8.0`, a Bun older than 1.4.3, or Deno. The CLI checks this before it starts and exits 2 with the same sentence. The loader checks again before it loads a config or test file, for a host that runs e2e's runner without the CLI. On Bun, `run`, `list`, `explore`, and `openHost` from `e2e/runner` throw it too: they need Node.js | infrastructure | 3 |
| `TYPESCRIPT_COMPILER_UNAVAILABLE` | oxc, which compiles e2e's TypeScript, could not be loaded; the message gives the cause. Most often its native bindings for this platform (`@oxc-transform/binding-<platform>-<arch>`, `@oxc-parser/binding-<platform>-<arch>`) are not installed. npm leaves them out with `--omit=optional`, or when `package-lock.json` was written on another platform (npm/cli#4828). Install again without `--omit=optional`, or delete `package-lock.json` and `node_modules` and run `npm install` | infrastructure | 3 |
| `IMAGE_CODEC_UNAVAILABLE` | `@napi-rs/image`, which reads and writes the PNGs of screenshots, could not be loaded; the message gives the cause. It is loaded when the first screenshot is read or written, so a run that takes none never needs it. Most often its native binding for this platform (`@napi-rs/image-<platform>-<arch>*`) is not installed. npm leaves it out with `--omit=optional`, or when `package-lock.json` was written on another platform (npm/cli#4828). Install again without `--omit=optional`, or delete `package-lock.json` and `node_modules` and run `npm install`. The package publishes no binding for Linux on ppc64, s390x, or riscv64, where `toHaveScreenshot` cannot work, and neither can an agent screenshot the runner has to resize (one with a side over 768 px) | infrastructure | 3 |
| `ENGINE_FAILURE` | Any engine fault with no more specific mapping | infrastructure | 3 |
Expand Down
8 changes: 4 additions & 4 deletions docs/reference/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ bunx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
| [`--config <path>`](#config) | discovered like `e2e run` |
| [`--target <name>`](#target) | the only target |
| [`--headed`](#headed) | headless |
| [`--max-sessions <n>`](#max-sessions) | `4` |
| [`--max-sessions <n>`](#max-sessions) | `4`, `1` on Bun |

#### `--config`

Expand All @@ -70,8 +70,8 @@ session whose `open_session` does not set `headed`.

#### `--max-sessions`

How many sessions may be open at once, 1 through 16. See
[Several sessions](#several-sessions).
How many sessions may be open at once, 1 through 16. On
[Bun](/reference/cli#bun), one. See [Several sessions](#several-sessions).
Comment thread
okwasniewski marked this conversation as resolved.
Resolved

```bash
e2e mcp --max-sessions 8 # default: 4
Expand Down Expand Up @@ -490,7 +490,7 @@ own names, scoped to the target's platform. A mobile project that passes
The server ships with `e2e`. `e2e init` offers to register it in
`.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and
`.codex/config.toml` (Codex). Install dependencies and start the MCP client
in the project directory so `npx` uses the installed e2e version. By hand:
in the project directory so `npx` (`bunx` in a Bun project) uses the installed e2e version. By hand:

<CodeGroup>
```bash npm
Expand Down
5 changes: 5 additions & 0 deletions docs/reference/runner.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ its findings, `list` returns a selection, and `openHost` hosts e2e sessions
in another test runner. Importing `e2e` from a test file does not load the
runner.

<Note>
`run`, `list`, `explore`, and `openHost` need Node.js. On Bun, they throw
`NODE_UNSUPPORTED`; run tests with the [CLI](/reference/cli#bun) there.
</Note>

```ts title="scripts/run-e2e.ts"
import type { E2EConfig } from 'e2e';
import { run } from 'e2e/runner';
Expand Down
2 changes: 1 addition & 1 deletion packages/e2e/src/cli/bin.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
#!/usr/bin/env node
import { unsupportedRuntimeMessage } from '../internal/node-version.ts';
import { unsupportedRuntimeMessage } from '../internal/runtime.ts';
import { packageVersion } from '../internal/package-version.ts';
import { ignoreBrokenPipes } from './broken-pipe.ts';
import type { DoctorReport } from './doctor.ts';
Expand Down
7 changes: 4 additions & 3 deletions packages/e2e/src/cli/doctor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import type { ResolvedTarget } from '../config/targets.ts';
import { selectTargets } from '../collect/select.ts';
import type { EngineDoctorCheck } from '../engine/index.ts';
import { classifyError, InfrastructureError } from '../internal/errors.ts';
import { SUPPORTED_NODE_RANGE } from '../internal/node-version.ts';
import { onBun, SUPPORTED_BUN_RANGE, SUPPORTED_NODE_RANGE } from '../internal/runtime.ts';
import { budgetText, cancelledError, NEVER_ABORTS, withAbort, withinCleanupBudget } from '../internal/time.ts';
import { loginOf } from '../oauth/login-model.ts';
import { apiKeyFor, getProvider, loginHint, type ProviderId } from '../oauth/providers.ts';
Expand Down Expand Up @@ -167,9 +167,10 @@ function errorOutcome(cause: unknown): { readonly code: string; readonly message
return { code, message };
}

/** The runtime, which passed: `bin.ts` reports the one it refuses before this module loads. */
/** The runtime, which passed: `bin.ts` reports the one it refuses before this module loads. Its id stays `node` on Bun too. */
function nodeCheck(): DoctorCheck {
return { id: 'node', status: 'pass', message: `Node.js ${process.versions.node} (${SUPPORTED_NODE_RANGE})` };
const message = onBun ? `Bun ${process.versions['bun']} (${SUPPORTED_BUN_RANGE})` : `Node.js ${process.versions.node} (${SUPPORTED_NODE_RANGE})`;
return { id: 'node', status: 'pass', message };
}

/** Loads and resolves the config the way `e2e run` does. */
Expand Down
2 changes: 1 addition & 1 deletion packages/e2e/src/cli/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -585,7 +585,7 @@ function createProgram(version: string, telemetry: Telemetry, updateCheck: Updat
.addOption(new Option('--headless').hideHelp())
.option(
'--max-sessions <n>',
`sessions open at once, each with its own browser or device, ${SESSION_BOUNDS.min} through ${SESSION_BOUNDS.max} (default: ${SESSION_BOUNDS.default})`,
`sessions open at once, each with its own browser or device, ${SESSION_BOUNDS.min} through ${SESSION_BOUNDS.max} (default: ${SESSION_BOUNDS.default}; 1 on Bun)`,
parseBoundedInt(SESSION_BOUNDS),
)
.addHelpText(
Expand Down
4 changes: 2 additions & 2 deletions packages/e2e/src/cli/init.ts
Original file line number Diff line number Diff line change
Expand Up @@ -302,9 +302,10 @@ export async function init(root: string, options: InitOptions = {}): Promise<Ini
);
if (isCancelled(mcpFiles)) return cancel();
facts.mcp = mcpFiles.length > 0;
const manager = detectPackageManager(cwd, pkg.manifest.packageManager);
let mcpRegistrations: ReturnType<typeof planMcpRegistration>['registrations'];
try {
const plan = planMcpRegistration(cwd, mcpFiles);
const plan = planMcpRegistration(cwd, mcpFiles, manager);
mcpRegistrations = plan.registrations;
for (const link of plan.links) {
clack.log.warn(`Symlink, not touching: ${link.relative} -> ${link.target} (e2e mcp server)`);
Expand Down Expand Up @@ -366,7 +367,6 @@ export async function init(root: string, options: InitOptions = {}): Promise<Ini
if (isCancelled(proceed) || !proceed) return cancel();
}

const manager = detectPackageManager(cwd, manifest.packageManager);
const install = given.install ?? await clack.confirm({ message: `Install dependencies with ${manager}?`, initialValue: true });
if (isCancelled(install)) return cancel();
facts.install = install;
Expand Down
14 changes: 7 additions & 7 deletions packages/e2e/src/cli/init/mcp-config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@

import { existsSync, lstatSync, readFileSync } from 'node:fs';
import path from 'node:path';
import type { PackageManager } from '../../internal/package-manager.ts';
import { realpathOfExisting } from '../../internal/paths.ts';
import { readCodexConfig, updateCodexConfig } from './codex-config.ts';

Expand All @@ -28,9 +29,6 @@ export const MCP_LOCATIONS = [

const MCP_SERVER_NAME = 'e2e';

/** How clients start the server from the project with e2e installed. */
const SERVER_ENTRY = { command: 'npx', args: ['e2e', 'mcp'] } as const;

export interface McpRegistration {
/** Project-relative file, e.g. `.mcp.json`. */
readonly relative: string;
Expand Down Expand Up @@ -119,7 +117,9 @@ export function findRegisteredMcpFiles(cwd: string): string[] {
* indentation are preserved. A file reached through a symlink is never read;
* it is returned among `links` for the caller to report and skip.
*/
export function planMcpRegistration(cwd: string, files: readonly string[]): McpPlan {
export function planMcpRegistration(cwd: string, files: readonly string[], manager: PackageManager): McpPlan {
// How clients start the server from the project with e2e installed; a Bun project may have no Node.js, so no npx.
const launch = { command: manager === 'bun' ? 'bunx' : 'npx', args: ['e2e', 'mcp'] };
const registrations: McpRegistration[] = [];
const links: McpLink[] = [];
for (const file of files) {
Expand All @@ -137,8 +137,8 @@ export function planMcpRegistration(cwd: string, files: readonly string[]): McpP
: {};
const existing = servers[MCP_SERVER_NAME];
const entry = typeof existing === 'object' && existing !== null && !Array.isArray(existing)
? { ...existing, ...SERVER_ENTRY }
: SERVER_ENTRY;
? { ...existing, ...launch }
: launch;
if (JSON.stringify(existing) === JSON.stringify(entry)) continue;
const merged: McpConfigDocument = { ...document, mcpServers: { ...servers, [MCP_SERVER_NAME]: entry } };
const original = existsSync(absolute) ? readFileSync(absolute, 'utf8') : undefined;
Expand All @@ -147,7 +147,7 @@ export function planMcpRegistration(cwd: string, files: readonly string[]): McpP
relative: file,
existing: original !== undefined,
absolute,
content: file.endsWith('.toml') ? updateCodexConfig(original ?? '', SERVER_ENTRY) : `${JSON.stringify(merged, null, indent)}\n`,
content: file.endsWith('.toml') ? updateCodexConfig(original ?? '', launch) : `${JSON.stringify(merged, null, indent)}\n`,
});
}
return { registrations, links };
Expand Down
Loading
Loading