Files
Donny/강동윤andClaude Opus 5.5 a2d0363128 feat(desktop): add the @e2e-dev/desktop engine on agent-desktop (#1953)
* feat(desktop): add the @e2e-dev/desktop engine on agent-desktop

A desktop engine for native and Electron apps, built on agent-desktop
(vercel-labs, Apache-2.0), which reads and drives apps through the OS
accessibility tree. macOS is the tested platform; this is rollout phase 1
of the ENG-1352 proposal.

- The engine downloads the pinned agent-desktop 1.3.1 release in prepare
  and checks its SHA-256; the npm package is not a dependency because its
  postinstall would fail check:install-scripts.
- Fill text reaches agent-desktop on stdin, never in its arguments.
  Screenshots are cropped to the window and paint every secure field black,
  and are withheld when a secure field has no bounds or the snapshot was
  partial.
- Node ids stay stable across observations, so the agent gets diffs.
- The engine quits only the process it launched, checked by its process
  instance.
- apps/desktop-testbed holds an AppKit sign-in form with deterministic and
  agentic suites.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): accept the remaining budget in the fill arguments

The timeout agent-desktop gets is what is left of the operation's
deadline, so it can be a millisecond under the full budget on a slow
runner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): report field values whole and keep a typed-into field's id

locate answers single-node reads, which the contract says carry the whole
value; the harness cuts what the agent sees. An unnamed field's identity no
longer includes its value, so typing into it is a change, not a remove and
an add. An image is projected as the contract role image, which both
locator spellings resolve to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): withhold a capture with a border instead of masking it in place

A capture within four pixels of the window was taken as the window, so a
two-pixel border shifted every mask. Only a pixel of rounding is accepted
now, any other capture is cropped to its opaque box, and each mask reaches
two pixels past its field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): give a read exactly its budget

The 500 ms floor exists so a click that landed is not reported as cut off;
a read has no such reason and now stops at the operation's deadline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep agent-desktop out of the replay cache and report install failures

E2E_CACHE_DIR names the replay cache, which a project may commit, so the
binary goes to the OS cache directory only, found from the run's
environment. A network or tar failure in prepare is now
AGENT_DESKTOP_INSTALL_FAILED, as the docs say.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): offer doubleTap only with headed, and say what app.open and settle do

agent-desktop double-clicks with the real pointer only, so doubleTap is
declared with headed: true and sent with --headed. The docs said app.open()
quits the app if it runs; it quits only the copy the engine launched. settle
is a fixed wait, not a check that the UI is still.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): drive only the launched process, and keep ids and the select ladder honest

- Every read and scoped command goes to a window of the process the engine
  launched; before app.open() or after the app quit, the engine reads and
  drives nothing, so a developer's own copy is never touched.
- With appPath, the launched executable must come from that bundle; another
  copy registered under the same bundle id fails the open.
- quit keeps the process as the engine's own until it is known to be gone,
  so a failed lookup is reported and dispose tries again.
- Node identities are scoped to their window and retired once gone or
  ambiguous, so neither a twin nor another window's control inherits an id.
- The select ladder passes the label after --, reports a stale ref as
  NODE_STALE, and stops once any command of a way reached the app.
- A press on a control that refuses focus is refused unless it holds focus.
- A root swipe after a restart reads the window again.
- app.open() waits at most 30 s for a readable window, reports any other
  read failure as it is, and is cancelled with its operation.
- A screenshot is withheld when the window read after the capture differs
  in its secure fields.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): read placeholders, mixed checkboxes, and depth-cut trees as agent-desktop reports them

- A placeholder comes from agent-desktop's own placeholder field; the hint
  is kept as an attribute of its own.
- A mixed checkbox reports no checked state, so check() and uncheck() always
  reach the control instead of returning early.
- A node that counts children it did not list (the depth limit) marks the
  tree as cut short, so a screenshot from it is withheld.
- Siblings that share a developer id (AppKit menu items) tell themselves
  apart by name and keep their ids; a status with a developer id keeps its
  id while its text changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): launch an appPath by path and keep every process a launch started

- An appPath bundle is opened by its path (open -n), and the new process
  running from it is taken as the engine's own; launching by bundle id let
  LaunchServices pick another copy with the same id.
- A launch that failed after the app started still leaves the engine owning
  the new process, so the end of the attempt quits it.
- A window is the engine's only when its process instance matches too, so a
  later process given the same pid is never read or driven.
- An app list that is incomplete keeps the process the engine's, to quit
  again in dispose.
- A point action finds the window where it is now, so it works right after
  app.open() and after the window moved.
- A type or fill after a clear that changed the field fails as
  ACTION_MAY_HAVE_COMMITTED, never as a retryable stale ref.
- A screen larger than the binding cap keeps every node it just read.
- The launch wait is 10 s, and each read in it gets what is left of it.
- A bundle id that names no app says so, instead of asking for app.open().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): refuse an archive with the wrong SHA-256 and cache nothing

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(desktop): say app.open brings the app forward, and that only macOS is tested

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): never take another copy as the launched one, and aim point actions at their window

- A launch agent-desktop refused takes no process as its own, and a copy is
  attributed to a launch by id only against a whole app list from before it,
  so cleanup never kills the developer's copy.
- A launch whose outcome is unknown is kept pending and settled by the next
  quit under its own budget, so a timed-out launch still has its app quit.
- A point action goes to the window it was observed in, wherever it is now,
  refuses a point outside that window, and brings it forward before the
  physical click.
- In the select ladder, ELEMENT_NOT_FOUND from select (no such option) goes
  on to the next way; from a command on the list itself it is NODE_STALE.
- A root swipe scrolls the window as it is now.
- With both appPath and bundleId, the appPath build is launched and its
  bundle id must match.
- An open that runs out of its own budget is OPERATION_TIMEOUT; only the full
  launch wait reports an unreadable window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop-testbed): check the saved screenshot for the password field's mask

The test checked only that the file was a PNG, which an unmasked capture
also is. It now decodes the image and requires the solid black bar the
password field's mask paints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(desktop): say which app launches when appPath and bundleId are both set

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): report a read agent-desktop timed out as OPERATION_TIMEOUT

TIMEOUT was NOT_ACTIONABLE for reads as well as inputs, so a snapshot that
ran out of time skipped the launch wait's timeout handling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): tell the launched process apart by a token, and measure points in their window

- Every launch passes a one-time token in the app's environment
  (launch --env, open --env), and a process is the engine's own only when
  ps -E shows that token. Guessing from the app list before and after a
  launch could take, and kill, a copy the developer or another worker
  started at the same time.
- A launch whose outcome is unknown is settled by the next quit, which looks
  for the token for up to 3 s and reports a failure when it finds none.
- A point is measured in the window of the newest screen observe or locate
  handed out, and sent unrounded, so it never lands past the window's edge.
- check and uncheck always go to agent-desktop, which reads the live state.
- One window's node ids stay while another window is read.
- The launch wait's commands share its deadline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): pin option and app validation and the headed-only actions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop-testbed): measure the password mask at the capture's scale

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep identities from colliding, and never drop a secure node

- A node identity is a tagged tuple, so a developer id and a name can never
  spell another control's identity (`shared` + `Edit:` against `shared:Edit`),
  which let one control take another's binding.
- A secure node is never dropped as a wrapper, so its bounds are masked.
- A binding records the window its node was read in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): press keys only into a focused control, type keystrokes, and check the launched process's token

- A press on a control needs its focus to succeed and to hold, and goes into
  the control's own window; before, a refused focus sent the key to
  whatever window had focus.
- The keyboard capability is declared with headed only and types with
  --headed: without physical input agent-desktop sets the text, and the
  contract asks for keystrokes the app's handlers see.
- The process agent-desktop reports for a launch must carry the launch's
  token; a launcher that handed over to a copy already running (a Linux
  desktop file) fails the open and never drives or quits that copy.
- A select that finds no such option never falls through to set-value,
  which would type the label in as free text; a menu left open after a
  missing option is reported as a changed app.
- A read tries the launched app's windows in turn, past a panel
  accessibility cannot read.
