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
45 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` が false になることがあります。このページ冒頭の例のように、`e2e` の `isAgentError` を使い、`code` で分岐してください。
</Note>
#### エージェントのコード
拡張できない `AgentErrorCode` ユニオンのメンバーです。`blocked:` は、実行を妨げる要因として 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()` を呼ばずに戻った、または 2 回呼んだ場合です | configuration | 2 |
| `AUTOMATION_UNSUPPORTED` | デバイス上の右クリックなど、利用可能なツールでは実行できない操作がステップに必要な場合(blocked: automation) | test | 1 |
| `MODEL_UNAVAILABLE` | モデルが設定されていない場合。組み込みエージェントの `agents.<name>.model` に AI SDK のモデルインスタンスがない場合(メッセージに選択されたエージェントを示します)、または GitHub Copilot がこのアカウントに設定済みモデルを提供していない場合(`model_not_supported`。メッセージにモデルを示します)です。実行全体のエラーとして 1 回記録し、実行を停止します。テスト実行では、モデルの未設定は `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 秒はリクエスト全体に適用されるため、1 回の回答にそれ以上かかるモデルもここで失敗します。プロバイダーパッケージが読み取れないエラーボディは、HTTP ステータスとボディを表示します。シークレットは秘匿し、1 KB で切り詰めます。プロバイダーが `error` の終了理由で終えた呼び出しも、付随するテキストにかかわらず該当します。`e2e doctor --check-model` の呼び出しが 1 分以内に応答しない場合も該当します。[記録](/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` | 呼び出しの期限が切れた場合。その期限からポーリング 1 回分以内でタイムアウトした操作も含みます。最後の判定があれば保持し、その判定が不確定だった場合は[画像入力に関するヒント](/reference/agent#agent-assert)も含めます | test | 1 |
| `CONTEXT_OVERFLOW` | リクエストがモデルのコンテキストウィンドウを超えた場合。`act` は履歴を短くし、それによってリクエストが小さくなれば 1 回リトライします。判定は直ちに失敗します。`agents.<name>.maxObservationBytes` を小さくするか、指示を短いステップに分割してください。blocked: automation として報告します | test | 1 |
| `MODEL_REFUSED` | モデルがリクエストを拒否し(終了理由 `content-filter`)、利用できる回答を返さなかった場合。指示を言い換えるか、別のモデルを使ってください。blocked: automation として報告します | test | 1 |
| `ASSERTION_FAILED` | `agent.assert` が false と判定した場合、またはロケーター、`browser`、値のマッチャーが失敗した場合 | test | 1 |
| `ASSERTION_INCONCLUSIVE` | `agent.assert` が判定できなかった場合。画面に判断に必要な情報が足りないときです(該当箇所が画面にない、読み込み中、読み取れないなど)。`agent.extract` でも、モデルが要求されたデータは画面にないと回答した場合、仮の値を返さずこのエラーになります。成功にはならず、必ず失敗です。説明には不足していた情報を示します。`vision` を無効にしてツリーだけで判定した場合、メッセージに[画像入力に関するヒント](/reference/agent#agent-assert)を追加することがあります | test | 1 |
| `AUTHENTICATION_FAILED` | エグゼキューターがアプリ内のサインイン失敗と結論づけた場合。プロダクトについての判定です。設定済みの認証情報をアプリが拒否した場合の blocked 判定は `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` のいずれかです。また、キャッシュディレクトリ(独自の `cache.store` は対象外)に別のキーでそのステップの記録がある場合は `no-entry` となり、メッセージにそのキーを示します。毎回同じ記録をリプレイするため、リトライしません。修正するには、このフラグを外した読み書き可能な実行で記録し直し、変更されたエントリーをコミットしてください。設定で `cache.strict` を有効にしていた場合は、そちらも無効にします。メッセージには 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`。`app.url` がない、またはデバイス用フィールドを持つ `web()` ターゲット。`app.bundleId` と `app.appPath` のどちらもない `mobile()` ターゲット、`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` の未知のキー(最も近いキーを示します)。`defineEngine` のハンドルでない `engine`。`json` レポーターと `list` の併用、または `--step` での使用。重複した、または不正な形式のターゲット名。6 文字(コードポイント)未満のシークレットや認証情報のパスワード。`{ username, password }` 形式でない認証情報、文字列でない `username`(関数にできるのは `password` だけ)、設定にも `E2E_USER_<NAME>_USERNAME` にもユーザー名がない認証情報。名前が同じ `E2E_USER_*` または `E2E_SECRET_*` 上書き変数に変換される 2 つの認証情報または 2 つのシークレット(`api-key` と `api_key` など)。大きすぎる `agents.<name>.context`。有限のミリ秒数でない `expect.poll` の `timeout` または `interval`、テスト外での `timeout` が 0。glob または glob のリストでない `tests`、`!` による除外だけの `tests` リスト。削除済みのトップレベル `limits` キー。`StepExecutor` を直接指定した agents エントリー(`{ executor }` を示します)やモデルインスタンスを直接指定したもの(`{ model }` を示します)。エージェントの未知のキー(最も近いキーを示します)。削除済みのエージェントキー `timeout` と `maxTurns`(`judgmentTimeout` と `maxModelCalls` を示します)。`executor` と並べた `system` または `tools`。`defineTool` で作成していない `tools` エントリー、組み込みツール名を使うもの(文法の動詞、`complete_step`、`locate`、`run_code`、`test_lines`、`start_recording`、`stop_recording`、`report_finding`)。`createToolLoopExecutor({ maxTurns })`。`app.url` で空きポートを要求するアプリの `reuseExisting`。サーバーを起動する `app.command` のないポート 0 の `app.url`。`{ name, filter }` のリストでない `filters`(`decisionFilter` のような関数を直接渡した場合は呼び出すよう示します)。ターゲット名の規則に違反する、256 文字を超える、または重複したフィルターの `name` | configuration | 2 |
| `CONFIG_NOT_DETERMINISTIC` | ワーカーが設定モジュールを再解決した結果、ランナーと異なるダイジェストを得た場合 | configuration | 2 |
| `APP_URL_REQUIRED` | `app.url` を宣言していないターゲットでのナビゲーションまたは相対 URL(`app.linkBase` がないデバイスターゲットでの `app.open(path)`)、またはポーリングする `app.url` も `app.readyUrl` もない `app.command` | configuration | 2 |
| `INVALID_APP_URL` | ベース URL を解析できない場合、ユーザー情報、クエリ、フラグメント、HTTP 以外のスキームを含む場合、ループバック以外のホストで暗号化されない HTTP を使う場合。リテラルのループバックアドレス(`127.0.0.1`、`[::1]`)以外のホストのポート 0、または実行時に空きポートをバインドできなかったループバックアドレスも該当します | configuration | 2 |
| `INVALID_GLOB` | 空のパターン。`tests` の除外を表す先頭 1 つの `!` 以外に、最初のセグメントが `!` で始まるもの(`!!tests/**`、`./!tests/**`)。単独の `!`。波括弧、文字クラス、extglob。区切りのバックスラッシュ。絶対パスまたは `..` セグメント。末尾の `/` または `.`。ワイルドカードがなくディレクトリを指す `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)が、開いているセッション、オープン処理中、クローズ処理中のセッションで埋まっている場合、またはサーバー終了中の場合。先に 1 つ閉じてください | 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` | 実行可能な通常テストとターゲットの組が 0 件の場合。メッセージに原因を示します。`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()` に達したとき、ディレクトリ内の別の実行がこの方法で操作されていた場合。ディレクトリの操作権を取得中に強制終了した実行がロックを残した場合(削除するファイルをメッセージに示します)。スイートを await し、既存のホストを閉じてから再試行してください。ステップ実行は `e2e run --step stop` で終了するか、メッセージにあるロックファイルを削除してください。 | configuration | 2 |
| `RUNNER_NOT_INSTALLED` | `e2e` がインストールされていない場所(`@e2e-dev/core` だけを使うプログラムなど)で、`@e2e-dev/web`、`@e2e-dev/mobile`、`@e2e-dev/desktop` のいずれかの `test`、`describe`、フックを呼んだ場合。同じエントリーのエンジンファクトリーは引き続き使えます。テストを書くには `e2e` をインストールしてください | configuration | 2 |
| `NO_LAST_RUN` | `--last-failed` が、実行の出力先に `report.json` を見つけられなかった場合、またはそのファイルが `report-1` ドキュメントでない場合。まずフラグなしで 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`、ワーカーフィクスチャ。互いを循環して指定するフィクスチャ。拡張元のフィクスチャと異なる `scope` または `auto` を持つ `test.extend()` のフィクスチャ | 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` | セットアップテストがセッションを 2 回保存した、未宣言の名前で保存した、または宣言したセッションを保存せずに終了した場合 | 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 が reject された場合。Node は Promise を作成したテストを特定できないため、未処理の reject は、表面化した時点で実行中のテストのエラーとして扱います。テストの合間ならこの実行エラーとなり、そのワーカーで最後に完了したテストを発生元の候補として示します。ワーカーでまだ 1 件もテストが完了していない場合は、代わりにワーカーを終了します。reject が実行エラーとなり、開始しようとしていたテストは `WORKER_CRASH` で失敗します。reject を残した本体は、`TEST_TIMEOUT` を超えた本体と同様に実行を続けます。`e2e mcp` でも、セッションが実行するテストのコードの実行中は、同じようにそのテストのエラーとして扱います。本体終了後の reject はこのコードとなり、`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 の検証に失敗した場合、またはワーカーが agent-desktop なしで起動した場合(エンジンの prepare を省いたホストなど) | infrastructure | 3 |
| `WORKER_INIT_FAILED` | ワーカープロセスが準備完了にならなかった場合 | infrastructure | 3 |
| `WORKER_EXIT` | ファイルの実行中にワーカーが予期せず終了した場合。実行中のテストは `WORKER_CRASH` で失敗し、そのファイルのほかのテストはスキップします。終了前に完了した試行はレポートに残します。リトライ前の試行や、直列グループの完了済みメンバーも含みます。クラッシュはそれらの後の試行として記録し、最後の試行後に発生した場合(`afterAll`)は最後の試行に記録します。未処理の reject によってワーカーが終了した場合(`UNHANDLED_REJECTION` を参照)、実行エラーはこのコードではなく、その reject です | infrastructure | 3 |
| `WORKER_CRASH` | 特定のテストの実行中にワーカーが終了した場合 | infrastructure | 3 |
| `WORKER_ENTRY_MISSING` | ワーカーのエントリーモジュールを解決できなかった場合。パッケージングの不具合です。 | infrastructure | 3 |
| `NODE_UNSUPPORTED` | ランタイムが e2e を実行できない場合。`^22.22.3 \|\| >=24.8.0` の範囲外の Node.js、1.4.3 より古い Bun、または 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>`)が未インストールです。npm は `--omit=optional` を指定した場合や、別のプラットフォームで `package-lock.json` を作成した場合(npm/cli#4828)に、それらを除外します。`--omit=optional` なしで再インストールするか、`package-lock.json` と `node_modules` を削除して `npm install` を実行してください | infrastructure | 3 |
| `IMAGE_CODEC_UNAVAILABLE` | スクリーンショットの PNG を読み書きする `@napi-rs/image` を読み込めなかった場合。原因をメッセージに示します。最初のスクリーンショットの読み書き時に読み込むため、スクリーンショットを撮らない実行では不要です。多くの場合、このプラットフォーム用のネイティブバインディング(`@napi-rs/image-<platform>-<arch>*`)が未インストールです。npm は `--omit=optional` を指定した場合や、別のプラットフォームで `package-lock.json` を作成した場合(npm/cli#4828)に、それを除外します。`--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 に 1 行出力します | infrastructure | 3 |
| `EVALUATE_FAILED` | `browser.evaluate` がページ内で例外を投げた場合、またはエンジンのページ内コードが必要とする JavaScript の組み込み機能(`Map` など)をページが削除または置き換え、以降の評価とロケーターが失敗する場合(`@e2e-dev/web`) | test | 1 |
| `INTERRUPTED` | ユーザーまたは CI のシグナルが実行を中止した場合。`--max-failures` または時間制限で中断したテストもこのコードで終了し、制限をメッセージに示します。その場合の実行の終了コードは 130 ではなく 1 です | interrupted | 130 |
#### テストコードのエラー
| コード | 発生条件 | 分類 | 終了コード |
| --- | --- | --- | ---: |
| `INVALID_ARGUMENT` | テストコードの引数検証が引数を拒否した場合 | test | 1 |
| `INVALID_LOCATOR` | テストコードの引数検証がロケーターの引数を拒否した場合 | test | 1 |
| `ERROR` | テストコードから投げられ、ほかのコードに分類されない値 | test | 1 |