`@e2e-dev/web` and `@e2e-dev/mobile` declare `e2e` an optional peer, but
their main entry imported it statically to build `test`. A program on
`@e2e-dev/core` alone that wrote `import { web } from '@e2e-dev/web'`
failed with ERR_MODULE_NOT_FOUND before any of its code ran.
The main entry now requires `e2e` only when it resolves. Without it, the
engine factory works and `test`, `describe`, and the hooks throw
RUNNER_NOT_INSTALLED when called. It uses createRequire, not a top-level
await, so a CommonJS file can still require() the entry.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* test(core): reproduce app commands exiting after readiness
* fix(core): fail runs when app commands exit after readiness
* test(core): tighten app exit outcomes and diagnostic docs
* fix(core): scope app command exits to dependent targets
Retain all owners of deduplicated commands and route ready app exits through the scheduler. Ignore owners with no unfinished work, preserve healthy targets, and classify forced app cancellation before watchdog timeout synthesis.
Cover shared ownership, completed targets, teardown, readiness and interrupt ordering, navigation advice, and both watchdog/app-grace orderings.
* fix(core): clarify app readiness and output guidance
* fix(core): share app command interruption and cover buffered exits
Use the same per-worker interruption path for app exits and run interrupts.
Iterate snapshots so a synchronous transport exit cannot skip another worker.
Cover exits buffered between readiness and scheduling, serial-group exit
status, and returned-unit skip reasons. Keep the aggregate process hook
separate from the individual managed-process hook.
* refactor(core): return app-exit target set directly
The scheduler result contains only the target names used to distinguish
app cancellation from a user interrupt. Return that set directly instead
of wrapping it in a named single-field result and a caller temporary.
Keep the same completion and drain order.
* test(core): cover app-exit guards and process liveness
* test(core): expect app exits to quote short logs whole
Main's #1577 quotes a log of up to 40 lines whole and keeps the first
lines of a longer one, so an app exit after readiness now quotes the
test server's first line too. The test asserts that instead of the old
tail-only quote, and docs/web.mdx says unexpected exits quote the log.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(changeset): note that background launchers now fail
Apply suggestion from @kdy1
Co-authored-by: Donny/강동윤 <kdy.1997.dev@gmail.com>
* fix(core): keep reused app hints from promising command output
A refused navigation on a target whose app.command sets reuseExisting
now says the runner may use a process it did not start, whose output
app.command.log never holds. The docs scope the exit quote to e2e run,
list spawn and log-open failures under APP_UNREACHABLE, and name the
first declaring target in the shared-command error label.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Donny/강동윤 <kdy.1997.dev@gmail.com>
* feat(mcp): open a session without a config by naming the engine
open_session takes engine, a package name or the factory call a config
would write as {package, export, options}, and app. An option can be
another such call, which is how an engine gets a device or browser
provider. Packages are found in the project, beside e2e, or in
~/.e2e/engines; ENGINE_NOT_INSTALLED names the install command.
@e2e-dev/web and @e2e-dev/mobile default-export their factory.
* fix(mcp): load import-only packages and refuse builtins as engines
Review fixes: resolve a package by its node_modules directory, so an
installed package without a loadable entry is reported as such; fall
back to the import condition; refuse Node builtin names; never read
the options object itself as a factory call; mobile() names the
platforms it takes when called without one.
* docs(mcp): say "no e2e config file", split the config error rows, pin the __proto__ key
Review fixes: a concrete app.url in the skill example, the string
shorthand in AGENTS.md, the engine-only wording in the security note,
and a test assertion that the __proto__ key survives as an own property.
A process that fails early and then keeps logging - a file watcher, say -
buried the startup error under its own tail: the message quoted only the last
20 lines appended since the command started. It now quotes the first and last
20 lines with `[startup output omitted]` between them when the log is longer,
both windows still byte-bounded and passed through the same redactor, so the
error that explains the failure survives.
Fixes#1527
* docs: retire sidebar page icons
The docs sidebar no longer shows icons. Drop icon: from every page's frontmatter, delete the grey silhouettes in docs/images/icons/, and make check-docs-logos fail on any frontmatter icon instead of requiring one on vendor pages. Card logos stay required. The authoring-docs skill trades its Page icons section for a short Vendor logos one.
* docs: require a migrate overview card for each migration guide
* docs: match only top-level icon keys in check-docs-logos
* feat(e2e): test.fail for tests expected to fail
Register, runtime, and option forms. A product failure passes the test and
keeps the error under expectedFailure; a pass fails with UNEXPECTED_PASS and
is not retried. Infrastructure errors, interrupts, and blocked agent verdicts
are not covered; a skip wins.
* fix(e2e): test.fail review fixes
Suite hook and API misuse errors not covered, reason redacted and bounded,
verdict settles before recordings, beforeEach may mark, afterEach refused,
reporters show the covered error, schema forbids marks on skipped, setup,
and serial results.
* fix(e2e): retry an unexpected pass of test.fail like Playwright
* docs(test): shorten test.fail
* feat(e2e): record one span of the screen with app.startRecording and app.stopRecording
* docs(e2e): name the video modes app.startRecording refuses under
* docs(reference): rewrite the API reference in the Next.js shape
Every reference page now opens with a lede and a minimal example, groups its
API under ## sections that start with a summary table linking to one ###
entry per member, and keeps the TypeScript declarations under ## Types.
* docs(reference): fix claims the review caught
Narrow the security summary rows to their sections, generate the screenshot
file name in the engine example instead of building it from the label, and
correct defaults, exit codes, and examples on config, cli, screen, web,
mobile, test, runner, and engine.
* docs(reference): address review findings
Scope error classes to runner errors, guard a zero-slot prepare in the engine
example, keep the cli #help-and-version anchor, and correct poll cancellation,
same-run screenshots, openLink schemes, type_secret, longPress durations,
runner signals and close failures, empty usernames, and the feedback exit
code. Make the reporter and extract examples self-contained.
* docs(reference): trim the summary tables to the minimum
Each group's summary table keeps the linked name and one or two short
columns (type, default, or a few-word description). Examples and details
live in the entries; facts that only a table cell held moved into its entry.
The expect overview is headed Reference instead of Entry points, and the
security rules table names what each section covers instead of restating
its claims.
* docs(reference): open every page's API under one Reference heading
Each page's first section after the lede is now ## Reference. A page with
one group lists its entries at ### right under it; a page with several keeps
each group as a ### with its summary table and its entries at ####.
Explanatory sections (behavior, budgets, setup, types) follow it. Linked
sub-parts that moved to ##### keep their anchors through explicit ids.
* docs(skills): describe the reference page shape in authoring-docs
Reference pages open their API under ## Reference, keep summary tables to
the name and one or two short columns, and nest entries at ### or ####
because Mintlify drops anchors below ####. ship-pr points reference edits
at these rules instead of the guide shortening pass.
* docs(reference): address cubic review on tables and skill
Keep readonly in the mobile device type, show the keyboard and mouse
object shapes, say a locator assertion times out as ASSERTION_FAILED, and
give reference pages a narrower shortening pass in authoring-docs.
* docs(reference): tighten the reference pages
Merge facts said twice into one place, move each declaration's JSDoc to a
single home, link timeout defaults, key grammar, and secure-field rules to
the pages that own them, and split long sentences. No fact is cut.
* docs(reference): address cubic review of the tightening pass
Qualify the GitHub token for fork pull requests, provider recording URLs,
duplicate device entries, MODEL_UNAVAILABLE timing, the APP_UNREACHABLE log
quote, UNKNOWN_TOOL versus UNSUPPORTED_CAPABILITY, node-less agent tools,
which model receives screenshots, passing assert evidence, and config-path
hosts; fix three garbled sentences.
* docs(reference): say device, not simulator, for worker isolation
* fix(cli): reject --max-duration over the timer cap as a flag error, name the limit on interrupted tests
* docs(errors): note INTERRUPTED from --max-failures and the time limit
* feat(cli): add e2e run --max-duration and maxDuration config
* fix(cli): keep e2e explore on its own --timeout, not maxDuration
* fix(cli): skip max-duration timer past setTimeout cap, cover config and explore paths
* refactor(cli): address max-duration review
- explore drops maxDuration from its config; runner no longer special-cases it
- scheduler records RUN_TIMEOUT from the skip reason, naming --max-duration or maxDuration
- stopEarly wakes the loop itself
- reject maxDuration above 2147483647 ms instead of skipping the timer
- trim cli docs, clarify ci wording, sync plugin
* feat(runner): open an e2e session from another test runner
Adds openSession() to e2e/runner: the standalone attempt e2e mcp already opens,
with its fixtures, live step progress (onStep), the step records (steps()), and
cleanup handed to the calling runner. config takes a path or an E2EConfig value,
as list() does; a config file is loaded fresh with its imports, so each session
gets engine instances of its own.
close() aborts the session's operation budget before teardown, so a fixture call
still running is cancelled; e2e mcp gets the same fix. Disposing a session
throws its cleanup failures as an AggregateError. A session reserves a free port
only for the target it opens.
* feat(runner): split hosted worker and test lifetimes
* fix(runner): release host engine claims after clean teardown
* fix(runner): enforce the hosted session deadline and keep the host after a failed launch
A hosted session's timeout now cuts every running step when it passes, the
way a run's body race does: an engine that ignores its operation timeout
or a model call no longer outlives it, the operation fails with
TEST_TIMEOUT, and close() reports the timeout. A timeout of 0 or less is
refused, as the config's is; the Playwright example maps Playwright's 0
to the config default.
A launch that fails or is cancelled leaves the host usable, as a run keeps
its worker for the retry; only failed engine cleanup retires it.
Split standalone.ts: the worker stays, standalone-attempt.ts owns one
attempt's reservation, launch, fixtures, deadline, and close, host-trace.ts
its trace.md. The attempt's kind is explicit instead of inferred from a
name. Port allocation for one target is a helper shared with MCP.
* fix(report): hosted trace pages stop pointing at a report.json that does not exist
* refactor(runner): simplify the hosted worker after review
The worker is an explicit state machine (idle, opening, live, retired)
instead of four promises and a flag. A live attempt holds its registry
through holdSecretRegistry, outranking a host opened meanwhile, so secrets
no longer import from the expect layer and the published attempt carries no
registry. Target selection is one helper shared with MCP; port allocation
for one target is direct. The attempt's verdict uses the run's
classifyAttemptStatus. The one-shot video branch was dead: MCP records off.
The fixture-recording deadline cap is gone: the session timer and the step
signal already cut every operation, and e2e run's body race covers runs.
withAbort's third argument is the fallback the signal's own error outranks.
The open-host suite is five files by concern on one shared harness.
* chore: refresh the runner docs card and drop an unused test helper export
* test(runner): pin the session verdict, not which deadline reporter won
A poll bounded by the session deadline and the session's own cut fire at
the same moment; on a slow host either can report first. Both are true.
---------
Co-authored-by: bheemreddy-samsara <bheem.reddy@samsara.com>
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
The guide answers what most readers ask: how secrets stay out of the model,
what can still leak, and what runs with your permissions. Every rule moves to
docs/reference/security.mdx. smol host-loopback access moves to the smol
page's warning. Fixes facts that no longer matched src/: defineTool errors are
INVALID_CONFIG, the CI cache default skips a cache.store, start-screen replay
matches routes, and outbound connections now list login, models, init, and the
smol image pull.
* fix(run): serial group failures reach the exit code and the reporters
- exit code folds serial groups: members carry no attempts, so a group's
infrastructure error exited 1, and a launch failure (all members skipped) exited 0
- group attempt that fails before any member runs (launch, file load) fails
the first member with the error, rest skip as serial-predecessor-failed;
an interrupt there skips every member instead
- a retry that never reached its members keeps the verdicts of the attempt before it
- worker crash during a serial member fails that member with WORKER_CRASH
instead of skipping it as never started
* docs(test): an interrupted serial launch skips every member
* fix(secrets): rewrite traces and text downloads whenever the run has a secret value
A registered value a test passed as a plain string (an app.open URL, a fill)
was redacted from titles, labels, and agent input but kept verbatim in
trace.zip: trace and download rewriting was gated on the exposure level,
which only a fill or an engine-held secret raises. Rewriting now depends on
the session ledger holding a value. The engine exposure level had no other
consumer and is removed; exposure now only decides pixels and saved-session
taint.
* fix(secrets): cover a plain-string fill, scope docs to the session's known values
* docs(secrets): download redaction is whole-value; TRACE_WITHHELD outside-path case
* docs(secrets): name the download rewrite failure path