- No app bundle is opened once the operation's budget is spent.
- doctor fails an appPath with no Contents/Info.plist.
- The unused latest-screen field is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop-testbed): require a mask the size of the password field, not one black row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(desktop): ship a NOTICE like every other published package

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(desktop): say typing into whatever has focus needs headed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): withhold masks with no area, and give controls their title as text

- A secure field whose box has no area masks nothing, so the screenshot is
  withheld.
- A control reports its title as its text, as on a device, so
  textContent() reads a button's title; an input's name is a label, so it
  gets none.
- A binding keeps its node's box, to find a look-alike again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): find a pressed look-alike by its place, keep unresolved launches, and test on the host's ps

- A press checks focus on the control found again by role and box, since a
  look-alike has a new id in every read; the key is resolved before focus
  moves, and a node read in no window is refused.
- An environment that cannot be read (a macOS system app under SIP, a
  failed lookup) is no evidence: agent-desktop's report of the process it
  launched stands, so system apps open again and are quit at the end.
- A pending launch stays until it is claimed or a whole wait finds none.
- A window row is the engine's only with the launched process instance.
- A screenshot finds secure fields in whole reads of the window, even with
  interactive snapshots, which leave out a secure node with no action.
- A menu read in part never reports an option missing.
- The unit tests read process environments the host's way (ps -E or
  /proc), so they pass on the Linux CI runner, and remove the fake's
  scenario directories.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): dispose every surface a test creates, so no state directory is left behind

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(desktop): drop Electron, so the engine targets native apps only

Electron apps are out of scope for this engine. Remove the paths that
existed only for them: the headed type fallback for a field the
accessibility API cannot set (Electron on Linux), and the expand and
menu-click steps of the select ladder (Electron on Windows and macOS).
A select now tries `select`, then sets the value of a list that takes
none (WinForms), and reports an option `select` cannot find as missing.

The Electron snapshot fixtures go too; the wrapper and shared-id tests
use the AppKit sign-in form and an inline AppKit menu. Docs, the
README, package metadata, and the skill now say native apps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(desktop): match the workspace's vitest 5.1.1

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(desktop): apply the review of #1953

macOS only. prepare and init refuse any other OS: on Windows and Linux
some actions need physical input and GTK's password field is not
reported as secure, so masking would fail open. A config with a desktop
target still loads elsewhere.

The app under test and agent-desktop get only HOME, USER, LOGNAME,
SHELL, PATH, TMPDIR, LANG, LC_*, and __CF_USER_TEXT_ENCODING of the
run's environment, so secrets, model keys, and CI tokens never reach
them. `open` and NSWorkspace both handed the caller's whole environment
to the app.

The app launches in the background (`open -g`, `launch` without
`--activate`) unless headed, so typing at the Mac no longer lands in it.
An app that shows no window after 2 s is brought forward once.
Every launch passes -ApplePersistenceIgnoreState YES.

An appPath app whose environment cannot be read (a system app, a build
signed with `restrict`) is now claimed as the single new copy that was
not running before the launch, instead of polling until the test timed
out and leaving the app running. A launch reported for a copy that ran
before it is refused. An open that finds no process fails within 10 s.

select no longer falls back to set-value, which could type a missing
option into an editable combo box. press sends a key only when the
control's window is the app's key window, and finds the control again by
its stable id. locate fails on a truncated read with no match instead of
proving absence. The reads a screenshot's mask takes hand out no ids.
The window's own Close, Minimize, Zoom, and Full Screen buttons are left
out of the tree. desktop.useWindow() picks the window screen reads.

Stale state directories of killed workers are swept at init. The cached
agent-desktop is reused only when a verified unpack stamped it and its
executable and helper are intact. doctor says the permission checks need
the first run. A pending launch whose lookup timed out stays pending.

Tests: the screenshot-moved test now uses the window the fake lists, and
a steady capture is checked to succeed. Each fix has a test that fails
without it (checked by mutation). The testbed checks the password
field's own box is black and the field beside it is not, and
test:desktop-testbed builds the app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep launches pending after open, and fix four review gaps

A fresh-context review of f0d1bb69f found these, each now with a test:

- openBundle: a failure after `open` ran (a list-apps error, or the
  budget running out while looking) was read as "nothing was sent", so
  the copy `open` started was never quit. Any failure after `open` is
  now ACTION_MAY_HAVE_COMMITTED and leaves the launch pending.
- An app that quits right after launch now fails the open at once,
  before the engine brings its bundle forward, which would have started
  a copy the engine does not own.
- A node inside a look-alike container is no longer marked stable: its
  id is built on its parent's, which is new in every snapshot, so press
  finds it by place again.
- Only a title-bar-sized button (at most 20 points) with a window
  control's name is left out; an app's own Close button stays.
- A window chosen with desktop.useWindow() that closed is now
  INVALID_STATE, not an empty screen a negative assertion would pass on.
- The release cache is swapped by rename instead of deleted first, and
  doctor checks the stamped copy, not only that the file exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): send keys and close select menus in the background, and quit apps killed workers left

Found in live runs on an unlocked Mac:

- A key press never reached an app in the background: agent-desktop
  sends a key to a named window only while that window is active, and
  answered STALE_REF, which the harness retried until the step timed out.
  The key now goes to the process by its app name, once the engine saw
  its copy is the only one with that name; with another copy running,
  press fails at once with NOT_ACTIONABLE and says to use headed.
- selectOption of a missing option on a pop-up button opened its menu,
  waited out the whole action budget, and left the menu open. select now
  waits at most 3 s; a menu it left open is closed with Escape and the
  option reported missing (NOT_ACTIONABLE), the list unchanged.
- A worker that was killed left its app running. Each worker records
  the app it launched and its token; the next run's sweep quits that app
  while its environment still shows the token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): sweep a state directory whose launch record was cut short

A worker killed while writing app.json left half a JSON record. The sweep
parsed it inside the promise's success handler, so the SyntaxError escaped
and every later init failed on the same stale directory. A record that does
not parse now names no process and the directory still goes, and the record
is written to a side file and renamed into place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep the state directory when dispose could not quit the app

dispose removed the state directory even when its quit failed, and app.json
went with it, so the next run's sweep had no pid and token to quit the
leaked app by. The directory now stays while the engine still owns a process
it could not quit; the owner file names a worker that is gone by then, so the
sweep removes the directory after it quits the app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): claim a copy with no readable token only from whole app lists

Two paths took a process as the launch's own on evidence an incomplete app
list cannot give, and the engine later kills what it owns:

- launch by bundle id accepted agent-desktop's reported pid when its
  environment could not be read and the list before the launch was partial,
  so a copy already running could not be ruled out;
- claim() took the single new unreadable copy from a list after the launch
  that left copies out, where a second new one could hide.

The first now refuses the launch and leaves the process alone. The second
reports that it cannot tell; quit keeps the launch pending as it does for a
lookup that ran out of time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): give a background key only what is left of its budget

sendKey built its command options once, so the key sent by the app's name,
after a refused window press and a list of the apps, still carried the budget
the operation had at its start and could run past the deadline. The options
are now built for each command from the time left.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep a select whose menu was left open as possibly committed

After a select that may have reached the app, closing a menu the app had
open was taken as proof that the option was missing and nothing was chosen,
and reported as NOT_ACTIONABLE. An open menu shows neither: it does not say
which control opened it. The failure now stays ACTION_MAY_HAVE_COMMITTED,
naming the option the list may lack, after the menu is closed. A failure to
close the menu (Escape refused while another copy runs) no longer replaces
the select's own error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): measure a point from the window useWindow() chose

performAt measured a point from the window the last read used. After
desktop.useWindow() picked another window, the next tapAt still brought the
old window forward and clicked there. Choosing a window, or going back to the
focused one, now drops that window, so the next point action measures from
the window in use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): read no empty screen from an app that cannot be read

capture() skipped every window it could not snapshot and returned no screen,
so observe showed an empty window and locate found nothing. While the screen
is locked, or after the app crashed, not.toBeVisible() then passed. Opus
reproduced it against the testbed app on a locked Mac.

Now:
- listed windows none of which could be read are a retryable NODE_STALE,
  so a locator reads again until its deadline;
