Review fixes: lines made behind a failing one do not run and an unawaited or timer failure fails the call; listed reads are complete; messages reach the code redacted; lines share the call's deadline; expect(value) compares like the test API; isEditable alias removed; refused arguments carry INVALID_ARGUMENT; clearTimeout works.
run_code takes the body of an async function with screen, app, expect, credentials, secrets, and console in scope. The code runs in QuickJS (the run package, in a worker) with no host access. Each call it makes on the app is spelled as one test line and parsed by the same closed grammar, then run with the same secret checks, so loops, reads, and return values work while the grammar still decides what reaches the app.
* feat(mcp): attach to a test held at screen.pause() or --step
A test held at `screen.pause()` or at an `e2e run --step` hold now prints
an ID, such as `Paused (p1) in pays with a card [web]:`. You can pass it to
`open_session {attach: "p1"}` in `e2e mcp` to look at the held test's app
and act on it.
The tools run in the worker, on the engine session the held attempt already
has. Requests go from the MCP server to the runner over the directory's
step socket, and the runner relays them to the worker. Replies are redacted
with the attempt's secret ledger before they're sent.
- `close_session` detaches and leaves the test held.
- When the test resumes, the session ends right away and a call still in
progress is cancelled.
- Attached calls aren't recorded as steps in the report or the trace.
- `run_code`, the recording tools, and `type_secret` aren't available in an
attached session.
- `e2e run --step` in a terminal now listens on the step socket like a pause
does, so you can attach at its holds.
With several workers paused, each prompt is now drawn from the hold it
names. Before, it could show one test's title next to another test's screen.
* fix(mcp): print output a tool's timer writes after its attached call ends
Output is muted only while the attached call is running. The call scope
lives in its own module, so process-output.ts doesn't load the attach tools.
* feat(mcp): record in an attached session when the run doesn't record
start_recording and stop_recording join the attached catalog, which now
lists exactly the normal session's tools. If the run already records the
test, start_recording fails with the run's video directory. A recording
still running when the session ends is saved.
The docs no longer describe what a pause ID looks like. The examples and
sample output show one.
* fix(mcp): don't hold a resumed test while an attached recording saves
On a resume or an interrupt the worker sends the stop for the agent's
recording and lets the test continue. The file finishes in the background
and its path goes to the log. Teardown waits for a save still in progress
for at most cleanupTimeout.
A project tool's attachScreenshot works in an attached session and stays
out of the test's report. In the live list a long title ends in an
ellipsis, so the pause ID stays visible.
Adds French as a translation language beside ja and zh, with the style guide, glossary, navigation labels, and the minimum set: Get started and Platforms.
Co-authored-by: Kacper Kapuściak <kapusciak.k@gmail.com>
* docs(hi): translate the Features pages
cache, explore, visual-testing, authentication, bug-bash, and agents.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): apply the Sol review of the cache page
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): apply the Sol review of the other Features pages
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): apply the pre-review fixes to the Features pages
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): apply the second pre-review to the Features pages
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): use रेडैक्शन, कैरेक्टर and दोष in the Features pages
The hi assignee chose these words in review: रेडैक्शन for the noun
"redaction", कैरेक्टर for "character" in length limits, since those limits
count digits and symbols too, and दोष for "defect". The glossary records
them, and वैल्यू (not मान) for "value".
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): widen the character glossary row and rewrap one paragraph
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): name कैश एंट्री in the cache entry glossary row
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): match the Security card to the reworded English card
The card promised that secrets stay out of screenshots. Screenshots mask
only secure fields, so #1988 rewords the English card. This brings the
Hindi card along.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): link Next.js on the cache page like the English page
#1952 added the link to the English page after this branch was cut.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): use चेकआउट for a git checkout
Add a glossary row for it and use it on the cache and web pages, which
said वर्किंग कॉपी. explore.mdx and ci.mdx already say चेकआउट.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(web): launch Chromium with its sandbox on by default
The web engine launched Chromium without chromiumSandbox, so Playwright added --no-sandbox to every browser process. The agent can follow the app to another origin, so a renderer exploit on a page it reaches ran unsandboxed as the user running e2e run, with the checkout, .env, and model keys in reach.
Chromium now launches with chromiumSandbox: true unless the config opts out with web({ chromiumSandbox: false }) or the run environment sets E2E_CHROMIUM_SANDBOX=0, for hosts where the sandbox cannot start (root, containers, Ubuntu 23.10+ with the AppArmor user-namespace restriction). Firefox and WebKit never receive the option. The flag resolves from the option, then the run's environment, then on; the process environment never decides a launch, per the EngineInitInfo.env contract. CI opts out explicitly because the ubuntu-2404 runners restrict unprivileged user namespaces.
Docs updated next to the no-origin-allowlist note (docs/reference/web.mdx, docs/security.mdx, SECURITY.md, skills/e2e/references/setup.md) with a .changeset entry. The smol VM's --no-sandbox is unchanged: the VM is the boundary there.
Verified: pnpm check green; web unit 354/354; web integration 379 passed with 3 known load flakes that pass in isolation; testbed CLI 6/6 fail with "Chromium sandboxing failed!" by default and 6/6 pass with the opt-out on this host.
Fixes#1613
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(web): qualify chromiumSandbox coverage as local-launch-only
Cubic review on the sandbox-default PR found three doc overstatements: SECURITY.md presented the sandbox as universal while connect() and browser providers bypass launch, the skill reference omitted that E2E_CHROMIUM_SANDBOX=0 only applies when the option is omitted, and the reference page implied any container cannot run the sandbox. All three are corrected in the SECURITY note, the reference page, the option JSDoc, and both skill copies.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* fix(web): friendly Chromium sandbox failure and unified sandbox resolution
A sandboxed launch on a host whose sandbox cannot start failed with Playwright's raw error and its full call log, which only hints at the option. acquireBrowser now catches that one failure on a local launch and throws an ENGINE_FAILURE naming both opt-outs, E2E_CHROMIUM_SANDBOX=0 and web({ chromiumSandbox: false }), with no call log and no cause chain to leak it back.
The sandbox flag resolves in one place now: resolveChromiumSandbox(configured, env) in browser-connection.ts replaces the split readChromiumSandboxFlag plus surface resolver, and the surface keeps a single field that init resolves. BrowserConnection.acquire takes an options object, so a relaunch retries with the same options. The option JSDoc shrinks to two lines pointing at the security docs.
Tests follow the restructure: the cdp-attach edits are gone (the flag never applied to attach), screenshot-caret and stalled-frame run sandboxed by default, resolved from the ambient environment so the CI opt-out still reaches a direct launch, and the workflow comments shrink to one line. New tests pin the trim and lowercase handling, the opt-out surviving a failed relaunch, and the friendly error text.
Verified: web unit 358/358 with the opt-out; a real launch on this host fails with the friendly error by default and passes with E2E_CHROMIUM_SANDBOX=0.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(web): minor bump for the sandbox default, CI opt-out, one home for the why
The sandbox default breaks Docker and Linux CI hosts, and the changeset said nothing about it: it is now a minor bump, opened as a maintainer-called release, telling users to set E2E_CHROMIUM_SANDBOX=0.
The CI docs name the opt-out where CI users find it: the GitHub Actions web workflow and the visual-testing screenshots workflow both set E2E_CHROMIUM_SANDBOX=0 on ubuntu-latest, matching this repo's own CI, with a note pointing at the security docs. The other CI pages run mobile targets only, so there is nothing to add there.
The why now lives in docs/security.mdx alone: the reference page, SECURITY.md, the option JSDoc, and the skill reference link to it instead of repeating it.
Verified: changeset-bumps, the docs check chain (anchors, MDX, examples, package managers, logos), and the skill tests all pass.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(web): qualify the Chromium sandbox opt-out as ubuntu-latest only
The visual-testing guide said Linux runners generally block the user
namespaces Chromium needs. The limitation is specific to the
ubuntu-latest runners used here, so name them and tell readers to leave
the sandbox on where it starts.
* fix(web): address review follow-ups on the Chromium sandbox default
Move the sandbox launch error out of the surface and into
BrowserConnection.launchLocal, where the browser name and the resolved
sandbox flag are already known, and drop the untested verb guard. The
error now names the environment opt-out only when the option did not set
the value, since an explicit option wins over the variable. The surface
keeps the option as a readonly field and resolves it into a private
field defaulting to true, the same pattern as headed, so startAttempt
without init no longer needs the fallback. The skill GitHub Actions
recipe runs ubuntu-latest with E2E_CHROMIUM_SANDBOX 0, the web reference
points at the new ENGINE_FAILURE instead of Playwright error text, and
the resolve helper loses its dead branches.
Web unit suite: 362/363 pass; the one failure is artifact-path, which
fails identically on the base head because a real Chromium cannot start
sandboxed in this container.
* fix(web): address re-review follow-ups on the Chromium sandbox default
Resolve the sandbox into one { enabled, fromOption } object and pass it through acquire into launchLocal, which now takes the options object instead of five positional args, so the launch and its error cannot disagree about which opt-out set the value. Add the waiter-joins-a-pending-relaunch case, where the re-acquire runs once and a flip cannot cancel out, and assert retryable is false on the friendly error. Document E2E_CHROMIUM_SANDBOX in the environment reference, point the dead [Security](/security) links at https://e2e.com/docs/security, and fix the changeset wording, since the error no longer always names both opt-outs. The acquire JSDoc now states the actual guarantee: a launch takes the value its own call passes.
Web unit suite: 364/364 pass with E2E_CHROMIUM_SANDBOX=0 (artifact-path fails without it, identically on the base head, because a real Chromium cannot start sandboxed in this container). Web typecheck clean, oxlint clean. The new waiter test fails against a flip mutant injected on the re-acquire and passes without it.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(web): mark E2E_CHROMIUM_SANDBOX as a value in the env reference
The entry was marked flag, but on this page 0 and false mean unset for flags, while 0 opts out of sandboxing here. Mark it value so readers do not apply the wrong flag semantics.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(ci): restore the timings-history section lost in the rebase
The rebase conflict resolution in docs/ci/github-actions.mdx kept only the tail of the new Cache the timings history section, dropping its heading, intro, and example, which broke the docs anchor check (docs/ci.mdx links to #cache-the-timings-history). Restored in full; the sandbox opt-out paragraph follows it unchanged.
Verified: the docs check chain passes locally (anchors, examples, package managers, logos, MDX).
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(security): soften sandbox containment wording
The security page stated a renderer exploit stays contained by the
sandbox, which reads as a guarantee. Say the sandbox helps contain it
and note it does not prevent sandbox escapes or Chromium
vulnerabilities, matching the review feedback on the Chromium sandbox
default.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(security): wrap the sandbox containment sentence at 80 columns
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* fix(web): import EngineError from @e2e-dev/core/engine
browser-connection imported EngineError from e2e/engine, so loading the
web engine without the e2e package failed with ERR_MODULE_NOT_FOUND.
That broke the core-only install smoke check, which loads each engine
main entry without e2e installed. Import from @e2e-dev/core/engine
instead, like every other file in the web engine.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* docs(security): re-wrap sandbox paragraph and soften changeset wording
Re-wrap the sandbox containment paragraph in docs/security.mdx at 80
columns so vulnerabilities; no longer sits on a line of its own, and
soften the changeset to match: the sandbox helps contain a renderer
exploit but does not prevent sandbox escapes. The changeset keeps only
the user-facing part: what changed and the two opt-outs.
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
* fix(web): default the Chromium sandbox by platform, drop the env opt-out
On for macOS and Windows, opt-in on Linux where root, most containers
and Ubuntu 23.10+ cannot start it. The option alone decides, so CI,
the test env forwarding and the docs recipes need no opt-out.
* test(web): drop the relaunch cases the waiter test already covers
---------
Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
* docs(ja,zh): stop the Security card promising that secrets stay out of screenshots
The English card makes the same fix in #1988. Screenshots mask only secure
fields, so a secret the app shows elsewhere is in the image. The cards now
reuse the wording of the security page in each language.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(zh): use the Security card wording a native speaker approved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Screenshots mask only secure fields: password inputs on web (SECURE_FIELD_SELECTOR in packages/web/src/read-node.ts) and states.secure nodes on mobile (packages/mobile/src/nodes.ts), as docs/security.mdx says.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The other merged Hindi pages say वैल्यू for "value" 12 times, and these
two pages said मान 4 times. The hi assignee chose वैल्यू, and कैरेक्टर for
"character", since a string also holds digits and symbols. The two
paragraphs with changed words are rewrapped, keeping every word.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs: add a Next.js guide page
One page takes a Next.js developer from `e2e init` to CI: `next dev`
locally and `next start` on the build in CI from one config, the port,
`reuseExisting`, and the Next.js problems (`allowedDevOrigins` on
127.0.0.1, the route announcer that `getByRole('alert')` also matches, a
webpack watcher that reads `.e2e/`), plus the `create-next-app` starter
and the Vercel template. The hydration accordion moves here from web.mdx;
web, cache, and example-projects link to the page, with ja and zh
translations, and the e2e skill's setup reference carries the same
guidance.
Refs ENG-1378
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: move the Next.js page into a Frameworks group
Next.js is not a platform like web, mobile, or desktop, so the page moves
to docs/frameworks/nextjs.mdx under a new Frameworks navigation group. The
web page no longer points at it from the app URL paragraph.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cache): record a code typed into a one-time-code field as a run-time gap
A code typed one digit per box replayed the previous run's code: the
read-off-the-screen check sees each digit alone, and a lone digit is
neither a whole node nor a word of the text that shows the code.
A value typed into a node whose inputPurpose is one-time-code is now a
minted-token gap. A lone digit there never counts as spelled out by the
instruction, so "the 6-digit code" does not make a 6 replay; a longer
value the instruction or params spell out still replays.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cache): replay a one-time-code fill only when the step spells the whole value
A chunk such as 482 from a longer param or word no longer counts as
written by the step; it needs to be a word of its own in the instruction or
exactly a param's value. The cache docs say which values replay in a
one-time-code field, and the twins form's JSDoc sits above its function
again.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs: add Hindi as a translation language
Adds hi beside ja and zh in the translation and anchor checks, and keeps
docs/hi out of the npm package, Context7, and the skill wording test.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): add the style guide, glossary, and navigation labels
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): translate the getting-started and platform pages
Translates the minimum set from #1890: index, quickstart, core-concepts,
agentic-vs-deterministic, coding-agents, mcp-server, ci, web, and mobile.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): fix wording and term consistency from review
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): apply the back-translation and Apple terminology review
Fixes the meaning errors a blind back-translation found, such as "similar"
for "matching" and "equal to" for "up to" on the mobile page. Writes the
remaining English words in Devanagari, and follows Apple's Hindi spelling
for accessibility, account, and keyboard keys. Uses इजाज़त for permission
and एक्शन for action, and records both in the glossary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): fix agreement and ambiguous clauses from the Sol re-check
Splits sentences where a clause could attach to the wrong noun, such as
the location in the assertion inputs and the checked state of a hidden
checkbox. Restores the Cursor update line to the Cursor commands only.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): use तालमेल बिठाना for the agent adapting on the landing page
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): follow main's removal of the run_tests MCP tool
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): unify reference, action, and state, and rewrap long lines
Uses रेफ़रेंस for "reference" everywhere, as most links already did, and
records स्थिति (app state in prose) beside स्टेट (stored or device state).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Kacper Kapuściak <kapusciak.k@gmail.com>
* docs(pt-BR): translate the minimum set
Add the Brazilian Portuguese locale with the Get started and Platforms
pages (index, quickstart, core-concepts, agentic-vs-deterministic,
coding-agents, mcp-server, ci, web, mobile), navigation labels, and a
README with the style guide and glossary.
Register `pt-BR` in the translation and anchor checks, the build and
skill-test exclusions, and context7.json, next to ja, zh, cs, and es.
List it in AGENTS.md and the authoring-docs skill, whose checklist now
says "every docs/<language>/ folder" so the next language needs no edit
there.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(pt-BR): state the timing order and what docs:check covers
The ci page now says untimed files run first, then the rest longest
first. The README says docs:check compares page outline and code, and
only checks that each tab and group has a label.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(reporters): build the built-in reporters on the public Reporter API
The built-in list, dot, json, junit, and markdown reporters now use only
the public Reporter contract: factories on e2e/reporters, printsTo for the
terminal stream a reporter prints to (one reporter per stream), live
onOutput, onStepPrompt, and onSummary hooks for any number of reporters,
and reportFiles for files the runner writes atomically. The list and dot
ids beside json print to stderr, so list,json now works as dot,json does.
@e2e-dev/html-reporter writes through reportFiles.
* docs(reporters): bring the Japanese and Chinese reporter pages up to date
Translates the reporter reference, the config reporters table, the
--reporter row, and the debugging output paragraph. In English, the name
section now says a reporter may share a built-in's name, and two lines
read less ambiguously.
Claude Code loads .mcp.json from a plugin's root even when the manifest names none, so the file goes and Codex and Cursor read the server from mcp.json, the Agent Plugins file Copilot already uses. plugins:check fails if .mcp.json comes back.
Under `e2e run --watch`, a test is now paused at each `screen.pause()` on
every run, as in `e2e run`.
While a pause is shown, the keys are read by the pause prompt and not by
watch mode:
- Press Enter to resume the test.
- Press `q` to cancel that run and stay in watch mode.
`e2e run --step next` and `stop` can be used from another shell, as for a
run without `--watch`.
With `await screen.pause()`, a test is paused at that line, with the app
open, until someone resumes it.
- In a terminal, press Enter to resume the test.
- From another shell in the same directory, run `e2e run --step next`.
A run without a terminal is resumed this way.
- Paused time doesn't count toward the test's timeout.
- With `CI` set, the test fails with `PAUSE_IN_CI`.
- Under `--step`, a test is still paused after `n` or `a`.
- A test isn't paused in an MCP `open_session {test}` session, under
`openHost` or `run()`, or in a core program.
- A test isn't paused under `e2e run --watch` yet.
* docs(es): translate the getting-started and platform pages
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): follow the worker fixture change in mobile and accept feminine bloqueada
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): fix agreement and meaning slips, restore main's translation policy
The earlier patch to scripts/check-docs-translations.ts and the
authoring-docs skill was made against an older main and reverted the
best-effort policy; both now carry only the es registration.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): follow the best-effort translation policy in the README
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): say what docs:check detects
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs: list the Spanish translation in AGENTS.md
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-authored-by: Kacper Kapuściak <kapusciak.k@gmail.com>
* docs(cz): translate the minimum set
Add the Czech locale with the Get started and Platforms pages,
navigation labels, and a README with the style guide and glossary.
Register `cz` in the translation checks and exclusions like `zh`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cz): fix three translations flagged in review
- web: the run fails with APP_ALREADY_RUNNING, not the server
- coding-agents: `init` registers the server, not the other way round
- quickstart: rephrase the config options intro
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cz): address review: no en dash, current README rules, mobile install
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cs): use the language code cs instead of the country code cz
Czech is `cs` in ISO 639-1 and BCP 47, which browsers send and `lang` and
`hreflang` expect. The code is also the URL, so rename before launch.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(test): add test.each and test.for
* fix(test): read %i and %f titles like parseInt/parseFloat, as Vitest does
* fix(test): keep each titles on one line and spread only all-array tables
* fix(test): type unknown each rows loosely and keep only real cycles as [Circular]
An unknown row may be spread or passed whole at run time, so EachArgs
now types only the fixtures, last. %j only reads Node's circular-structure
TypeError as a cycle; a toJSON that throws names the row. Docs say %d
keeps BigInt's n suffix and shows Symbol as NaN, and that a string title
value keeps its line breaks.
* docs(test): note that %i keeps the BigInt n suffix
* fix(test): print undefined for %j of a function or Symbol, read Unicode $keys
- %j prints undefined for what JSON leaves out, as Vitest does, so a
function's source never lands in a title
- $name and its path read Unicode identifier characters
- inline the test mode back into registrar
- docs: note that a Vitest test.each body gets no fixtures
* fix(test): read test.each fixtures from the parameter after the row
Fixtures are now set up on demand from what the body destructures (#1891).
A test.each row runs a wrapper, (fixtures) => body(...row, fixtures), so
registration read the wrapper's own parameter and refused every row with
"must destructure its first parameter". registerTest now takes the body
and the position of its fixtures parameter (the row's length when it is
spread, else 1), and fixtureNames reads that parameter.
* fix(test): keep Error rows on one line and locate rows through a helper
- An Error in a title shows as its name and message, not its stack, and
whatever inspect still breaks is joined, so a title is always one line
- The source location reads the whole stack: the default 10 frames cut the
test file off a row declared through a helper and a describe
- A tagged template table is a COLLECTION_ERROR instead of one test per
template chunk
- A bound row body is told how to wrap itself with the row first
- tests: a run sets up only the fixtures a row body names; fixtureNames at
a position
- docs, skill, changeset: a row body names its fixtures after the row
* fix(test): restore the stack limit on a throw, read only an own raw
- stackLocations puts Error.stackTraceLimit back in a finally
- Only an own raw property marks a template table
- The wrap hint for a bound row body names one argument per row item
- skill: rows are spread only when every row is an array
---------
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
* fix(html-reporter): keep the previous page when a run stops before its tests
writeReport never checked run.reportPath, so a run that stopped before
its tests (NO_TESTS, a config error, an app that never started) replaced
report.html with an empty page beside the previous run's report.json and
printed an HTML report row under "Report (not written)". It now returns
early with no row, as the built-in junit and markdown reporters do, and
the FinishedRun.reportPath docs say it is also absent when the run stops
before its tests.
Fixes#1897.
* docs(runner): say run()'s reportPath is also undefined when a run stops before its tests
The same field FinishedRun.reportPath documents, in reference/runner.mdx
and the ja and zh pages. The changeset is one line.
A session a test opens with launch() from @e2e-dev/core was invisible to
the test's report, and a secret passed only to launch() could reach it.
- secrets: every owner of values (config, open host, open session) shares
them through one refcounted map on globalThis; ledgers redact what is
shared beside them without storing it
- report: a launch session's steps are mirrored into the test's recorder
under an actor name (launch-1), with model usage and video
- lifecycle: the attempt owns hosts and sessions the test opened, cuts
their steps when the body ends, and closes them at its end
- reporters: list, trace page, markdown, junit and html name the session
- errors a session throws no longer carry a secret in details
* feat(test): set fixtures up once per worker and pass them to beforeAll
test.extend() takes [fn, { scope: 'worker' }]: one instance per worker and
target, torn down when the worker ends. Suite hooks receive worker fixtures.
Engines can declare isolation: 'worker'; @e2e-dev/mobile does, so its device,
app, and screen reach beforeAll, afterAll, and worker fixtures.
Refs ENG-1297
* feat(e2e)!: set up fixtures on demand
A test now sets up only the test.extend() fixtures its body and its
beforeEach and afterEach hooks name in their first parameter, the fixtures
those name, and the auto ones. A suite hook sets up the worker fixtures it
names and the auto worker fixtures. Names are read from the function's
source, as Playwright and Vitest read them.
- [fn, { auto: true }] and [fn, { scope: 'worker', auto: true }] run a
fixture nothing names.
- A fixture can name the fixtures declared beside it in the same extend()
call. Fixtures run in declaration order, each after the ones it names.
- The attempt is resolved as one unit before the session launches: a
fixture only an afterEach names is set up before the first beforeEach.
An afterEach that names a fixture whose setup failed is skipped.
- Fixture rules fail as COLLECTION_ERROR with the file and line of the
code: a parameter that is not destructured or takes a rest property, and
a cycle, when the file is collected; a name the target lacks, a test
fixture named by a suite hook or a worker fixture, and a fixture named
like an engine's, at selection, for the pairs that run on that target.
- On an engine with isolation: 'worker', a suite hook or a worker fixture
teardown that names no engine-backed fixture opens no engine attempt.
BREAKING CHANGE: a fixture nothing names no longer runs unless it is
declared with auto: true, and a test body, hook, or fixture function that
takes the whole fixture object (async (fixtures) => {}) no longer loads.
Refs ENG-1297
* refactor(core): declare core fixtures in one table
The five core fixtures (agent, app, screen, platform, session) are one
table in @e2e-dev/core: name, scope, and factory. createFixtures builds
the built-ins object through one loop over that table and the engine's
factories, every fixture a lazy accessor behind the same gate as before.
The runner's fixture pool, test.extend() validation, and launch read the
names and scopes from the table, so the name lists and the per-name scope
checks are gone. A launch session exposes the core fixtures that do not
belong to a test: app, screen, platform.
No behaviour change. app and screen were built with the attempt and are
now built on first read, like agent and the engine's fixtures.
Refs ENG-1297
* feat(e2e): extend a built-in fixture through test.extend
A test.extend() fixture named like one the test already has extends it,
by Playwright's rule: inside its function its own name is the fixture it
extends (the built-in, or an earlier fixture of that name), and tests,
hooks, and other fixtures that name it receive what it hands to use().
base.extend({ device: async ({ device }, use) => {
await device.setPermission('camera', 'deny');
await use(device);
} })
- A plain function takes the scope the extended fixture has on the
target: device is a worker fixture on mobile, so its override runs once
per worker and reaches beforeAll; app is a test fixture on web and a
worker fixture on mobile. A declared scope that differs is a
COLLECTION_ERROR naming both.
- A worker-scoped override receives what a worker fixture receives for
that built-in, the forwarder to the attempt that is running.
- On a target without the built-in nothing fails until code that runs
there names it; then the target has no such fixture.
- Only user code sees the override: the attempt's own built-ins, which the
runner and the worker fixtures' forwarders read, are untouched.
- Types: the override keeps the extended fixture's type and scope, through
an extend() overload that takes overrides without type arguments.
A fixture named like a core fixture, an engine's, or an earlier one of the
chain was refused before.
Refs ENG-1297
* docs(fixtures): name built-in fixtures and give their scope per engine
The docs now use one term, built-in fixtures, for agent, app, screen,
platform, session, and the ones an engine contributes (browser, device),
where pages said core fixtures, contributed fixtures, or engine fixtures.
The test reference gets one table with each built-in fixture's scope on
web and on mobile, and says what the scope decides: a test fixture reaches
test bodies, beforeEach, and afterEach; a worker fixture also reaches
beforeAll, afterAll, and worker fixtures. The hooks, worker fixtures, and
override sections link to it, as do the fixtures guide and the engine
pages. The Japanese and Chinese pages carry the table and the same terms.
Refs ENG-1297
* docs(ja): translate the fixture scope and on-demand changes
* docs(zh): translate the fixture scope and on-demand changes
* fix(e2e): let a worker fixture name an extended app or screen
A fixture that extends `app` or `screen` was taken for a test fixture when
its test.extend() call was checked, before any target is known. A worker
fixture declared after it that names `app` then failed at import on every
target, though the same fixture is accepted without the override and the
plan resolves both to worker scope on an engine whose state outlives a
test.
The scope of a plain function is now unresolved until a target is known,
whatever it extends, as it already was for an engine's own fixtures.
Refs ENG-1297
* fix(e2e): fail a suite hook that left an engine step running
On an engine whose state outlives a test, a beforeAll or afterAll hook, or
a worker fixture's teardown, can start a device step and not await it. The
hook's attempt then closed under the step, and its failure arrived later
as a stray rejection charged to whichever test ran then.
The suite attempt now does what a test attempt does once its body settled:
the step is failed at its call and cancelled, its outcome is awaited within
the cleanup budget, and the hook fails with STEP_NOT_AWAITED (HOOK_FAILED
for a suite hook).
The suite attempt keeps no step records, and StepRecorder dropped the
record of the step it had just opened before marking it running, so there
was nothing to abandon: a step now counts as running before the retained
window is trimmed.
Refs ENG-1297
* refactor(e2e): keep the fixtures a function names beside it
Registration parsed each test body, hook, and fixture function for the
fixtures it names, dropped the result, and left it in a WeakMap that the
planner and the pool read back with placeholder subjects. A cache miss
there would have named the wrong code and no line.
The parse result is now data: `names` on the registered test, the hook,
and the fixture definition. The planner and the pool read it, the WeakMap
and the per-function wrappers are gone, and one describeUser() gives an
error its subject. The explore test, registered by hand, parses its body
where it builds the record.
Unit tests state the names instead of generating source text for them.
Refs ENG-1297
* refactor(core): resolve built-in fixtures in one place
The core table declared the core fixtures, but what a target's built-in
fixtures are was still assembled around it: core names plus engine names in
three files, the 'engine' scope resolved in e2e through a cast into the
table, `platform` hard-coded as the one fixture that needs no attempt, and
two structural copies of the target.
core now exports builtInFixtures(target): names, scope(name),
needsAttempt(name), attemptless(name), and the unknown-fixture message,
over one BuiltInTarget. `platform` declares in the table that the target
alone decides it. launch, the planner, and the pool read from it.
DECLARED_BUILT_INS is the same view before a target is known: a scope the
engine decides is 'unresolved'. The planner takes either one, so its
no-target mode and the `target === undefined` branches through scopeOf and
read are gone. The scope of a fixture that extends `app` before a target
is known is 'unresolved' by construction.
Refs ENG-1297
* refactor(e2e): hand each function the fixtures it names
Every test body, hook, and fixture function must destructure its first
parameter, so what it reads is known before it runs. bindFixtures still
built a Proxy-gated bag for arbitrary property reads: one value in three
stores, the gate run twice (once over a faked plan), a third derivation of
scope, and an own-name shadow that re-derived what the planner had resolved.
No test code could reach the gate's throwing branches; only unit tests did,
by reading the bag directly.
The plan now records, per function, what each name it reads resolved to: a
chain fixture or a built-in. The pool hands each function a plain object
with exactly those names, the value a chain fixture handed over, or a
built-in read off the attempt when the function destructures it, so
built-ins stay lazy. An override that names itself receives the fixture it
extends because that is what its own name resolved to.
- bound.call(user) replaces user.fn(bound.fixtures); ready(user) asks
whether every chain fixture it names was provided.
- attemptlessBuiltIns is a function from a name to a value that throws the
reason for a built-in that needs an attempt.
- The planner runs once: it records what each fixture names, and the order
is one declaration-order walk over that record. A second validating pass
only reordered.
Behaviour: a bound or native function, whose parameters cannot be read, is
a COLLECTION_ERROR; it used to parse as naming nothing and still got lazy
built-ins. The docs no longer promise hooks and the body one shared object.
Refs ENG-1297
* refactor(e2e): move the suite attempt out of TargetExecutor
dispose, openSuiteHooks, and openSuiteAttempt were 177 lines of a second
attempt lifecycle inside TargetExecutor, written as closures in one method.
run/suite-attempt.ts now owns it: a SuiteAttempt class with open, acquire,
within, and close, over a SuiteAttemptHost interface the executor satisfies
(the way serial.ts borrows it through SerialHost), plus the worker
fixtures' teardown pass. It is the realm's SuiteHookSession itself, so the
executor keeps a context object and two call sites.
The three branches that built an attemptless reader with a "not available
to the <label>" error are one NoAttempt value ('isolated', 'unnamed',
'interrupted', or the launch failure) and one mapper to the message.
execute.ts: 1244 lines to 1052.
Refs ENG-1297
* refactor(e2e): share the attempt's fixture sequence
A run's attempt and an `e2e mcp` session's test each planned the test's
fixtures, bound them, entered the worker pool, set them up, ran the
beforeEach hooks and the body, filtered the afterEach hooks that can still
run, and labelled the teardowns. This PR widened that copy, and
standalone-test.ts asked the realm for the same hooks four times.
planAttemptFixtures(target, test, hooks) plans before any session exists
and returns open(), which binds the plan to the attempt: enter(), run()
for setup, hooks, and body, and cleanup() for the labelled afterEach hooks
and teardowns. Both call sites keep their own phases, budgets, and error
handling around it.
execute.ts: 1052 lines to 1031, its size on main.
Refs ENG-1297
* refactor(e2e): open the suite-hook pass without a lazy thunk
withSuiteHooks handed its work a thunk that opened the pass on first use.
Opening one does no I/O: the suite attempt launches nothing until a hook
that names an engine fixture runs. The pass is now opened up front and
closed in finally, and the `opened` slot and the `hooks()` call form go.
Refs ENG-1297
* refactor(e2e): ask the registry which hooks apply to a test
The selection-time fixture check rebuilt the scope chain of a test and
filtered the file's hooks by it, which the realm already did its own way.
registry.ts now exports scopeChain(test) and hooksFor(registration, test),
and both use them.
Refs ENG-1297
* refactor(core): move the fixture types into types/fixtures.ts
types.ts grew from 1679 to 1798 lines in this PR. The fixture scope, the
worker fixtures, and what test.extend() takes (definitions and overrides)
are one coherent group that nothing else in the file defines against, so
they move to types/fixtures.ts and types.ts re-exports them. The public
surface is the same.
types.ts: 1798 lines to 1715.
Refs ENG-1297
* refactor(core): drop the redundant override branch in FixtureDefinitions
A fixture that extends one the base already has was typed three ways: a
conditional branch inside the `Extra` map of FixtureDefinitions, the
`& FixtureOverrides` intersection, and the extend(overrides) overload.
Compiling the type tests without each in turn: the intersection types an
override written beside new fixtures with type arguments, and the overload
types an override-only call without them; both fail the tests when
removed. The conditional branch does not: with it gone the tests pass, and
a base name in `Extra` is `never` again, as it was before overrides. It is
removed, and the reference's copy of the declaration follows.
Refs ENG-1297
* refactor(e2e): split fixture errors from the parser, share hookLog
fixture-names.ts parses a parameter list, and also held FixtureUseError and
declarationSite, which format an error. They move to fixture-errors.ts.
Its identifier pattern held two raw zero-width characters; they are
written as escapes now.
hookLog and LOG_MODULE were pasted into three integration tests; they are
one helper in tests/helpers/hook-log.ts.
Refs ENG-1297
* docs(e2e): name the scope rule in the selection check's summary
The summary of assertFixtureUse still listed a chain fixture named like an
engine's as an error. Such a fixture extends the built-in now; the rule
left is a declared scope that differs from the extended fixture's.
Refs ENG-1297
* refactor(e2e): take execute.ts under 1000 lines
Two more pieces that are not the attempt's own sequence leave the file.
- Holding steps for `e2e run --step`: reading the screen a hold starts on
and wiring AttemptHolds to the runner's hook move to step-hold.ts, beside
the holds they configure (holdAttemptSteps, readHeldScreen).
- The result of a finished test or setup unit is a pure function of the
pair, the verdict, the attempts, and a beforeAll failure: unitResult in
units.ts, beside pairResult.
execute.ts: 1031 lines to 956. It was 1031 on main and 1226 at the review.
Refs ENG-1297
* test(e2e): match the not-awaited message without a step label
Main's #1880 names an unlabeled step by its api alone ("gadget.hang
finished"), where the message used to quote an empty label. The suite-hook
test's pattern required a label between the two, so it failed on the merge
with main.
* feat(e2e): an override inherits auto from the fixture it extends
A fixture that extends another and does not state `auto` now has the
extended fixture's, the way it has its scope: an override of an auto
fixture is set up for every test, and one of a built-in fixture on demand.
An `auto` that differs from the extended fixture's is a COLLECTION_ERROR
naming both, worded like the scope mismatch. This matches Playwright.
It also fixes which fixtures the plan starts from. An auto fixture was a
root by its own flag, so with an auto base and its override in one chain
the base was set up and the override skipped, while the name resolved to
the override; an override that replaced the base without naming it still
left the base running. An auto fixture is now a root only where its name
stands for it: the base runs once through the override's own name, or not
at all when the override replaces it.
Refs ENG-1297
* fix(core): name the hook or fixture that left a step running
STEP_NOT_AWAITED said "the test body returned before ..." for a step a
beforeAll, afterAll or beforeEach hook, a fixture's setup or a worker
fixture's teardown left running. The recorder now keeps the owner each
step was started under, and the runner says which code runs: the pool
for fixtures, hooks and the body, the suite attempt for suite hooks, and
a hosted session for itself.
---------
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
English stays current in every change; the Japanese and Chinese
translations may lag behind, since no contributor can be expected to
update a language they don't speak. check-docs-translations.ts now warns
on outline, code, and navigation label drift instead of failing, and
fails only on what needs no language to fix.
Refs ENG-1385
"Add --no-cache to skip cached actions" reads as if the agent steps are
skipped. They still run: with the replay cache off, each step calls the
model. The quickstart in English, Japanese, and Chinese, and the Context7
rule, now say that.
The Japanese quickstart also ends the --headed and --no-cache sentences,
and the example prompt 「購入手続きのテストを追加してください」, with the
polite request form, so the two parallel flag sentences read the same.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cache): tell long-id steps apart by an identity digest under --strict-cache
An entry keeps the test id, target id, and agent name cut to 300
characters. Two steps whose names agree in their first 299 characters
stored the same provenance, so the strict rekey check took a step that
was never recorded for one whose key changed and failed it with
REPLAY_STALE.
When a name is longer than an entry keeps, the entry now also stores
identityDigest, the SHA-256 of the whole redacted names, and stepKey
compares it. A confirmed replay writes the digest into a kept entry
that predates it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cache): key by the identity digest a name that ends like a cut
bound() cuts a name to 299 characters and an ellipsis (298 after a
surrogate pair). A whole target or agent name of that shape stored no
digest, so it matched an entry recorded before the digest for another
step whose name was cut, and strict failed it with REPLAY_STALE.
boundIsAmbiguous() names both cases, and recordedProvenance writes the
digest for either.
Also pins that the digest is taken over the redacted names.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cache): measure the long-id row by the test id, and say where a name ends in an ellipsis
The test id percent-encodes the titles, so the limit is reached well
before 300 characters of title text. The row names the test id again.
The digest JSDoc names the createAgent cache key as the source of a
name that ends like a cut, and the provenance tests leave the
settlement block.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(cache): refuse an identity digest that is an array or a number
RegExp#test stringifies its argument, so ['<64 hex>'] passes the hex
pattern; the typeof check is what refuses it, and now a test pins it.
Also rewords the stepKey JSDoc.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cache): pin the no-rewrite side of the identity digest backfill
- Add a settleStagedTraces test: a confirmed kept entry that already
keeps the step's identity digest gets no store write.
- The StagedTrace JSDoc names the identity digest beside the
occurrence fields.
- The docs row no longer says "test id", which this page uses for the
app's element test ids, and names the 299 or 300 characters ending
in an ellipsis case.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(cache): pin that ambiguity is measured on the redacted names
- Test that a name a secret makes longer than an entry keeps gets an
identity digest.
- The docs row drops the ellipsis case: target and agent names are
ASCII only, and runner test ids are percent-encoded, so neither can
end in one. It says the test's file path and percent-encoded titles,
and that a confirmed read-write replay ends the exception.
- The identityDigest JSDoc names the secret-value case.
- One isOptionalDigest check serves paramsDigest and identityDigest.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(cache): pin that the backfill replaces or drops a stale identity digest
- A confirmed kept entry whose names redact differently now gets the
step's new digest, and one whose names no longer need a digest drops
it.
- Shorten the docs row to the maintainer's wording.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cache): say the backfill rewrites differing provenance, and translate the row
- The StagedTrace, completeProvenance, and settleStagedTraces JSDoc say
an entry is rewritten when its stored provenance differs from the
step's, which now includes replacing or dropping a digest.
- Test that an invalid paramsDigest is refused too, in a describe for
reading entries.
- Add the long-name row to the ja and zh cache tables.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(cache): pin that target and agent names are stored and digested redacted
- Test both fields with a registered secret: the stored name holds no
secret value, and the digest is the same for two values.
- The StagedTrace and settleStagedTraces JSDoc point at
completeProvenance instead of restating when it rewrites an entry.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cache): name each identity digest case completeProvenance rewrites
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cache): measure the long-name row by the testId in report.json
- A title is percent-encoded into the test id, so a 34-character
Japanese title already passes 300 characters. Name the `testId`
field users can see instead of "a very long title".
- Only a read-write run of this version writes the digest in, so say
so.
- Drop a test assertion on a constant, and a stray blank line.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* test(oauth): expect one refresh across worker processes
Four processes over one expired login file send four refresh requests
with the same refresh token today. Refs #1807.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): refresh a login once across worker processes
Each `e2e run` worker is its own process, and `createOAuthFetch` shared a
refresh only within one process, so N workers sent the same rotating
refresh token and the vendor rejected all but one. `FileCredentialStore`
now holds a refresh lock from the re-read of the store to the write, so a
waiting worker finds the fresh tokens and sends nothing. The 2 s poll after
a rejected refresh, which was the only recovery, is removed.
Fixes#1807
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): keep a slow refresh's lock from going stale
A refresh over the 10 s stale bound let a waiter claim the refresh lock
and send the same refresh token again. The holder now touches the lock
while the refresh runs. The docs line names a saved login, since the
environment-variable store does not share refreshes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): never take over a refresh lock another process holds
A waiter that found the refresh lock stale renamed it away, so a lock
another waiter had just created in its place was renamed too and both
held it. Waiters now take turns through a `.break` file and check the
age again while holding it, and each lock holds a token so release and
the heartbeat only touch the holder's own lock.
Each login has its own refresh lock, so a slow ChatGPT refresh no
longer holds up Grok or Copilot in another worker. A waiter that gives
up after 30 s says another worker is still refreshing, as a TIMEOUT
OAuthError, since the holder may be alive.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): take over a lock only once its holder has exited
The lock took a holder for dead once its file was 10 s old, but age
cannot tell a dead process from a suspended one, a laptop asleep
mid-refresh, or a clock change. A waiter took over a live holder's lock,
and the holder's check-then-remove release could then delete the
waiter's lock. The lock file now names its holder's host and pid, and a
waiter takes it over only when that pid is gone, at once rather than
after 10 s. The age bound stays for a lock that names no process this
host can check: another host's, an older e2e's, or one still being
written. The heartbeat is gone with the age check it fed.
A waiter now checks its deadline on every turn, so a takeover turn held
by another waiter cannot keep it waiting past 30 s.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): link a lock into place with its holder already written
A lock was created empty and its holder written after, so a holder
stopped in between had its lock taken over as nameless after 10 s, and
a failed write left a partial name that waiters took for a live holder
until it exited. The holder is now written to a file of its own and
hard-linked into place, so a lock never exists without its full name.
A file system without hard links falls back to creating the lock
directly.
A waiter now checks its deadline before every takeover, so locks of
holders that keep exiting cannot keep it past 30 s.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): take over an untouched lock whatever pid it names
With liveness as the only test, a lock naming a pid another program
had since been given was never taken over: every run failed until the
user removed the file. The holder touches its lock again while it holds
it, and a lock untouched for 10 s is taken over whoever it names. An
exited holder's lock is still taken over at once. A holder suspended
for over 10 s mid-refresh now loses its lock, so waiters never wedge.
Tests now fail without each lock branch: the token checks in release
and the heartbeat, the dead waiter's turn, the 30 s TIMEOUT, the host
and pid checks, EPERM, the linked lock, the heartbeat cleared on
release, and an expiring token another process stored. A multi-process
test runs 8 waiters through an orphaned lock. The docs say how long a
worker waits for another's refresh.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): name the pid namespace in a lock's holder
A caller in a sandbox on the same host, such as bwrap with its own pid
namespace, could not see the holder's pid, took the holder for exited,
and took over a live lock. The holder now names its pid namespace with
its host, and only a caller in the same one judges its pid.
With the heartbeat back, linking a written file into place guarded only
a holder dying between creating the lock and writing it, which the
untouched bound already covers. The lock is created exclusively again
and removed when writing its holder fails.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): keep the rotation poll for runs of an older e2e
An e2e released before the refresh lock refreshes without it, so a run
of it beside a run of this one can still rotate the token first. The
2 s poll for a token another process stored stays, now inside the lock,
so the run whose refresh was rejected picks up the other's token.
Tests now fail when the refresh sends the token it read before the
lock, when the heartbeat runs no faster than the stale bound, and when
two attempts in one process share a token. The docs name the code a
step fails with after the 30 s wait.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): give a refresh's token request 20 s
A token request that never answered held the refresh lock until its
test timed out, so every other worker gave up after 30 s where main
lost only that worker. The refresh now aborts its token request after
20 s, under the 30 s a waiter gives the lock, and fails with TIMEOUT;
the next worker then takes the lock and refreshes.
The 8-process test is gone: it passed with the takeover turn removed,
while the single-process tests catch that every time. A lock that
cannot be created now has a test, and the heartbeat test is tight
enough to catch a slower interval. The docs name the codes a step
fails with when a refresh runs out of time.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): poll for a rotated token after releasing the refresh lock
The poll for a token an older e2e rotated ran inside the refresh lock,
so on a revoked login each worker waited out the one before it, 2 s
each, and with 16 workers the last gave up with TIMEOUT instead of
LOGIN_REQUIRED. The lock now covers the re-read, the token request,
and the write, and the poll runs after it is released.
The orphaned-lock test the maintainer asked for is back, from an empty
lock gone untouched, which fails it every time without the takeover
turn. The heartbeat has a test for a lock that vanishes before it is
touched.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(oauth): poll for a token other than the one the refresh sent
The poll after a rejected refresh compared against the token read
before the lock, so no test failed when it waited for that one instead
of the token the refresh sent. The LOGIN_REQUIRED guard is back in
block form, and the changeset says the shared refresh is for a saved
login.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): never abandon a token request that may have rotated the token
The 20 s abort dropped a token request the vendor might already have
answered by rotating the token, so a late answer lost the new token and
left the stored one revoked: the user had to sign in again. A refresh
now waits for its answer however long it takes. A hung token request
again fails the other workers of that run after 30 s, which costs a run
rather than the login.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(oauth): move the refresh lock to its own module with tests that fail without the turn
The cross-process lock is general-purpose and never used the store, so it
moves from oauth/store.ts to internal/file-lock.ts as withFileLock(), with
its own tests. store.test.ts drops its module-wide node:fs mock.
- Two waiters racing for a crashed holder's lock: a second real waiter runs
its takeover inside the first one's pid check, so the test fails every run
without the takeover turn or without the re-check in it.
- A crash-loop test replaces the 8-process test: 12 processes take the lock
over and over, half the holds ending like a crash, until 300 crashes.
- The pid-namespace case that could not fail becomes a Linux check that a
held lock names this host's pid namespace.
- claim() writes the whole token with writeFileSync.
- The release JSDoc says a holder paused past the stale bound can remove the
lock of the waiter that took over.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(oauth): describe the symptom the refresh fix removes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(oauth): pin the re-read inside the refresh lock with a deterministic test
The only test that failed without the re-read was the 4-process one, which
missed it when the workers booted far enough apart. The new test stores a
fresh token while the refresh waits for the lock and expects no refresh.
The refresh now returns the renewed login, or the rejected one with the
token it sent, so the LOGIN_REQUIRED poll no longer guards a value that is
always set. The crash-loop lock test says it is a soak check, and new long
lines are wrapped.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(oauth): cover refresh failures other than LOGIN_REQUIRED and a failed stat of the turn
- A FLOW_FAILED from the token request passes through as it is, with no
poll for a rotated token.
- A waiter that cannot stat a live waiter's turn file leaves it.
- Tests that start worker processes kill them when the test ends, so a
hung worker is not left running after a timeout.
- The module JSDoc says only a holder on this host and pid namespace is
taken over at once.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(oauth): reuse sleep in the lock wait and document exclusive
- The lock's retry wait uses sleep from internal/time.ts.
- FileCredentialStore.exclusive has JSDoc.
- The docs paragraph wraps like the rest of the page.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(oauth): import sleep from @e2e-dev/core after the core move
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>