- a chosen window whose snapshot says it is gone is INVALID_STATE, like
  one missing from the list;
- an app whose process is gone is INVALID_STATE.

An app with no window at all still reads as an empty screen. The launch's
readiness wait treats the new errors as a window not readable yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): count no matches in a window read in part

locate() refused a partial read only when nothing matched, and then with a
non-retryable ENGINE_FAILURE. One visible match in a read cut short still
counted as exactly one, though a second could sit in the part left out, so
a strict action or toHaveCount(1) could pass on it. And a locator for a
control not there yet failed at once instead of polling.

A partial read is now a retryable NODE_STALE whatever it matched, so the
locator reads again until its deadline. The docs say so for a window deeper
than the 24 levels a snapshot reads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(desktop): correct getByText on buttons, and macOS-only metadata

- The desktop page said getByText cannot find a button by its title. The
  projection gives a button its title as text too, so it can; getByRole is
  what limits a match to the button.
- The package keywords listed windows and linux, which the engine refuses.
- CONTRIBUTING said a contract change bumps both engines; there are three.
- @e2e-dev/desktop moves to its alphabetical place in the docs package.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): cover the appPath launch and a successful install

Every surface test launched by bundle id, so a change to the open -g -n
arguments, the claim of the copy carrying the token, or its quit would not
fail a test; and the binary tests covered only failed installs.

- An appPath test puts a fake open first on PATH: it records its arguments
  and starts a process with the variable --env names, which the engine
  claims, reads, and quits.
- An install test serves an archive of its own through a digests table
  installPinned now takes (the pinned one by default), installs it twice
  at once, and checks the stamp, that nothing is left beside the entry, and
  that a third install fetches nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): find the app's running copies the way agent-desktop launches it

runningCopies() and claim() listed every app and kept the ones whose
bundle id or name equalled the target exactly. agent-desktop reports the
localized name (Calculator is 계산기 on a Korean Mac) and matches a launch
target in any case, so a copy the launch could hand over to was left out of
the list before it. A copy whose environment cannot be read was then taken
as the launch's own and killed at the end of the test; and a copy a launch
of unknown outcome started was never found, and left running.

Both now ask list-apps --app <target>, which matches the way the launch and
quit() do, and count every process it returns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): stop the fake apps before removing the list of them

afterEach ran cleanupFakes() first, which deletes the file fake.spawned()
reads, so the processes a test left running were never killed and stayed
for their 60 s timer. They are now killed first; no stand-in process is left
after the suite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): report an open LaunchServices refused as starting nothing

openBundle wrapped every failure of open as ACTION_MAY_HAVE_COMMITTED, so a
bundle LaunchServices refused (a missing executable, a bad signature) left the
launch pending. The end of the attempt then looked for its process for 3 s
and failed a second time, telling the user to quit an app that never
started. The error also quoted the whole open command line.

An open that exits with an error, or cannot run, is now ENGINE_FAILURE with
open's own message, and nothing is left to look for. Only an open the budget
or a cancellation stopped stays possibly committed. The appPath tests share
a helper that puts a stand-in open on PATH.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): record the launch token before the launch, and sweep by it

app.json was written only once the launch's process id was known. A worker
killed during the launch (which can wait up to 10 s for its process), or a
launch whose process was never found, left no record, and dispose then
deleted the state directory too. The next run could not find the app.

The record now holds the launch token and is written before anything is
sent. dispose keeps it while a launch is pending, as it does for an app that
would not quit. The sweep quits every process whose environment carries the
token, found by listing the processes, so it needs no process id and
cannot reach a process that took one over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): act on no node read outside the window useWindow() chose

useWindow() changed the window every read used but kept the nodes read
before, so an action on a ref from the old window still reached its control
after a test chose another. Such a ref is now NODE_STALE, which the harness
answers by locating the node again in the window in use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): read no empty screen from an app whose process id was reused

With no window of the launched process listed, capture() checked only that
its process id was alive. Once the app quits, macOS can give that id to
another process, so the read showed an empty screen and a negative assertion
could pass. The app list must now show the same process instance; a list
that left copies out is a retryable NODE_STALE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): make doctor check an appPath bundle the way init does

doctor passed any bundle with a Contents/Info.plist, while init also needs a
CFBundleIdentifier in it, equal to app.bundleId when that is set. A bundle
doctor passed could then fail init, and a plist with no bundle id failed init
with plutil's raw error. Both now use one check, which reports a missing or
mismatched bundle id as the problem.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): never move another install's verified release out of the cache

download() checked whether the cache entry was usable and, if not, moved it
aside before renaming its own unpack in. Two installs that both found no
usable entry could interleave: the second moved aside the release the first
had just put in place, and a worker starting between its two renames found
no executable. The unpack is now renamed into place first. A rename onto an
existing entry fails, and then the entry is used if it checks out, and moved
aside only if it does not.

The race has no deterministic test; a new test covers replacing a damaged
entry, the path this reorders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(desktop): say when two desktop targets share a run, and what reads empty

- The workers line said two desktop targets can run at the same time
  while telling headed runs to set workers: 1, which is what stops them.
  It now says they do, and why headed runs set workers: 1.
- The Reading row and capture()'s comment said a window is never read as
  an empty screen, but an app with no window open still is, on purpose.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(desktop-testbed): pin ai to the version every other workspace uses

The testbed pinned ai 7.0.173 while the rest of the repo pins 7.0.177, which
put a second copy of ai and its gateway and provider packages in the
lockfile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): report an open cancelled mid-launch as CANCELLED

An abort while open ran, or while the engine looked for the process it
started, came out as ACTION_MAY_HAVE_COMMITTED, where every other path of
the engine reports CANCELLED. It is now CANCELLED; the launch stays pending
as before, so the end of the attempt still looks for the app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): settle a pending launch by its last lookup and by its token

quit() dropped a pending launch, and dispose its record, once any lookup in
its wait had a whole answer. Two cases lost an app that was still starting:

- an early complete list with no match, followed by partial ones that could
  hide the app once it registered;
- a process carrying the launch's token that the app list did not show yet.

Now only the wait's last answer counts; a lookup that ran out of time is no
answer. Before giving up, quit looks for processes carrying the token and
quits them. The launch stays pending, and its record kept, unless the last
answer was whole and found nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): run launches and quits of one surface one at a time

Two overlapping app.open() calls could both quit, then both launch, writing
into the one process id and launch record the engine keeps; they even shared
the app.json.partial file. The end of the attempt then quit only one copy.
restart, closeApp, endAttempt, and dispose now wait for the launch or quit
running before them. restart's budget counts from the call, so the wait is
part of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): measure a headed click from where the window is after focus

performAt read the window's bounds, brought the window forward, and clicked
at the bounds read before. A window that moved as it came forward (onto
another space, out from under the menu bar) took the click somewhere else,
possibly another app. The window is now read again after focus-window, and
the point is checked against and measured from its bounds then.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): repair a damaged cache entry under a lock

12c8f64d0 renamed a fresh unpack into place first, which keeps a run from
moving aside a release another run just installed only when there was no
entry. Two runs that both found an entry damaged could still interleave: the
second moved aside the copy the first had just put in place. Its commit
message and comment claimed more than that.

Replacing an entry now holds a lock directory that names its owner's process
id, and checks the entry again under it. A lock whose owner is gone, or that
got no owner and is 10 s old, is taken over; one held for 60 s fails the
install with AGENT_DESKTOP_INSTALL_FAILED.

Tests repair one damaged entry from three runs at once and take over a lock a
dead process left. The interleaving itself has no deterministic test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): refuse getByPlaceholder, which macOS gives nothing to match

agent-desktop's macOS adapter reports no placeholder for a field; AppKit
folds it into the accessible name of a field with no label. A placeholder
query therefore matched nothing, and not.toBeVisible() or toHaveCount(0) on
it passed with the field on screen. locate() now refuses any expression that
uses a placeholder query with UNSUPPORTED_CAPABILITY, naming getByRole as
the way to find the field, and the docs say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(desktop): let desktop({ maxDepth }) set how deep a read goes

A read cut short at the fixed 24-level depth makes every locator on that
window read again until its timeout, since a match could sit below it. An
app nested deeper could not be tested with locators at all. maxDepth, from
1 to 255 (agent-desktop's limit), defaults to 24 and raises it; the partial
read error names the option.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): accept the verified cache copy a run published mid-repair, and keep a launch record when its process lookup fails

A run that finds no cache entry publishes without the lock, so it can fill the gap a locked repair makes between its two renames; the repair then failed with ENOTEMPTY although the cache held a verified release. The repair now accepts a usable copy there.

A failed process listing was read as an empty one, so the stale-worker sweep deleted the record that names the app a killed worker left running. The listing now reports failure apart from none found: the sweep keeps the owner and launch records (removing only the cached field text beside them), and an attempt's quit keeps its pending launch and retries.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(desktop): publish the agent-desktop cache without a lock, keeping a verified winner

The fast path renamed a fresh unpack into place without the lock that the
repair of a damaged entry held. A run that published while a repair had
moved the damaged entry aside made the repair's own rename fail with
ENOTEMPTY, though the cache now held a checked release (seen on the Node
22.22.3 and Node 26 CI jobs). The lock's stale-owner takeover could also
remove a lock another waiter had just taken.

Every run publishes a copy of the same checked release, so the lock is
gone: a rename that collides with an entry accepts it once it is checked,
a damaged entry is moved aside by one rename that only one run wins, and a
whole copy moved aside by a run that saw the entry damaged earlier goes
back. Two tests hold one run at each of those points while another installs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): show a whole cache entry without the right stamp is downloaded again

The stamp test's entry had no executable or macOS helper, so it was
downloaded again even with the stamp check removed. The entry now has
both, and a missing stamp and one for another release each force a
download.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): take a launched process as the engine's own only by its launch token

When no environment could be read, a launch took the one new copy of the
app as its own, and a cleanup after an uncertain launch could quit it.
Being new does not show this launch started it: a copy the developer
opened at the same moment is new too, and was killed in a scripted probe.

A copy is now claimed only when it carries the launch token. agent-desktop's
launch, which reports the process it started, still stands for an app
launched by bundleId. An appPath to a bundle whose environment macOS hides
(an Apple platform app, a build signed with the restrict flag) is refused
by init and doctor, which name the bundleId to use instead, so open never
starts a copy the engine could not find again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep a launch record until cleanup confirms its process is gone

A process lookup that failed read as an empty list: the sweep then
deleted a killed worker's launch record, and the next sweep left the app
running though the lookup worked again. The record held only the token,
so a process the worker had identified, whose environment cannot be read,
could not be found by a later run. A dispose whose quit failed kept the
whole state directory, with the text agent-desktop keeps of the fields.

A failed lookup is now no answer: the pending quit fails and keeps the
launch, and the sweep keeps the record. A kill waits for the process to
exit before the record goes. Once a process is shown to be the launch's,
the record also names its id and start time, so a later run quits it
without reading its environment, and never a later process given that id.
Dispose and the sweep keep only the owner file and the record, and remove
the field text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): never bring a background app forward to ask it for a window

An app launched in the background that showed no window for 2 s was
brought forward with a second open by path, bundle id, or name. That open
did not name the process the engine launched, so LaunchServices could
bring another copy forward, and it took the keyboard the guide promised
to leave alone.

The background launch now stays in the background. An app that opens no
window there fails the open with a message that it needs
desktop({ headed: true }), whose launch brings the app it starts forward.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): send a key only to the launched process's window, never by app name

agent-desktop refuses a key for a named window that is not active, which
an app in the background never is. The engine then sent the key by the
app's name once a list of the apps showed its copy alone, even a list
agent-desktop marked incomplete. The name does not pin the process, so a
copy that started between the list and the key could get it.

The fallback is gone: a refused key fails as NOT_ACTIONABLE, and nothing
is sent. Since a key then reaches an app in the background only by chance,
press joins the actions only headed offers, so a locator press without
headed fails as unsupported before it moves focus.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): never retry a press whose focus already moved

A locator press focuses the control, reads its window to check the
control kept focus, then sends the key. A stale read after the focus was
retryable, so the locator ran the whole press again and focused the
control a second time, which an app's focus handler sees. A retryable
failure after the focus is now ACTION_MAY_HAVE_COMMITTED; one before it
stays retryable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): show a select that may have reached the app stays possibly committed

Removing the delivery check from the select's ELEMENT_NOT_FOUND mapping
left every select test green. A select whose failure agent-desktop marks
delivered_unverified must stay ACTION_MAY_HAVE_COMMITTED, not "no option".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 14:34:19 +00:00

183 lines
33 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: 错误
description: 你可能遇到的所有错误码、所属类别及退出码。
"og:image": "https://e2e.com/docs/images/og/reference/errors.png?v=b184354c61"
"twitter:image": "https://e2e.com/docs/images/og/reference/errors.png?v=b184354c61"
---
运行器的每个错误都带有类别和错误码。类别决定退出码,错误码说明原因。模型不会选择其中任何一个。`e2e login`、`e2e logout` 和 `e2e models` 是例外,参阅[退出码](#exit-codes)。
```ts title="tests/upgrade.e2e.ts"
import { isAgentError, test } from 'e2e';
test('upgrade to Pro', async ({ agent }) => {
try {
await agent.act('upgrade the workspace to Pro');
} catch (error) {
if (isAgentError(error) && error.code === 'STEP_TIMEOUT') {
// the step ran out of time; the message carries the last judgment
console.error(error.category, error.details);
}
throw error;
}
});
```
## 参考
### 退出码
| 类别 | 退出码 |
| --- | ---: |
| test | 1 |
| configuration | 2 |
| infrastructure | 3 |
| internal | 4 |
| interrupted | 130 |
- 一次运行出现多种错误时,以优先级最高的退出码为准:`130 > 4 > 3 > 2 > 1 > 0`。报告保留每项独立结果。
- 如果测试清理失败(必需的视频未完成保存,或会话未关闭),则使用该清理错误的退出码,通常为 3。
- 准备测试中的断言失败属于测试失败,并会跳过依赖它的测试。准备基础设施缺失则保留其 configuration 或 infrastructure 类别。
- `internal` 类别和退出码 4 保留给违反运行器不变量的情况。目前没有第一方代码抛出该类别的错误码。
- `e2e login`、`e2e logout` 和 `e2e models` 会输出失败消息,不带错误码,并以退出码 1 退出;如果登录或选择器被取消,则以 130 退出。
| 错误码 | 说明 |
| --- | --- |
| [智能体错误码](#agent-codes) | `AgentError` 的 `code` |
| [运行器错误码](#runner-codes) | 输出和报告中的普通字符串 |
| [测试代码错误](#test-code-errors) | 从测试代码中抛出 |
### AgentError
`AgentError` 是由运行器分类的智能体失败,从 `e2e` 导出。
```ts
/** Runner-classified agent failure. */
export class AgentError extends Error {
/** Closed union, assigned by the runner, never taken from model text. */
readonly code: AgentErrorCode;
/** The error class in the table above; it sets the exit code. */
readonly category: 'test' | 'configuration' | 'infrastructure' | 'internal' | 'interrupted';
readonly retryable: boolean;
/** Structured facts: locator, expected, observed, match count, wait time. */
readonly details: ErrorDetails | undefined;
/** Sanitized, bounded prose; the same value as `message`. */
readonly explanation: string;
/** Artifact path, present only when evidence was captured and permitted. */
readonly screenshot?: string;
/** True when this failure reports a blocked step, not a product failure. */
readonly blocked: boolean;
}
```
<Note>
测试文件在各自的模块域中加载,因此 `instanceof AgentError` 可能为假。请使用 `e2e` 中的 `isAgentError`,并根据 `code` 分支处理,如本页开头的示例所示。
</Note>
#### 智能体错误码
封闭联合类型 `AgentErrorCode` 的成员。`blocked:` 表示受阻判定所报告的障碍类别。
| 错误码 | 触发条件 | 类别 | 退出码 |
| --- | --- | --- | ---: |
| `AUTH_CREDENTIAL_UNAVAILABLE` | `Secret` 或 `credentials.user()` 指定了 `config.credentials` 中不存在的凭据,调用发生在活动运行器之外,或密码提供方未返回至少 6 个字符(码点)的字符串 | configuration | 2 |
| `AUTH_CREDENTIAL_INVALID` | 应用拒绝了已配置的凭据(blocked: credentials) | configuration | 2 |
| `SECRET_UNAVAILABLE` | 运行期间,`Secret` 或 `secrets.get()` 指定了 `config.secrets` 中不存在的机密值,机密值提供方未返回至少 6 个字符(码点)的字符串,或引擎解析了未在其 `secrets` 中声明的机密值。也包括 `host.secret(name)`(`@e2e-dev/core`)指定了未传给 `launch` 的机密值 | configuration | 2 |
| `ENVIRONMENT_UNAVAILABLE` | 被测环境中应用之外的部分宕机或无法访问(blocked: environment) | infrastructure | 3 |
| `SEED_DATA_MISSING` | 步骤依赖的数据在环境中不存在(blocked: seed_data) | configuration | 2 |
| `TEST_SETUP_FAILED` | 未能准备好产品之外的测试前提条件(blocked: test_setup)。也包括违反约定的 `test.extend()` 测试夹具:未调用 `use()` 就返回,或调用了两次 | configuration | 2 |
| `AUTOMATION_UNSUPPORTED` | 步骤需要当前工具集无法执行的交互,例如在设备上右键点击(blocked: automation) | test | 1 |
| `MODEL_UNAVAILABLE` | 未配置模型:内置智能体的 `agents.<name>.model` 不含 AI SDK 模型实例(消息会指出选中的智能体),或 GitHub Copilot 未向该账户提供配置的模型(`model_not_supported`;消息会指出模型)。作为运行级别错误记录一次,然后停止运行。在测试运行中,首次获取 `agent` 测试夹具时会发现模型缺失,首次调用时会发现模型未提供。`e2e explore` 使用内置智能体,因此会在启动任何内容之前检查模型是否缺失,包括自定义执行器的条目。未配置模型的自定义执行器不接受此检查:其 `act` 和 `assert` 步骤会运行,而 `waitFor` 或 `extract` 在首次调用时会因该错误码失败。不会逐出任何[录制](/cache)。 | configuration | 2 |
| `POLICY_DENIED` | 安全策略拒绝了操作:禁止的目的地、禁止的填入、没有像素时使用 `vision: 'only'`,或读取安全字段。也包括 `app.open` 链接使用了被拒绝的协议方案。[策略拒绝](/reference/security#policy-denials)列出了所有情况。未知工具,或对声明了字段的内置工具传入未声明的字段,会作为调用结果返回给模型,绝不会作为此错误码返回 | configuration | 2 |
| `APP_UNREACHABLE` | 无法访问应用 URL,或应用命令退出或超过 `startupTimeout`。在 `e2e run` 期间,就绪后的退出只会影响仍有未完成工作的依赖测试目标:中断其活动测试,并跳过排队的测试。诊断信息请参阅[应用命令](/reference/config#command)。在智能体下,还包括没有更具体错误码的任何引擎故障。在设备上,消息可能指出繁忙或卡死的 iOS 自动化运行器及其恢复方法。参阅[移动端](/mobile#troubleshooting)。 | infrastructure | 3 |
| `APP_ALREADY_RUNNING` | 在生成测试目标的 `app.command` 进程之前,`readyUrl` 已有响应,且 `reuseExisting` 未生效。停止该进程,或在本地设置 `reuseExisting: true` | infrastructure | 3 |
| `MODEL_PROVIDER_FAILED` | 适配器完成传输重试后,提供方仍出现传输失败(网络错误、5xx、速率限制或 120 秒内无响应):每次模型调用最多重试 5 次,遵循 `retry-after`,且不超过步骤剩余超时时间。停滞的请求会在 120 秒时中止并重新发送;`agent.act` 步骤的 `--debug` 交互记录会注明这一点。120 秒覆盖整个请求,因此单次回答需要更久的模型也会在此失败。如果提供方的包无法读取错误响应体,则显示 HTTP 状态和响应体,机密值会脱敏,内容截断到 1 KB。也包括提供方以 `error` 结束原因终止的调用,无论附带什么文本,以及 1 分钟内未得到回答的 `e2e doctor --check-model` 调用。不会逐出任何[录制](/cache) | infrastructure | 3 |
| `CANCELLED` | 运行器在没有进程信号的情况下取消了操作:`e2e mcp` 的 `open_session` 被客户端取消、连接关闭或服务器关闭打断,并已停止它启动的内容。在 `@e2e-dev/core` 中,也包括被 `signal` 中止的操作,或对已关闭会话的操作 | infrastructure | 3 |
| `MODEL_OUTPUT_INVALID` | 修复预算耗尽后,结构化输出仍未通过校验。在[决策模型](/decision-models)下:回答没有有效的选项分布、选择了请求未提供的选项,或提供方拒绝了问题。决策不会进行修复 | test | 1 |
| `APP_NOT_OPEN` | 操作需要已打开的应用:尚未运行 `app.open()`,或引擎报告状态无效 | test | 1 |
| `LOCATOR_NOT_FOUND` | 截止时间内没有匹配节点,或智能体操作引用了已不可用的节点。对于经过过滤的定位器,如果失败后的诊断过程能读取过滤链,消息还可能列出每个过滤步骤留下的候选项数量,数量在失败后统计 | test | 1 |
| `LOCATOR_AMBIGUOUS` | 单节点操作匹配了多个节点。立即失败,不进行轮询。对于经过过滤的定位器,如果失败后的诊断过程能读取过滤链,消息可能列出每个过滤步骤留下的候选项数量,数量在失败后统计 | test | 1 |
| `ACTION_FAILED` | 可操作性检查失败、操作超时,或操作可能已经生效。也包括对没有值的节点调用 `inputValue()`,以及对没有选中状态的节点调用 `isChecked()` | test | 1 |
| `STEP_BUDGET_EXHAUSTED` | 得出结论前已耗尽模型调用或操作步骤预算 | test | 1 |
| `STEP_TIMEOUT` | 调用截止时间已到,包括在距离截止时间一个轮询间隔内超时的操作。如果存在最后一次判定,则携带该判定;如果判定无法得出结论,还会附带[视觉提示](/reference/agent#agent-assert) | test | 1 |
| `CONTEXT_OVERFLOW` | 请求超过了模型的上下文窗口。`act` 会缩短历史记录,如果这使请求变小,就重试一次;判定会立即失败。减小 `agents.<name>.maxObservationBytes`,或将指令拆分为更短的步骤。报告为 blocked: automation | test | 1 |
| `MODEL_REFUSED` | 模型拒绝了请求(结束原因为 `content-filter`),且未返回可用回答。改写指令或使用其他模型。报告为 blocked: automation | test | 1 |
| `ASSERTION_FAILED` | `agent.assert` 判定为假,或定位器、`browser` 或值匹配器失败 | test | 1 |
| `ASSERTION_INCONCLUSIVE` | `agent.assert` 无法判定:屏幕没有显示足以判断真假的信息(相关部分不在屏幕上、仍在加载,或无法读取)。如果模型回答屏幕未显示所需数据,`agent.extract` 会抛出此错误,而不是返回占位符。这始终算作失败,绝不会通过;说明会指出缺失的内容。关闭 `vision`、仅根据语义树判定时,消息可能添加[视觉提示](/reference/agent#agent-assert) | test | 1 |
| `AUTHENTICATION_FAILED` | 执行器判定应用内登录失败:这是产品判定。`AUTH_CREDENTIAL_INVALID` 是对应的受阻情况,表示应用拒绝了已配置的凭据 | test | 1 |
| `STEP_NO_CONCLUSION` | 执行器耗尽所有轮次,但未调用 `complete_step`。步骤失败,并附带智能体最后的摘要 | test | 1 |
| `REPLAY_STALE` | 启用 `cache.strict` 或 `--strict-cache` 时,步骤的录制存在但已无法回放,因此步骤会直接失败,不调用模型,也不移交给智能体。`step.cache.reason` 为 `invalid-entry`、`wrong-context`、`target-not-found`、`target-ambiguous`、`viewport-changed`、`action-failed`、`action-uncertain`、`end-mismatch` 之一;或者为 `no-entry`,此时缓存目录(不是自定义 `cache.store`)在另一个键下保存着该步骤的录制,消息会指出该键。不会重试:每次尝试都会回放同一份录制。修复时,在不带该标志的读写运行中重新录制,如果配置设置了 `cache.strict`,也要关闭它,然后提交更改后的条目。消息会指出启用严格模式的设置,以及配置的缓存目录(或 `cache.store`) | configuration | 2 |
### 运行器错误码
这些错误码作为普通字符串出现在终端输出和报告中。
| 错误码 | 触发条件 | 类别 | 退出码 |
| --- | --- | --- | ---: |
| `CONFIG_NOT_FOUND` | `--config <path>` 指定的文件不存在,或从工作目录到仓库根目录之间都不存在 `e2e.config.ts`、`e2e.config.mts`、`e2e.config.js` 或 `e2e.config.mjs` | configuration | 2 |
| `CONFIG_AMBIGUOUS` | 同一目录同时存在 `e2e.config.ts` 和 `e2e.config.mts`,或在没有 TypeScript 配置的目录中同时存在 `e2e.config.js` 和 `e2e.config.mjs` | configuration | 2 |
| `CONFIG_LOAD_FAILED` | 配置模块导入失败:包已声明但未安装、包未声明、子路径错误、导出已移除,或求值期间抛出其他异常。消息会指出修复方法。求值期间抛出的配置错误保留自身错误码:配置调用的工厂拒绝选项,或 `secrets.get()` 句柄被转为字符串时,错误码为 `INVALID_CONFIG` | configuration | 2 |
| `INVALID_CONFIG` | 配置模块调用的工厂(`web()`、`mobile()`、`defineEngine()`、`decisionExecutor()`、`decisionFilter()`)拒绝了选项,附带工厂自己的消息。也包括:未知键、超出范围的值、无效枚举或缺少 `targets`;测试目标使用了 `{ name, platform, engine, app, trace, video }` 之外的键;测试目标的 `app` 键未知或格式错误;没有引擎的测试目标设置了 `app`;`web()` 测试目标缺少 `app.url` 或包含设备字段;`mobile()` 测试目标缺少 `app.bundleId` 或 `app.appPath`、包含 `app.url`(尚不支持)、在引擎无法打开链接的测试目标上设置了 `app.linkBase`,或该值不是绝对 URL 或协议方案、含查询或片段、指定了被拒绝的协议方案、在 `bundleId` 中包含链接,或包含未知的权限名称或状态(消息会指出最接近的名称);`web()` 或 `mobile()` 选项中的未知键,包括 `web({ connect })` 和 `web({ basicAuth })`(消息会指出最接近的键);`trace` 或 `video` 不是录制模式;已移除的产物类型列表(`artifacts: [...]` 或 `artifacts.kinds`)或 `artifacts.trace` 块(消息会指出它们对应的 `trace` 模式);已移除的 `artifacts.video` 块或 `video` 产物类型(消息会指出 `video` 选项);已移除的 `specVersion` 键;引擎选项中的 `secrets.get()` 没有对应的 `secrets` 条目(凭据密码不算);配置求值时将 `secrets.get()` 引用转为字符串(模板字面量、`String()`),或在需要字符串的位置传入它(`app.command` 的 `args` 条目或 `env` 值;只有声明了机密值的引擎选项才接受它);`app.command` 的 `args` 条目或 `env` 值不是字符串(值为 `undefined` 的 `env` 条目会被丢弃);`app.command` 中的未知键(消息会指出最接近的键);`engine` 不是 `defineEngine` 句柄;`json` 报告器与 `list` 组合,或用于带 `--step` 的运行;重复或格式错误的测试目标名称;机密值或凭据密码少于 6 个字符(码点);凭据不是 `{ username, password }`、`username` 不是字符串(只有 `password` 可以是函数),或配置与 `E2E_USER_<NAME>_USERNAME` 中都没有用户名;两个凭据或两个机密值的名称映射到同一个 `E2E_USER_*` 或 `E2E_SECRET_*` 覆盖变量(`api-key` 和 `api_key`);过大的 `agents.<name>.context`;`expect.poll` 的 `timeout` 或 `interval` 不是有限的毫秒数,或在测试外使用值为 0 的 `timeout`;`tests` 值不是 glob 或 glob 列表,或 `tests` 列表仅包含 `!` 排除项;已移除的顶层 `limits` 键;agents 条目为裸 `StepExecutor`(消息会指出 `{ executor }`)或模型实例(消息会指出 `{ model }`);未知智能体键(消息会指出最接近的键);已移除的智能体键 `timeout` 和 `maxTurns`(消息会指出 `judgmentTimeout` 和 `maxModelCalls`);在 `executor` 旁设置 `system` 或 `tools`;`tools` 条目不是由 `defineTool` 构建,或占用了内置工具名称(语法动词、`complete_step`、`locate`、`run_code`、`test_lines`、`start_recording`、`stop_recording` 或 `report_finding`);`createToolLoopExecutor({ maxTurns })`;应用的 `app.url` 请求空闲端口时设置 `reuseExisting`;端口为 0 的 `app.url` 没有提供服务的 `app.command`;`filters` 值不是 `{ name, filter }` 列表(对于 `decisionFilter` 这样的裸函数,消息会提示调用它);或过滤器的 `name` 违反测试目标名称规则、超过 256 个字符,或重复使用 | configuration | 2 |
| `CONFIG_NOT_DETERMINISTIC` | 工作进程重新解析配置模块时,得到的摘要与运行器不同 | configuration | 2 |
| `APP_URL_REQUIRED` | 在未声明 `app.url` 的测试目标上导航或使用相对 URL(在没有 `app.linkBase` 的设备测试目标上调用 `app.open(path)`),或 `app.command` 没有可供轮询的 `app.url` 或 `app.readyUrl` | configuration | 2 |
| `INVALID_APP_URL` | 基础 URL 无法解析,或包含用户信息、查询、片段、非 HTTP 协议方案,或在非回环主机上使用明文 HTTP;在非字面回环地址(`127.0.0.1`、`[::1]`)的主机上使用端口 0;或运行无法在回环地址上绑定空闲端口 | configuration | 2 |
| `INVALID_GLOB` | 空模式;除 `tests` 排除项开头的一个 `!` 外,首个路径段仍以 `!` 开头(`!!tests/**`、`./!tests/**`);单独的 `!`;花括号、字符类或扩展 glob;反斜杠分隔符;绝对路径或 `..` 段;结尾的 `/` 或 `.`;不含通配符却指向目录的 `tests` 条目(消息会指出应填写的 glob);仅指向项目根目录的模式;或不独占整个路径段的 `**` | configuration | 2 |
| `UNKNOWN_TARGET` | `--target`、`open_session.target` 或 `openHost`(`e2e/runner`)指定了未配置的测试目标 | configuration | 2 |
| `TARGET_REQUIRED` | `e2e mcp` 或 `openHost`(`e2e/runner`):配置声明了多个测试目标,但没有指定使用哪一个 | configuration | 2 |
| `NO_SESSION` | `e2e mcp`:在 `open_session` 之前或会话结束后调用 `call` 或 `tools`(消息会指出原因),或 `call`、`tools`、`close_session` 指定的 `session` ID 未打开或正在关闭 | configuration | 2 |
| `SESSION_REQUIRED` | `e2e mcp`:多个会话打开时,调用 `call`、`tools` 或 `close_session` 未提供 `session`。消息会列出这些会话 | configuration | 2 |
| `ENGINE_IN_USE` | `e2e mcp`:对某个测试目标调用 `open_session`,但其引擎实例正由另一个打开的会话操作,因为配置从所有会话共享的包中获取该实例。请在配置中,或在配置通过路径导入的文件中创建引擎 | configuration | 2 |
| `ENGINE_NOT_INSTALLED` | `e2e mcp`:`open_session {engine}` 指定的包未安装在项目中、e2e 旁边或 `~/.e2e/engines` 中。消息会给出安装命令 | configuration | 2 |
| `CONFIG_IN_USE` | `e2e mcp`:`open_session` 使用的配置与已打开会话的配置不同,或在通过 `engine` 打开的会话仍打开时使用配置。凭据和机密值在整个进程范围内解析,因此请使用同一配置打开,或先关闭这些会话 | configuration | 2 |
| `SESSION_OPEN` | `e2e mcp`:调用 `open_session` 时,每个会话槽位(`--max-sessions`,默认为 4)都已有打开、正在打开或正在关闭的会话,或服务器正在关闭。请先关闭一个会话 | configuration | 2 |
| `UNKNOWN_TOPIC` | `e2e mcp`:`e2e://guide/{topic}` 资源指定了技能中不存在的主题。消息会列出可用主题 | configuration | 2 |
| `UNKNOWN_TOOL` | `e2e mcp`:`call` 或 `tools` 指定了会话目录中不存在的工具。消息会列出目录。引擎未声明的操作动词则使用 `UNSUPPORTED_CAPABILITY` | configuration | 2 |
| `TEST_AMBIGUOUS` | `e2e mcp`:`open_session` 的 `test` 在会话的测试目标上选中了多个测试。消息会以 `file:line` 列出它们 | configuration | 2 |
| `SESSION_TEST_UNSUPPORTED` | `e2e mcp`:`open_session` 的 `test` 选中了会话无法单独运行的测试:串行组成员、从准备测试的 `session` 开始的测试,或使用多个智能体运行的测试。请使用 `e2e run` 运行它 | configuration | 2 |
| `UNSUPPORTED_ARTIFACT` | 测试目标或将在该目标上运行的测试设置的 [`video` 模式](/reference/config#recording)要求在某次尝试中录制,但该目标的引擎无法录制视频。消息会指出测试目标;如果模式来自测试,也会指出测试。配置根级别或 `--video` 的模式绝不会触发此错误:它们只适用于能录制的测试目标,并以提示列出其余目标 | configuration | 2 |
| `UNSUPPORTED_CAPABILITY` | 测试目标的引擎未声明某个测试夹具、操作或层级:没有测试或钩子在运行时工作进程测试夹具使用了内置测试夹具(测试目标没有的测试夹具为 `COLLECTION_ERROR`)、没有 `locate` 时使用 `screen`、没有 `state` 时恢复状态、没有 `artifacts` 时截图、在持久浏览器上下文上调用 `app.clearState()`(消息会指出模式)、执行器未声明 `vision: true` 时使用 `agent.assert` 的 `vision`,或测试视频正在录制时调用 `app.startRecording()` | configuration | 2 |
| `NO_TESTS` | 可运行的普通测试与测试目标组合数为零。消息会指出原因:没有文件匹配 `tests` glob(会列出相似文件)、位置参数没有匹配项(会指出排除位置参数所指文件的 `!` 条目)、文件未注册测试,或过滤条件排除了全部测试。使用 `--pass-with-no-tests` 可抑制此错误。如果[测试过滤器](/filters)排除了所有可运行测试,运行会通过(退出码 0)。也适用于 `e2e mcp` 的 `open_session` 中 `test` 未选中任何可运行测试的情况。 | configuration | 2 |
| `RUNNER_BUSY` | 测试套件与另一个测试套件、正在打开或已打开的宿主,或活动尝试重叠;或测试套件运行期间打开宿主;或在没有终端时启动 `e2e run --step`,而该目录中已有另一个运行受 `e2e run --step` 控制;或在没有终端的运行中,测试到达 `screen.pause()` 时,该目录中的另一个运行已以这种方式受控制;或某次运行在取得目录控制权时被终止并遗留了锁(消息会指出要删除的文件)。重试前等待测试套件结束并关闭现有宿主;使用 `e2e run --step stop` 结束单步运行,或删除消息指定的锁文件。 | configuration | 2 |
| `RUNNER_NOT_INSTALLED` | 在未安装 `e2e` 的位置调用了 `@e2e-dev/web`、`@e2e-dev/mobile` 或 `@e2e-dev/desktop` 中的 `test`、`describe` 或钩子,例如仅基于 `@e2e-dev/core` 的程序。同一入口导出的引擎工厂仍然可用。要编写测试,请安装 `e2e` | configuration | 2 |
| `NO_LAST_RUN` | `--last-failed` 在运行写入报告的位置未找到 `report.json`,或该处文件不是 `report-1` 文档。请先不带该标志运行一次。 | configuration | 2 |
| `INVALID_CHANGED_SINCE` | `--changed-since`(`changedSince`)不是字符串、为空或以 `-` 开头。或者,当运行调用测试过滤器或 `e2e explore` 探索变更时,该值在检出的仓库中未指向任何提交,或与 HEAD 没有共同历史记录(浅克隆时消息会提示获取更多历史,否则会说明历史不相关);或项目不在 git 仓库中、未安装 git,或 git 未在 30 秒内响应 | configuration | 2 |
| `ONLY_IN_CI` | CI 运行中出现了聚焦测试 | configuration | 2 |
| `COLLECTION_ERROR` | 在收集阶段之外注册;标题无效;测试体不是函数;`describe` 的函数体为异步;嵌套串行组;串行组内使用了禁止的选项;`describe` 内包含准备测试;会话名称无效;测试选项格式错误,例如 `tags` 不是不重复名称的列表;测试或 `describe` 使用了调用不接受的选项键(消息会指出最接近的键);在没有位置参数的运行中,或位置参数选中了该文件时,测试文件导入失败;所选测试使用的会话,或 `e2e explore --session` 指定的会话,没有任何已收集的准备测试生成它(消息会列出声明的会话);使用会话的测试目标,其引擎没有用于保存会话的 `state` 能力;位置参数路径在项目根目录之外;或违反了测试夹具规则,报告时带有代码所在的文件和行号:测试体、钩子或 `test.extend()` 测试夹具函数没有解构第一个参数、在其中使用剩余属性或是绑定函数,在某个测试目标上运行的测试用到了该测试目标没有的测试夹具名称,`beforeAll`、`afterAll` 或工作进程测试夹具列出了测试作用域的测试夹具,测试夹具互相列出形成循环,或 `test.extend()` 测试夹具的 `scope` 或 `auto` 与它所扩展的测试夹具不同 | configuration | 2 |
| `SESSION_MISMATCH` | 已存储会话与当前运行、测试目标、引擎、平台或应用标识不匹配。也包括将 `@e2e-dev/core` 的 `SessionState` 传给其他引擎、平台或应用的宿主 | configuration | 2 |
| `SESSION_EXPIRED` | 已存储会话或 `@e2e-dev/core` 的 `SessionState` 在恢复或导入时已过期(configuration,退出码 2),或准备测试保存的状态,其过期时间不晚于创建时间(test,退出码 1) | configuration 或 test | 2 或 1 |
| `SESSION_INVALID` | 已存储会话未通过身份验证,遭到篡改或损坏。也包括 `SessionState.import`(`@e2e-dev/core`)接收到的字节不是 `session-state-1` 文档,或无法用该密钥通过身份验证:密钥不同,或某个字节已更改 | configuration | 2 |
| `SESSION_UNAVAILABLE` | 测试要求的会话没有任何所选准备测试生成 | configuration | 2 |
| `SESSION_CONTRACT` | 准备测试保存同一会话两次、保存了未声明的名称,或结束时未保存某个已声明的会话 | test | 1 |
| `TEST_TIMEOUT` | 尝试超过了解析后的测试 `timeout`。测试体不会被停止:它当前执行的测试执行框架操作会被取消,其测试夹具随尝试结束而失效,因此无法影响下一个测试。如果测试阻塞事件循环,在超时后再经过 `cleanupTimeout`(至少 5 秒),其工作进程会被终止。参阅[钩子](/reference/test#hooks) | test | 1 |
| `PAUSE_UNAVAILABLE` | 测试在没有人能恢复它的运行中调用了 `screen.pause()`:设置了 `CI` 的运行。测试会在调用所在行失败。请删除该调用,或在不设置 `CI` 的情况下使用 `e2e run` 运行测试 | test | 1 |
| `STEP_NOT_AWAITED` | 测试体已结束,但它启动的步骤仍在运行:步骤调用缺少 `await`。该步骤会在调用所在行失败并被取消,消息会指出启动该步骤的代码:测试体、`beforeEach` 钩子或测试夹具的准备。如果测试体正常返回,尝试会以此错误码失败;如果测试体抛出异常,尝试保留测试体的错误,并将此错误记录在 `secondaryErrors` 下。如果测试体、`afterEach` 钩子或测试夹具清理已返回,而 `expect.poll` 匹配器仍在运行,该阶段也会以相同方式在调用行失败,匹配器会被取消。由 `beforeAll` 或 `afterAll` 钩子遗留的匹配器或仍在运行的步骤会使钩子因 `HOOK_FAILED` 失败 | test | 1 |
| `UNHANDLED_REJECTION` | 没有测试运行时发生 Promise 拒绝。Node 无法确定哪个测试创建了 Promise,因此未处理的拒绝归于它出现时正在运行的测试。如果发生在测试之间,则成为此运行错误,并将该工作进程中最后完成的测试列为可能来源。如果工作进程中尚无测试完成,则会终止工作进程:拒绝成为运行错误,即将执行的测试因 `WORKER_CRASH` 失败。遗留该 Promise 的测试体会像超过 `TEST_TIMEOUT` 的测试体一样继续运行。在 `e2e mcp` 中,会话运行的测试在其代码执行期间也按相同方式归责;测试体结束后,拒绝使用此错误码,由 `close_session` 报告,或在会话关闭后作为警告写入 stderr | test | 1 |
| `HOOK_FAILED` | `beforeAll` 或 `afterAll` 抛出异常。跳过测试套件中的测试。 | test | 1 |
| `UNEXPECTED_PASS` | 标记为 [`test.fail`](/reference/test#test-fail) 的测试通过了。像其他测试失败一样重试。原因修复后,请移除该标记 | test | 1 |
| `RUN_TIMEOUT` | 运行耗尽了 [`maxDuration`](/reference/config#maxduration) 或 `--max-duration`。正在运行的测试以 `interrupted` 结束,其余测试以原因 `time-limit` 跳过 | test | 1 |
| `LAUNCH_TIMEOUT` | 引擎初始化或尝试启动超过 `config.launchTimeout` | infrastructure | 3 |
| `CLEANUP_TIMEOUT` | 引擎结束尝试超过 `config.cleanupTimeout`,尝试结束时引擎为测试运行的路由或对话框处理函数仍在运行,或测试用 `launch()` 打开的宿主或会话未在该时间内关闭 | infrastructure | 3 |
| `BROWSER_INSTALL_FAILED` | 浏览器准备失败 | infrastructure | 3 |
| `AGENT_DESKTOP_INSTALL_FAILED` | `@e2e-dev/desktop` 无法下载固定版本的 agent-desktop、归档未通过 SHA-256 校验,或 worker 在没有 agent-desktop 的情况下启动(例如跳过了引擎 prepare 步骤的宿主) | infrastructure | 3 |
| `WORKER_INIT_FAILED` | 工作进程始终未就绪 | infrastructure | 3 |
| `WORKER_EXIT` | 工作进程运行文件时意外退出。正在执行的测试因 `WORKER_CRASH` 失败,该文件中的其他测试被跳过。退出前已完成的尝试保留在报告中,包括重试之前的尝试和串行组中已完成的成员。崩溃记录为它们之后的一次尝试;如果发生在最后一次尝试之后(`afterAll` 中),则记录在最后一次尝试上。如果未处理的拒绝导致工作进程结束(参阅 `UNHANDLED_REJECTION`),运行错误是该拒绝,而非此错误 | infrastructure | 3 |
| `WORKER_CRASH` | 工作进程在某个特定测试期间退出 | infrastructure | 3 |
| `WORKER_ENTRY_MISSING` | 无法解析工作进程入口模块。属于打包故障。 | infrastructure | 3 |
| `NODE_UNSUPPORTED` | 运行时无法运行 e2e:Node.js 不在 `^22.22.3 \|\| >=24.8.0` 范围内、Bun 低于 1.4.3,或使用 Deno。CLI 在启动前检查这一点,输出相同消息并以退出码 2 退出。对于不通过 CLI 使用 e2e 运行器的宿主,加载器会在加载配置或测试文件之前再次检查。在 Bun 上,`e2e/runner` 中的 `run`、`list`、`explore` 和 `openHost` 也会抛出此错误:它们需要 Node.js | infrastructure | 3 |
| `TYPESCRIPT_COMPILER_UNAVAILABLE` | 无法加载用于编译 e2e TypeScript 的 oxc;消息会给出原因。最常见的原因是未安装当前平台的原生绑定(`@oxc-transform/binding-<platform>-<arch>`、`@oxc-parser/binding-<platform>-<arch>`)。使用 `--omit=optional` 时,或 `package-lock.json` 在其他平台上生成时(npm/cli#4828),npm 会漏装它们。不带 `--omit=optional` 重新安装,或删除 `package-lock.json` 和 `node_modules` 后运行 `npm install` | infrastructure | 3 |
| `IMAGE_CODEC_UNAVAILABLE` | 无法加载用于读写截图 PNG 的 `@napi-rs/image`;消息会给出原因。它在首次读取或写入截图时加载,因此不截图的运行无需它。最常见的原因是未安装当前平台的原生绑定(`@napi-rs/image-<platform>-<arch>*`)。使用 `--omit=optional` 时,或 `package-lock.json` 在其他平台上生成时(npm/cli#4828),npm 会漏装它。不带 `--omit=optional` 重新安装,或删除 `package-lock.json` 和 `node_modules` 后运行 `npm install`。该包未发布 ppc64、s390x 或 riscv64 上 Linux 的绑定,因此这些平台无法使用 `toHaveScreenshot`,也无法处理运行器需要缩放的智能体截图(任意一边超过 768 px) | infrastructure | 3 |
| `ENGINE_FAILURE` | 没有更具体映射的任何引擎故障 | infrastructure | 3 |
| `WORKER_PROTOCOL` | 工作进程报告了错误的执行单元、尝试与活动尝试重叠、`openHost` 尝试获取另一个宿主持有的引擎实例,或 `host.openSession` 尝试复用已关闭的宿主,或与正在打开、活动或正在关闭的会话重叠。在 `@e2e-dev/core` 中,也包括对另一个宿主持有的引擎实例调用 `launch`,或对已关闭的宿主调用 `host.newSession`,或在已有打开会话时调用它 | infrastructure | 3 |
| `SESSION_KEY_INVALID` | 工作进程收到的会话密钥不是 32 字节。属于打包或 IPC 故障。 | infrastructure | 3 |
| `REPORT_WRITE_FAILED` | 无法写入 `report.json` 或 `ai-trace.json`。记录为运行错误;内存中的结果仍然完整。如果无法写入 `junit.xml`,则改为在 `junit` 报告器的 stderr 上输出一行消息 | infrastructure | 3 |
| `EVALUATE_FAILED` | `browser.evaluate` 在页面中抛出异常,或页面删除或替换了引擎页内代码所需的 JavaScript 内置对象(例如 `Map`),导致后续求值和定位器失败(`@e2e-dev/web`) | test | 1 |
| `INTERRUPTED` | 用户或 CI 信号中止了运行。被 `--max-failures` 或时间限制提前结束的测试也使用此错误码,消息会指出该限制;这种运行的退出码为 1,而非 130 | interrupted | 130 |
#### 测试代码错误
| 错误码 | 触发条件 | 类别 | 退出码 |
| --- | --- | --- | ---: |
| `INVALID_ARGUMENT` | 测试代码中的参数校验拒绝了某个参数 | test | 1 |
| `INVALID_LOCATOR` | 测试代码中的参数校验拒绝了定位器的参数 | test | 1 |
| `ERROR` | 测试代码抛出了无法归入其他错误码的值 | test | 1 |