argent-create-e2e — Skillopedia

Create an Argent e2e test An Argent e2e test is a replayable sequence in ( is still read). For a saved QA test case, ticket, or acceptance criterion, load first. It adds deterministic setup, acceptance evidence, and two-pass proof. Read the relevant reference - Before creating or changing an e2e test, read Live authoring completely. - When polishing, composing, or manually reviewing YAML, read E2E YAML. For Vega, read its platform limits before recording remote or keyboard tools. - E2E tests run on physical iPhones (an iOS entry with kind ), but replay never auto-binds one, even when no simul…

} }\n```\n\n### The runner tree is not the discovery tree\n\nYAML selectors and live discovery use different screen projections:\n\n| Platform | Runner tree | `describe` / `await-ui-element` | Important difference |\n| -------- | --------------------------------------------------------- | ------------------------------- | ------------------------------------------------------ |\n| iOS | projected UIView hierarchy | accessibility tree | `native-full-hierarchy` is raw; nodes and roles differ |\n| Android | full accessibility hierarchy | trimmed interactables | Discovery can omit testID containers or merge nodes |\n| Chromium | filtered DOM nodes with id, label, value, click, or focus | shorter DOM walk | Projections and node limits differ (12,000 vs. 5,000) |\n| Vega | toolkit page source | same source | Same elements, different shape |\n\nOn iOS, Android, and Chromium, an id absent from `describe` can still resolve in an e2e test. Verify it in a scratch fragment. Chromium exposes password fields to the runner as `[password]`; select them by id or role.\n\nThe recorder rechecks each successful `await-ui-element` against the runner tree. Follow any `message` warning and replay each conversion. On Vega, a mismatch usually means the screen changed. A `text` check can also select different elements from the same source. See [Live waits and checks](live-authoring.md#live-waits-and-checks).\n\n**On iOS, a `launch:` step also decides which app the runner reads.** A successful `launch:` pins later runner-tree reads to that app, so a read probes only that app instead of fanning out over every connected one to find the frontmost. A pinned read still refuses, naming the reason, when the app has no foreground presence left, when it stops answering after an earlier read got through, when its devtools connection dropped, or when the pinned id is a `com.apple.*` system app.\n\nAny raw `tool:` step ends the pin, because its effect on the screen is opaque to the runner, and reads auto-detect the frontmost app again until the next `launch:` re-pins. A tool that cannot change the foreground app leaves the launched id as an unpinned fallback, which takes the read only when auto-detection times out and the launched app vouches for itself with a probe of its own. `launch-app`, `restart-app`, `reinstall-app`, `open-url`, and `button` drop even that; `launch-app` and `restart-app` replace it with the app they just started, still unpinned. Nested `run:` fragments inherit both the pin and its clearing.\n\nSo on iOS recording and replay can read different apps, not only different projections: recording has no run state and always auto-detects the frontmost connected app, while a replay read between a `launch:` and the next raw `tool:` step reads the launched app.\n\n**On iOS, never copy a `role` from `describe` into a YAML selector.** The runner derives iOS roles from the UIView class name and `describe` from accessibility traits, so a React Native `Pressable` (class `RCTView`) is `AXGroup` to the runner and `AXButton` to `describe`. Select on `id`/`text`, or confirm the role against the runner's own tree.\n\nWhen several nodes match, the directive decides:\n\n- **Actions** (`tap`, `long-press`, `type`, `scroll-to`, `pinch`, `rotate`) take the most specific visible match: exact text/id beats substring, then the smallest frame, then reading order.\n- **Conditions** (`await`, `assert`) do not rank. `exists`/`visible` hold if any match qualifies and `hidden` only if none does; `text` reads the first visible match in reading order.\n\nA container that aggregates a child's text therefore splits them: `tap` hits the leaf while `text.in` reads the container, so `equals` fails against correct UI. Use an `id` or a [relational scope](#relational-scopes) when an action and a check must agree, and a stricter selector when ranking can still choose the wrong element.\n\n### Relational scopes\n\nYAML selectors support frame-based `within`, `after`, and `next` in every selector slot. Live `await-ui-element` does not support them.\n\n```yaml\n- tap: { text: Delete, within: { id: profile-card } } # inside a container\n- assert: { visible: { role: Button, after: { text: Danger zone } } } # any follower\n- tap: { role: Switch, next: { text: Wi-Fi } } # nearest matching follower\n```\n\n`within` means visual frame containment, not source-tree ancestry. Overflowing children and anchored popovers can fall outside it. `after` and `next` use top-to-bottom, left-to-right reading order as the user sees the UI. This is also true on a landscape UI, for example a rotated iPhone or an unfolded foldable. A target cannot satisfy its own `within`, `after`, or `next` anchor. The synthetic root never counts.\n\n`next` finds the nearest matching follower and skips non-matches. It can therefore reach the next row when the intended row lacks a control. Prefer a stable row container with `within`, or assert the row-local control first.\n\nScopes can combine and nest, with at most six scope keys. Use strict selectors for anchors. Scope through a trusted container when a missing control must fail instead of reaching another row.\n\n## Directives\n\nDirectives stop the test on failure and skip later steps. The available directives are `launch`, `tap`, `long-press`, `swipe`, `type`, `scroll-to`, `pinch`, `rotate`, `fold`, `await`, `assert`, `wait`, `snapshot`, `run`, `script`, `when`, `echo`, and `tool`.\n\n`fold` folds or unfolds a foldable iOS simulator or Android emulator. Write a posture (`fold: closed`, `fold: half-open`, `fold: open`) or an angle from 0 to 180 (`fold: 120`). The step waits until the device accepts input again. A recorded `fold` tool call becomes a `fold:` step. After a `fold` step:\n\n- The coordinates change with the panel. Selectors resolve against a new tree.\n- A `snapshot` baseline is valid only for the posture that made it.\n- iOS: unfolded, the UI is landscape. `swipe` and `scroll-to` directions and the reading order stay as the user sees the UI. Coordinates stay in the space of the `describe` frames.\n- iOS: a fold between two angles that are not `closed` or `open` can keep the current panel. The step passes, and the report names the panel. To change panels, fold to `closed` or `open`.\n\nUse the launch map for cross-platform tests. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. `ios:` also accepts `{ app, args }`; a simulator passes `args` to the app at launch. A launch that declares no id for the run's platform is an error, not a cue to switch platforms. A run on a remote simulator uses the `ios:` id, or the `native:` id when the map has no `ios:` key, so no test needs a key for a remote run. On iOS, a successful launch also pins later tree reads to that app until the next raw `tool:` step, so read [The runner tree is not the discovery tree](#the-runner-tree-is-not-the-discovery-tree) when a read describes the wrong screen.\n\n```yaml\n- launch: { native: com.acme.app, chromium: ../../app }\n- launch: { ios: com.acme.app, android: com.acme.app.android, chromium: ../../app }\n```\n\nAn Android app that needs a non-launcher activity has no `launch:` form. Record `restart-app` with `activity` and keep the test as a fragment.\n\nIn a `scroll-to` map, put the selector under `target:`. The map supports `up`, `down`, `left`, and `right` directions. The default is `down`; set it explicitly to reach a target above the viewport or along a horizontal carousel. If the target is already visible, the step is a safe no-op. `tap`, `type`, and `long-press` do not auto-scroll. Add `scroll-to` when the target can be off-screen. Use `within` for a nested scroller.\n\n### `swipe`\n\n`swipe` is one semantic finger flick where the gesture itself is the action: dismiss a card, page a carousel, open a drawer, pull-to-refresh: `- swipe: left`, `- swipe: { from: Card, direction: left }`, `- swipe: { by: { y: -0.4 } }`.\n\n**Never use `swipe` to scroll.** Whenever the goal is \"bring X on screen so the next step can act on it\", write `scroll-to: \u003cX>` instead: it is goal-seeking (stops exactly when the target appears), momentum-free, and a no-op if the target is already visible.\n\n**`direction` is the finger's travel** (the Maestro convention): `swipe: left` flings content leftward and reveals what is to the right, the opposite sense of `scroll-to`'s content direction. Declare exactly one travel:\n\n- `direction` - Maestro-compatible screen geometry, with edge-gesture-safe start and end points.\n- `by: { x?, y? }` - signed 0-1 screen fractions, one axis or both for a diagonal.\n- `to: \u003ctarget>` - an explicit endpoint, selector or point.\n\n`from` anchors the start on a selector or `{ x, y }` point. Without it the start is the direction preset, or screen centre for `to` and `by`.\n\nAll three must clear a 0.03 minimum travel on the combined start-to-end vector; shorter reads as a tap and will be rejected/fail.\n\nAnchoring decides how a travel that does not fit is resolved:\n\n- `direction` keeps the preset magnitude from where the finger lands (0.8 of the width for `left`/`right`, 0.7 of the height for `down`, 0.4 for `up`), clamped at the screen edge. It fails only when the clamp leaves it under 0.03, so a drawer handle or bottom sheet near the edge still swipes.\n- `by` delivers its exact delta or nothing. With `from`, a delta that runs off-screen fails.\n\nOnly the direction presets carry OS-edge margins. A resolved `from` point is used verbatim, so use `from` for app-level gestures only and write system-edge gestures such as system back as raw `tool: gesture-swipe` steps.\n\n`momentum: false` removes the fling, so the swipe lands where the finger stops. The default `momentum: true` is a natural flick that flings on. `duration` (ms) is the travel time: default 300, minimum 150. A shorter gesture gives the content too few frames to track the travel, so it overshoots and may fling backwards. Every `swipe` then waits for the tree to settle, best effort, so its momentum does not swallow the next step's touch.\n\nOn Chromium a swipe is a mouse drag (`gesture-drag`), so a `from` on an `\u003cimg>`, an `\u003ca href>` or a `draggable=\"true\"` node starts the browser's native drag-and-drop: the page gets `pointerdown` then `pointercancel` and sees no travel. On Vega, `swipe` fails upfront like the other touch directives.\n\n`type` presses Enter in a second `keyboard` call unless `submit: false`. A polished focus tap plus one text-only `keyboard` call usually needs `submit: false`. Store external values as `{{secret:NAME}}`. The runner uses the first source that defines the name: environment `ARGENT_SECRET_NAME`; project `.argent/secrets.env`; project `.env.local`, then `.env`; then `~/.argent/secrets.env`. Over a link with `forward-secrets` on, the same sources on the client's machine come first. The two `secrets.env` files accept the bare `NAME`, but the shared dotenv files expose only `ARGENT_SECRET_`-prefixed keys, so a bare `NAME=…` in `.env` or `.env.local` stays unresolved. The runner redacts every resolved value, so do not use a placeholder for content a report must show.\n\nA **selector-less gesture** (a coordinate `tap`/`long-press`/`swipe`, or a `pinch`/`rotate` with no `on:`) resolves no frame, so a tree source it cannot read does not fail it. It settles best effort, dispatches anyway, and the step **passes carrying a warning** that quotes the source's own error. That green says the gesture was sent, not that it landed: one aimed at a moving element can miss it entirely. Restore the tree source, usually by relaunching the app so the instrumentation loads. Accept the warning only where the app serves no tree at all, and put an explicit `wait:` before a gesture that follows a transition. The first such gesture proves the outage and later ones spend that verdict without paying the settle window again. A tree read that comes back, or a relaunch, retires that verdict, which only makes the next gesture pay a fresh window, and it warns again if the source is still down.\n\n## Verification conditions\n\n```yaml\n- await: { visible: { id: settings-screen } }\n- await: { hidden: { id: loading-spinner }, timeout: 15000 }\n- assert: { exists: { id: notifications-toggle } }\n- assert: { text: { in: { id: preference-status }, equals: Enabled } }\n- assert: { text: { in: { id: result-count }, matches: '^\\d+ results

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

} }\n```\n\n`text.in` locates one element. It compares that element's rendered and descendant text with exactly one comparator:\n\n- `contains`: case-insensitive substring.\n- `equals`: case-insensitive full match.\n- `matches`: case-sensitive JavaScript regex.\n\nUse `equals` or an anchored regex when boundaries matter. For example, `contains: \"Taps: 3\"` also matches `Taps: 30`.\n\nUse `await` for an outcome that can take time. Its default is 7500 ms. Add a larger timeout only after the default expires. Use `assert` for settled state. It has a fixed 1000 ms grace and rejects `timeout`.\n\nA negative condition proves only that the current tree has no visible match. It also passes before the element appears, for a typo, or on the wrong screen. First prove the containing screen and the same stable selector as `visible`. Then perform the removing action and check `hidden`. Prefer an additional positive replacement or empty state.\n\n## Prove a navigation: identity, then readiness\n\nEvery screen change needs both checks:\n\n```yaml\n- await: { visible: { id: profile-screen } } # identity\n- await: { idle: true } # readiness\n```\n\nThe identity selector must exist only on the destination. A dropped tap can leave the source screen idle. A destination element can enter the tree before its animation finishes. Therefore neither check replaces the other.\n\n### `idle` readiness\n\n`idle` waits until the screen has content and stops changing in both the UI tree and pixels.\n\n```yaml\n- await: { idle: true, stableFor: 400, timeout: 9000 }\n```\n\n`stableFor` (default 250) is how long stillness must hold. `timeout` (default 7500) is the budget for the whole wait, and parse rejects one that cannot contain a settle. A settle spans three reads across two 200ms polls. The floor is the longer of `stableFor` and the 400ms a settle spans, plus the 200ms of budget the closing round needs to start. The hold runs during those polls rather than after them, so only the longer of the two counts: the default 250ms hold needs 600ms and an 800ms hold needs 1000ms. Stillness is measured across intervals, so `stableFor: 0` means the first two agreeing intervals, not the first read. `idle` has no assert form and no `when:` form.\n\nIt **never fails a run.** Every outcome short of a clean settle passes with a warning, because readiness is not an acceptance criterion. Read that warning rather than stepping over it:\n\n- **the screen never held still**: it spent the timeout and was still moving on the last interval. A video, shimmer, carousel, or live text stays healthy while moving, and a load that never finished looks identical.\n- **a small part of it was still changing**: a spinner, caret, or progress dot moved through the hold. Too small to count as the screen moving, so the settle completed anyway.\n- **the screen was still for the last Nms**: the wait ran out mid-hold, so no settle was confirmed. It names the term that was short: a second agreeing interval, or the rest of `stableFor`. Raise this step's `timeout:`, because the wait was too short rather than the screen too busy.\n- **the tree stayed empty**: the screen rendered no accessible content: a canvas or video surface, or a screen that never arrived.\n- **settled on the UI tree alone**: no screenshot pair could be read, so presentation-layer animation was never waited out.\n- **too few reads**: a settle needs three reads across two intervals and this step got fewer, so it ended with no evidence either way.\n\nOnly a tree source this step could not read stops the run, as an errored step: one still failing when the wait ends, one that wedges after answering, one that answers with an empty tree it flags as degraded (an unattached Vega toolkit, an AX service asking to be relaunched), or one that never answers (raise `timeout` before suspecting the app). The run is then not ok and every later step is skipped. A single failed read is not that: the hold restarts from the next good read. The same outage stops no [selector-less gesture](#directives), which needs no frame and passes with its own warning instead.\n\n`idle` proves readiness only and never identifies the screen, so it cannot serve as acceptance evidence or replace the identity gate. Gate the next action on a stable element. Add `idle` during polish after each screen change, not after every step.\n\n## Optional divergences\n\nUse `when:` only for optional setup or an interstitial that reconverges:\n\n```yaml\n- when: { visible: { text: Got it } }\n steps:\n - tap: { text: Got it }\n```\n\nThe guard accepts one `exists`, `visible`, `hidden`, or `text` condition, or `{ platform: ios|android|chromium|vega }`. A run on a remote simulator matches `ios`. UI guards use the short assert grace and reject `timeout`. There is no `else` or per-step `optional`. Put separate behavioral paths in separate tests. Never place a required acceptance check inside `when:`.\n\n## Composition and platform limits\n\nA `run:` target is a YAML path resolved against the directory of the test file containing the step, so `../shared/login.yaml` reaches a sibling directory rather than the project root. The `.yaml` suffix is optional: `run: login` and `run: login.yaml` both name `login.yaml` beside the test. A bare name that is missing beside a test in `.argent/e2e/` is also looked up in `.argent/flows/`, and the reverse. The recorder writes a nested test that is only in the other directory by its path, for example `run: ../flows/login.yaml`.\n\n`run:` steps and `tool: e2e-execute` steps make one chain of tests. A step that closes a cycle in that chain, such as a test that runs itself through `tool: e2e-execute`, fails with a reason that contains `cyclic e2e test reference:`. A step that makes the chain longer than 20 tests fails with a reason that contains `max run depth exceeded`.\n\n- iOS and Android can run fragments or standalone tests inline. A nested standalone launch restarts its app.\n- Chromium boots one instance per launch **step**, not one per run. The leading launch (the test's own, or the one its leading `run:` chain reaches) boots before step 1, unless you pinned the run with an explicit `device`, where it only attaches. Every later launch boots a fresh instance, moves the run onto it, and tears down the instance the run already owned for that app path. Nesting a Chromium standalone test with its own launch is therefore the supported way to give a sub-scenario its own restart. Chromium rejects `pinch` and `rotate`. Use the app's own zoom or rotate controls.\n- Vega uses `tool: tv-remote` and raw `tool: keyboard`. The touch directives (`tap`, `long-press`, `swipe`, `type`, `scroll-to`, `pinch`, `rotate`) are unsupported. Gate focus and navigation results with `await`.\n- HarmonyOS: read `references/harmonyos.md` of `argent-device-interact` before writing a test for it.\n\n## Local scripts\n\nUse a local `.mjs` script only when the user requests one. Record it with `e2e-add-script` at the point where it must run.\n\n```yaml\n- script: { path: ../../scripts/seed-order.mjs }\n- script: { path: ../../scripts/seed-order.mjs, timeout: 60000 }\n```\n\nUse the map form shown above. A bare `script: scripts/seed.mjs` is invalid.\n\n- **`path`** is relative to the test file that contains the step. Include `.mjs` and match the file name's letter case.\n- **`timeout`** is optional and uses milliseconds. The default is 30000. The minimum is 100.\n\nOver a link (`argent link` or `ARGENT_TOOLS_URL`, also to 127.0.0.1), `e2e-add-script` refuses the call, and a replay rejects a test with a `script:` step. Record and replay a test with a script without a link.\n\nIf a script fails, check its changes before you retry.\n\n## Snapshots and CLI runs\n\n`argent e2e run \u003cname> [--device \u003cid>] [--platform ios|android|chromium|vega|ios-remote] [--update-baselines] [--output \u003cdir>] [--json]` runs without an LLM and exits non-zero on failure.\n\nA screenshot is human evidence. A `snapshot:` is executable visual verification. A missing baseline or excessive mismatch fails. A `cropOn` size change also fails. Use snapshots for color, layout, size, spacing, typography, clipping, overflow, images, icons, or stable component appearance. Use full screen for global changes and `cropOn` for one component.\n\nDo not use a snapshot as the only proof of navigation, persistence, data, accessibility state, logs, or network behavior. Avoid unstable timestamps, live data, ads, animation, and device drift. First establish deterministic state, identity, and readiness.\n\nBaselines live beside the test, under `.argent/e2e/__baselines__/\u003cname>/` and are keyed by platform and full-capture geometry; `cropOn` also contributes its selector. A run on a remote simulator uses `ios` in the key, so it uses the same baseline as a local iOS run with the same capture geometry. Seed from a known-good state with `--update-baselines`. A test that a `tool: e2e-execute` step runs keeps its own baselines, and `--update-baselines` updates them too unless the step sets `updateBaselines` itself. A run on a remote simulator with `--update-baselines` rewrites the same baseline file that a local run uses, and its step reason says that a remote simulator wrote it. Inspect every baseline and require user review. Do not commit it yourself. Baseline creation or update is not a test pass. Never update a baseline only to make a diff pass. The default `maxMismatch` is 0.5 percent.\n\nPin `--platform` and `--device` for iOS, Android, or Vega. For Chromium the device class is the window's own pixel size, which the app sets and no launch argument changes: pass `--platform chromium` and omit `--device` so the runner boots the declared app path instead of attaching to a running window of another size. A window sized from host or session state produces a key CI cannot reproduce, and the step fails for a missing baseline. The runner pins mobile status bars during visual runs. `--output \u003cdir>` writes failed baseline, current, and diff images under `\u003cdir>/\u003cname>/` for CI artifact upload.\n\n## YAML safety\n\nQuote strings containing `#`, `:`, or quotes. Quote numbers and `true` or `false` in text slots. Use single quotes for regexes with backslashes. Parsing rejects invalid directives, selectors, regexes, `else`, unsupported options, and standalone tests that also declare `executionPrerequisite`.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":26676,"content_sha256":"4c61b86c7607f2f5d4b0ea3763eb846d3d0f9207798ec092d3debe9937de2c83"},{"filename":"references/live-authoring.md","content":"# Live authoring\n\nRead this file before creating or changing an e2e test. Exercise the saved path through the recorder. Perform syntax cleanup only after finishing.\n\n- [Live authoring](#live-authoring)\n - [Recorder contract](#recorder-contract)\n - [Start in the correct order](#start-in-the-correct-order)\n - [iOS, Android, and Vega standalone tests](#ios-android-and-vega-standalone-tests)\n - [Chromium standalone tests](#chromium-standalone-tests)\n - [Fragments](#fragments)\n - [Record the first walkthrough](#record-the-first-walkthrough)\n - [Record identity, then readiness, after every navigation](#record-identity-then-readiness-after-every-navigation)\n - [Record absence in three steps](#record-absence-in-three-steps)\n - [Taps](#taps)\n - [Typing](#typing)\n - [Scrolling and swiping](#scrolling-and-swiping)\n - [Live waits and checks](#live-waits-and-checks)\n - [Wrong turns](#wrong-turns)\n - [Finish and polish](#finish-and-polish)\n - [Worked example](#worked-example)\n - [Blocking audit](#blocking-audit)\n - [Replay](#replay)\n\n## Recorder contract\n\n`e2e-add-step.command` is an MCP tool name. `args` is a JSON string, not an object. Omit `args` for a no-argument tool.\n\n```text\ncommand: \"gesture-tap\"\nargs: \"{\\\"udid\\\":\\\"DEVICE\\\",\\\"x\\\":0.5,\\\"y\\\":0.35}\"\n```\n\nA recorded `e2e-execute` has two names. The top-level `name` identifies the recording. `args.name` identifies the sibling test captured as `run:`.\n\nWhen the user requests a script, call `e2e-add-script` at the point where it must run. Read [E2E YAML: Local scripts](e2e-yaml.md#local-scripts) first. If the call fails, check its changes before you retry.\n\nOver a link, `e2e-add-step` refuses a call whose step a replay over the same link rejects, and runs nothing. It also refuses an `e2e-execute` call whose test does not pass. That test can have changed the device before it stopped. In both cases the recorder records no step. See [Replay](#replay) for the steps that a replay over a link rejects.\n\nObey these lifecycle rules:\n\n1. Pass the same `name` and absolute `project_root` to every recording tool.\n2. Choose a name unique to the task. Another caller can take over the same pair without an ownership check. The pair is keyed by the file the filesystem resolves to, not the spelling you passed, so a differently-cased name or a symlinked `.argent/e2e` collides too. That collision is reported: the second start says `restarted`, and the first recording's next call fails naming both spellings.\n3. Give concurrent recordings separate devices. Their files are isolated, but their live device actions are not.\n4. Treat `e2e-start-recording` as destructive. It always truncates the named YAML, including a finished or committed test. `restarted` reports only a displaced live take.\n5. If a call says the recording is inactive, do not restart under that name. The completed take can still be on disk. Copy it aside or record under a fresh name.\n6. Inspect `toolResult`, `message`, and `recorded` after each call. A call that errors records nothing, but a call that returns normally while reporting an unmet condition **does** append the step, and `message` says the step was added either way. A failed `e2e-add-script` call appends nothing. `await-ui-element` is the case that turns up in practice (see [Live waits and checks](#live-waits-and-checks)). Only `e2e-start-recording` and `e2e-finish-recording` return the whole YAML as `flowFile`. A step call returns `recorded` (one summary line for the step it appended) plus a running `stepCount`. Read `recorded`: the recorder does not always store the tool call you made, and that line is where a rewrite shows up. To see the whole file mid-recording, read it at `savedTo`. A `savedTo` that comes back `null` means the write failed on your side. The step is still in the recording, so continue: the next step rewrites the whole file, and `e2e-finish-recording` returns `flowFile` regardless.\n7. Edit or reorder the YAML only after `e2e-finish-recording`. A recording over a link, also to 127.0.0.1, overwrites edits made during the recording.\n\n## Start in the correct order\n\n### iOS, Android, and Vega standalone tests\n\n1. Call `e2e-start-recording` before launching or touching the app.\n2. Record a plain `restart-app` as the first action that is neither an echo nor a script. Pass only the device id and app id. The recorder converts it to `launch:`.\n3. Record `await-ui-element` for the real first screen immediately after restart.\n\nExtra restart arguments prevent `launch:` conversion. An Android `activity`, for example, leaves a raw tool step and therefore a fragment. On iOS, `launchArgs` is the exception: it records as `launch: { native: \u003capp id>, ios: { app, args } }`.\n\nDo not use splash content as a selector or landmark. Wait for the first real screen.\n\nOn iOS, only `restart-app` guarantees an instrumented launch. `launch-app` can foreground an uninstrumented process. Use [iOS selector recovery](reliability-and-recovery.md#ios-selector-recovery) when the tree is missing.\n\n### Chromium standalone tests\n\n**The app sets the window size; no boot argument overrides it.** Electron ignores `--window-size`: the size comes from the app's own `BrowserWindow` options, and Argent never resizes the window. Boot a fresh target with `boot-device` and `electronAppPath`, then take one `screenshot` and record its pixel dimensions: that capture size is the snapshot device class ([E2E YAML: Snapshots](e2e-yaml.md#snapshots-and-cli-runs)) and must match when CI replays. If the app sizes its window from host or session state, say so in the report.\n\nAfter boot, start the recorder before the first in-app action. Record the first-screen wait. `restart-app` has no Chromium support, so the call errors and records nothing, and a recorded Chromium test is always a fragment: its launch is written in during polish rather than captured, and any `executionPrerequisite` the recording declared must go with it. A launch-first test must not carry one. During polish, add the matching launch:\n\n```yaml\nsteps:\n - launch:\n chromium:\n path: ../../app\n args: [\"--enable-feature-flag\"]\n```\n\nThe path is relative to `.argent/e2e/`. Copy the live boot arguments verbatim, and omit `args` when the boot passed none. This packaging exception represents the boot already exercised live. It does not permit a rehearsed UI path.\n\n### Fragments\n\nStage the entry state before recording. Then start with a precise `executionPrerequisite` that names UI, account, and platform state. Do not store a device id. Start recording before the fragment's first interaction.\n\n## Record the first walkthrough\n\nFor Vega, first read [E2E YAML: Composition and platform limits](e2e-yaml.md#composition-and-platform-limits). Vega is remote-driven and does not use touch gestures.\n\nReach each screen through the app's UI. Do not replace tested navigation with `open-url`. Starting the app is not navigation.\n\nFor every action:\n\n1. **Discover without mutation.** Use `describe`, iOS native discovery, `debugger-component-tree`, or `screenshot`. Do not record discovery or `debugger-*` calls: `port` is not a device-bind key, so a recorded one replays against whatever Metro owns that port.\n2. **Choose a durable target.** Prefer a stable id, then stable text or an accessibility label. On iOS, use native discovery for ids that trimmed accessibility output omits.\n3. **Add an echo.** Name the current state, action, and expected outcome before the action can fail.\n4. **Execute through `e2e-add-step`.** Inspect the result and the `recorded` line immediately.\n5. **Verify immediately.** Record outcome checks when their states first appear. After navigation, prove identity then readiness: record the identity check live, and add the readiness gate during polish.\n\n### Record identity, then readiness, after every navigation\n\n1. Record `await-ui-element visible` on an element unique to the destination.\n2. If a specific control marks application readiness, record another visible wait on that control before the next action.\n3. During polish, add `await: { idle: true }` after the identity check.\n\nA shared tab bar, source element, or positional id does not prove navigation. `idle` cannot identify the screen or prove application data is ready. Keep the control wait because asynchronous loading can continue after stillness. If the screen intentionally moves, disclose it and gate the next action on a stable element. Read [E2E YAML: Prove a navigation](e2e-yaml.md#prove-a-navigation-identity-then-readiness) for the directive semantics.\n\n### Record absence in three steps\n\nUse the same stable selector for both checks:\n\n1. Record it as `visible`.\n2. Record the action that removes it.\n3. Record it as `hidden`.\n\nWithout step 1, `hidden` also passes for a typo or an element that never existed. A role-only or regex-only first locator does not establish a specific element.\n\n### Taps\n\n`e2e-add-step` cannot receive a YAML selector directly. Discover the element first, then record `gesture-tap` at its frame center; the live coordinates are transport for the gesture, not a final locator. The recorder reads the pre-tap tree and derives the selector in a fixed order (`id`, then `text`, then `role`), giving three outcomes. Read the `recorded` line after every tap, because only two of them warn. It names the derived form (a selector map, or the kept point):\n\n1. **`tap: { id: ... }` or `tap: { text: ... }`**: the good case.\n2. **`tap: { role: ... }`, appended with no warning.** An icon-only button with neither id nor visible label lands here. `role` matches as a case-insensitive substring, so a replay screen holding a second control of that role can win the [ranking](e2e-yaml.md#the-runner-tree-is-not-the-discovery-tree) and the tap reports a pass on the wrong control.\n3. **A kept raw point**, with a warning naming the reason and the retarget.\n\nTreat outcomes 2 and 3 alike. Restore the source screen with direct MCP calls, record a corrected tap, then remove the weak step after finishing. Keep a point or a bare role only through the [coordinate fallback gate](reliability-and-recovery.md#coordinate-fallback-gate).\n\nNever tap the on-screen keyboard through the recorder. Some platforms expose it as one large node, so replay can tap the wrong key while reporting success. Record text with `keyboard`.\n\n### Typing\n\nRecord the focus tap, then record `keyboard` with `text`. A `keyboard` call carries `text` or `key`, never both. To submit, record a second `keyboard` step with `key: \"enter\"`. Verify the complete value with `describe` or an app validation marker.\n\n**Never `describe` or `screenshot` a non-secure field you just filled from `{{secret:…}}`.** Only a password field is redacted; a plain text input hands the resolved value back into your context, and an API key or token typed into one is the ordinary case. Submit or navigate away first, then verify the resulting screen.\n\n**`describe` reports focus on Chromium only.** iOS and Android leave it unset (it is a Vega/D-pad signal there), so those platforms have no live pre-typing focus check, and the value check afterwards is what proves the keys landed. On Chromium, read `focused` before recording `keyboard`.\n\nIf characters are lost, restore the field with direct calls. Do not record a duplicate typing step. Polish the valid pair into `type:`. Its replay focus wait reads the runner's own tree, which does report focus on iOS, Android, and Chromium, but an unconfirmed poll falls through to typing rather than failing, so retain the committed-value check. Store credentials as `{{secret:NAME}}`. Never record a literal credential.\n\n### Scrolling and swiping\n\nRecord the required live gesture. During polish:\n\n- Convert element-seeking movement to selector-based `scroll-to`.\n- Convert a swipe that is a gesture in its own right - swipe-to-dismiss, paging a carousel, revealing a row action - to `swipe:`, anchoring `from` on the gesture's **subject** (the card being dismissed, the row being revealed), not on whatever content happened to be under the finger.\n- Retain a raw gesture tool only for what `swipe` deliberately doesn't express - an edge swipe (system back), a multi-touch `gesture-custom`, or exotic velocity control.\n\nFor every retained raw gesture, add an echo and a recorded result check.\n\n### Live waits and checks\n\nRecord `await-ui-element` through `e2e-add-step`. The recorder writes the step even when `toolResult.success` is false. Read `success` and `cause` after each check:\n\n- `unmet`: The tree was readable, but the condition was false. Restore the expected state or correct the selector or timeout. Record the check again, then delete the failed step after `e2e-finish-recording`.\n- `unreadable`: The wait ended without a trustworthy read. Restore the tree source and record the check again. Keep the failed step: the condition is unknown, not false.\n- `cancelled`: The caller stopped the wait. Record the check again. Keep the failed step: the condition is unknown, not false.\n\nOnly `unmet` disproves the condition. Never delete a step during the recording.\n\nA stale `hidden` whose selector matches nothing replays as a silent pass: the unfalsifiable gate that [Record absence in three steps](#record-absence-in-three-steps) exists to prevent. Never proceed as though the gate passed. See the `await-ui-element` section of `argent-device-interact` for the full live condition and selector reference.\n\nA wait inside `run-sequence` gets no recorder warning. Inspect the nested result. Any `success: false` fails the sequence during replay.\n\nThe live tool and e2e runner use [different trees](e2e-yaml.md#the-runner-tree-is-not-the-discovery-tree). After a successful wait, the recorder checks the same condition on the runner tree:\n\n- No warning: The condition holds on both trees.\n- Mismatch: For `text`, first rule out a selector that matches more than one element. Then rule out a changed screen. If the trees really differ, keep the raw `await-ui-element` step: it replays on the tree it passed on.\n- Unreadable, slow, or cancelled check: The conversion is unknown. Restore the source or re-record before conversion.\n\nA warning does not reject the step. `e2e-finish-recording` repeats each warning below its step and reports dropped warnings.\n\nDo not edit YAML before finishing because edits can drop recorded verdicts. If the finish reports drops, record the waits again. Replay every conversion. Keep a raw tool only for `pollIntervalMs`, `bundleId`, or a cross-tree mismatch.\n\n### Wrong turns\n\nStop immediately. Restore the last valid screen with direct MCP calls, not `e2e-add-step`. Continue only from verified state. Remove the bad step after finishing. If recovery changed or skipped meaningful behavior, re-record that portion live.\n\n## Finish and polish\n\nCall `e2e-finish-recording`, then read the saved YAML. Apply only meaning-preserving conversions:\n\n| Recorded form | Finished form |\n| ------------------------------------------ | ------------------------------------------------------------------ |\n| focus tap + `tool: keyboard` | `type:` |\n| text `keyboard` + `key: enter` `keyboard` | submitted `type:` without Enter in its text |\n| `tool: await-ui-element` | `await:` or `assert:` |\n| element-seeking movement | `scroll-to:` |\n| `tool: gesture-swipe` as the action itself | `swipe:` with `from` on the gesture's subject |\n| coordinate tap or long-press | strict selector after the fallback gate |\n| `tool: gesture-pinch` | selector-based `pinch:` with `scale = endDistance / startDistance` |\n| `tool: gesture-rotate` | selector-based `rotate:` with `by = endAngle - startAngle` |\n| sibling `tool: e2e-execute` | recorder-captured `run:` |\n\nCopy the recorded `selector:` map when you convert a wait. Do not use the loose bare-string form. E2E YAML accepts `identifier`; rename it to `id` only for style. Convert `textMatch: equals` to `equals:` and other text checks to `contains:`.\n\nOnly these unrecorded insertions are allowed, at states observed live:\n\n- A planned `snapshot:` for pixel-level evidence.\n- `await: { idle: true }` after a navigation identity check.\n- The Chromium launch that packages the live boot.\n\nKeep raw forms only when conversion changes behavior. Examples include point-anchored or panning pinch, an edge swipe or one with exotic velocity control, or rotation with a tested start angle, radius, pivot, duration, or speed. Keep screenshots for human evidence. Use `snapshot:` for automated visual comparison. Read [E2E YAML](e2e-yaml.md) for syntax.\n\nIf polish reveals a missing action or structural check, restore its preceding state and record it. Do not add remembered behavior directly to YAML.\n\n## Worked example\n\n`TEST` below abbreviates `name: \"open-settings\", project_root: \"/Users/dev/AcmeNotes\"`. Repeat both fields in every call.\n\n```text\ne2e-start-recording { TEST }\ne2e-add-echo { TEST, message: \"Restart Acme Notes; expect Home\" }\ne2e-add-step { TEST, command: \"restart-app\", args: \"{\\\"udid\\\":\\\"ABC\\\",\\\"bundleId\\\":\\\"com.acme.notes\\\"}\" }\n# captured as: - launch: com.acme.notes\ne2e-add-step { TEST, command: \"await-ui-element\", args: \"{\\\"udid\\\":\\\"ABC\\\",\\\"condition\\\":\\\"visible\\\",\\\"selector\\\":{\\\"identifier\\\":\\\"home-screen\\\"}}\" }\ne2e-add-echo { TEST, message: \"On Home; open Settings\" }\ne2e-add-step { TEST, command: \"gesture-tap\", args: \"{\\\"udid\\\":\\\"ABC\\\",\\\"x\\\":0.91,\\\"y\\\":0.94}\" }\n# pre-tap capture resolves to: - tap: { id: settings-tab }\ne2e-add-step { TEST, command: \"await-ui-element\", args: \"{\\\"udid\\\":\\\"ABC\\\",\\\"condition\\\":\\\"visible\\\",\\\"selector\\\":{\\\"identifier\\\":\\\"settings-screen\\\"}}\" }\ne2e-finish-recording { TEST }\n```\n\nAfter meaning-preserving conversion:\n\n```yaml\nsteps:\n - echo: Restart Acme Notes. Expect Home\n - launch: com.acme.notes\n - await: { visible: { id: home-screen } }\n - await: { idle: true }\n - echo: On Home. Open Settings\n - tap: { id: settings-tab }\n - await: { visible: { id: settings-screen } }\n - await: { idle: true }\n```\n\n## Blocking audit\n\nRun these checks before replay:\n\n```text\n# Weak targets: coordinates, raw gestures, role-only selectors\nrg -n '(\\{ *x:|^ +(x|centerX|fromX|toX):|gesture-(tap|swipe|scroll|drag|pinch|rotate|custom))' .argent/e2e/\u003cname>.yaml\nrg -n -B2 '^ +role:' .argent/e2e/\u003cname>.yaml\n# Stored device ids\nrg -n '(udid|device_id)' .argent/e2e/\u003cname>.yaml\n# Positional ids and loose condition selectors\nrg -n '(-selector-\\d+|selector-\\d+\\b)' .argent/e2e/\u003cname>.yaml\nrg -n '(visible|hidden|exists) *: *[\"'\"'\"'A-Za-z0-9]' .argent/e2e/\u003cname>.yaml\n# Fixed waits and skipped navigation\nrg -n '^\\s*- wait:|open-url' .argent/e2e/\u003cname>.yaml\n```\n\nThe condition grep matches a condition key with a scalar after it (`visible: Save`) and not `visible:` opening a map. Recorder output is always block style, so both forms are one line below their `await:`/`assert:`. It covers `when:` guards too, which take the same loose fallback.\n\nResolve every hit and confirm:\n\n- Every element action uses a stable selector unless the fallback gate cleared and documented it.\n- **No `role:` stands as the only key under a `tap:`/`long-press:`.** That is the recorder's silent fallback, which warned about nothing. Replace it, or clear it through the fallback gate. A `role:` beside another field or a scope (`within`, `after`, `next`) is deliberate and needs no defence.\n- Every element-seeking gesture became `scroll-to`.\n- No device id or literal credential remains.\n- Every selector-bearing condition uses an explicit selector map without positional or data-derived values.\n- Every fixed wait has an echo and a following hard check. Prefer a condition or `idle`.\n- No `open-url` replaces tested navigation.\n- Every snapshot is intentional, deterministic, non-mutating, and ready for reviewed baseline creation.\n- The standalone launch and real first-screen gate are present. Only Chromium permits an inserted launch.\n- Every screen change has a destination-only identity check and an `idle` readiness check. The two are repaired differently: record a missing identity check live on the restored screen, but add a missing readiness gate in YAML, because `await: { idle: true }` has no recorder form.\n- Every `hidden` check follows a `visible` check on the same stable selector and the removing action. A proven containing screen is not a substitute, because it is no evidence the selector itself ever resolved.\n\n## Replay\n\nRun `e2e-execute` on the complete YAML with the absolute project root. For a fragment, verify its prerequisite before setting `prerequisiteAcknowledged: true`.\n\n`e2e-execute` takes exactly one test source: `name`, for a test saved under `.argent/e2e/` (or the legacy `.argent/flows/`), or `flow_path`, an absolute path to any test `.yaml`.\n\nOver `argent link` or `ARGENT_TOOLS_URL`, the client sends the test file, its `run:` fragments, the tests that its `tool: e2e-execute` steps name, the snapshot baselines of each run and the file arguments of its `tool:` steps with the call. These steps work over a link:\n\n- `run:` fragments and the tests that `tool: e2e-execute` steps name, when they are under `project_root`, under its `.argent/e2e/` or `.argent/flows/`, or beside the test file. Keep them there.\n- `snapshot:` steps in the test and in its fragments. The baselines stay in the project. With `updateBaselines: true`, the client writes each new baseline when the run ends. A `baseline not written` line in the report means that the client did not save that baseline: fix the reason in the line and run again.\n- A `tool:` step whose file argument is an absolute path to a `.png` or `.yaml` file, such as `baselinePath` of `screenshot-diff`. Keep the real file under the project root or beside the test file, not behind a symlink to another place. Otherwise the step reports `error` when it runs, after the earlier steps acted.\n- A `tool: e2e-execute` step that names its test with `name` and an absolute `project_root` without a `..` segment. Keep the test that the step names under the project on the client, and spell `name` in the letter case of its file. That test uses its own baselines. A replay with `updateBaselines` also updates them, unless the step sets `updateBaselines` itself.\n\nThese steps do not work over a link, in the test or in a fragment or test that it runs:\n\n- `script:`\n- a `tool:` step that takes a directory, an app or an output directory, such as `reinstall-app`, `gather-workspace-data`, or `screenshot-diff` with `outputDir`\n- a `tool:` step with a relative file path, or a file other than `.png` or `.yaml`\n- a `tool:` step whose tool builds the file path from several arguments, such as `e2e-read-prerequisite` with `name`\n- a `tool: e2e-execute` step with `flow_path`, or with `name` and a relative `project_root` or one with a `..` segment\n- a `tool:` step that records an e2e test\n\nThe tool-server checks the test, its fragments and the tests that it runs before the first step. The error lists each step that does not work over a link, and each `run:` or `tool: e2e-execute` step whose test the client could not send, with the reason. A fragment or a test that does not exist fails its step when the step runs. Run a test that needs these steps with no link and no `ARGENT_TOOLS_URL`, on the computer that runs the tool-server.\n\nManual rescue invalidates the pass. An `errored` step was never evaluated: an `idle` wait whose tree source could not be read, a step that threw, an unresolvable `run:` target, or a `launch:` that did not start the app. Read the reason: most name the environment, but a failed `launch:` is a verdict about the app. Unconfirmed focus is not in this class at all: the replay focus poll has no failure return, so a `type:` step whose focus was never confirmed is scored a **pass**, and only the value check after typing catches it.\n\n**A passing step that carries a `warning` is a finding, not noise.** `await: { idle: true }` raises [six different warnings](e2e-yaml.md#idle-readiness) and they do not share one meaning. Two say the screen was moving; one says the wait ran out mid-hold and is repaired by raising the step's `timeout:`; one says the tree stayed empty; one says the tree did hold still and only the screenshot pairs were missing, so the capture path is what to check; one says the step ended with no evidence either way. No report separates intended motion from a load that never finished. Read which one it is, look at that screen, disclose what you found, and confirm the following step targets a stable element rather than stillness.\n\nA [selector-less gesture](e2e-yaml.md#directives) raises a warning of a different shape, not one of those six: a tree-source outage left it unsettled, so it dispatched blind and the green says only that the gesture was sent. Restore the source, usually by relaunching the app so the instrumentation loads. Accept it only where the app serves no tree at all, such as the [injection-free iOS form](reliability-and-recovery.md#terminally-non-injectable-ios-apps).\n\nOne uninterrupted full pass completes a normal e2e test. `argent-qa-e2e` requires two consecutive passes of unchanged YAML. For CI, use `argent e2e run \u003cname> [--platform ...]`; it exits non-zero on failure.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":25654,"content_sha256":"1814a95d93102e6bfa3d6e6c0e1505338ab07ab64d3bcaf6db31adcd217e2569"},{"filename":"references/reliability-and-recovery.md","content":"# Reliability and recovery\n\nRead this file for selector warnings, raw coordinates, unavailable trees, swallowed actions, overlays, or replay failures.\n\n- [Coordinate fallback gate](#coordinate-fallback-gate)\n- [iOS selector recovery](#ios-selector-recovery)\n- [Other tree sources](#tree-source-recovery-on-android-chromium-and-vega)\n- [Strong transition gates](#strong-transition-gates)\n- [Obscured targets](#obscured-targets-and-persistent-overlays)\n- [Replay diagnosis](#diagnose-a-replay-failure)\n- [Corrections](#correct-the-smallest-justified-unit)\n\n## Coordinate fallback gate\n\nUse this target order:\n\n1. A strict stable id.\n2. Narrow, stable text or accessibility label.\n3. A stable role only when it is unique.\n4. `scroll-to` plus one of those selectors for an off-screen target.\n5. Raw coordinates only after the checks below.\n\nConvert element-seeking swipes to `scroll-to`. Keep a coordinate swipe only when the gesture itself is the tested action and no directive expresses it.\n\n### Run the gate when capture warns\n\nWork this gate as soon as capture warns that it kept a raw point, and equally when it silently recorded a role-only selector, which warns about nothing. Keep the source screen available and do these checks:\n\n1. **iOS:** query plausible ids or labels with `native-find-views`. If no term is useful, call `native-full-hierarchy` with narrow fields and `maxDepth: 100`. `describe` and `native-describe-screen` are accessibility projections. They cannot prove that no YAML selector exists.\n2. **Other platforms:** use `debugger-component-tree` for React Native; otherwise, use `describe`. Verify Android and Chromium candidates in step 3. Their discovery trees can omit runner elements.\n3. Test each candidate in a scratch fragment with `assert: { visible: \u003ccandidate> }` on the valid screen. Inspect every failure before trying a better id, label, app, or container.\n4. If source is available, inspect its `testID`, `accessibilityIdentifier`, or `resource-id`. If none exists, report the missing stable id as the real fix.\n\nAn unavailable tree makes the candidate test void. It proves the tree was absent, not that the selector failed, so it never authorizes coordinates. Relevant failures include `native devtools is unavailable` or `No native-devtools-connected apps are available` on iOS, an unreachable Android helper, an unreachable Chromium CDP session, or missing Vega page source. The recorder quotes the same reason back in its `selector capture failed` warning, so read that warning before treating it as a verdict about the element. Restore the tree and repeat the test.\n\nKeep coordinates only for a genuinely unlabeled target or after all plausible labeled candidates fail against a working runner tree. Add an echo naming the target and a hard check on the action's outcome. Report the point, discovery results, and candidate failures. Re-record every uncleared point.\n\nQA e2e tests are stricter. They can keep a coordinate only for a genuinely unlabeled target. Failed selector candidates alone are insufficient.\n\n## iOS selector recovery\n\nThe full iOS runner tree exists only for an app launched by Argent with instrumentation.\n\n1. If Metro, Expo, Xcode, an icon, or a prior process launched the app, call `restart-app`. Restore the source screen and retry capture. `launch-app` can only foreground the existing process.\n2. Tap capture does **not** wait for that connection. It makes one tree read and turns any failure straight into the kept-coordinates warning. A recording-time `restart-app` returns before the devtools connection opens, so the first tap after a restart can warn transiently. Re-record that tap once before escalating; only a warning that survives the retry is evidence of a real fault.\n3. If the warning survives, call `native-devtools-status` with the same UDID and bundle id and follow its `message`, which names the one action that helps and says when to stop. `requiresRestart` covers only the states a fresh process fixes: an `unregistered` or `connecting` app reports it false, because it already launched under the terms a restart would recreate.\n4. If an injectable app remains disconnected, call `stop-all-simulator-servers` once, **scoped to `devices: [\u003cthis simulator's UDID>]`**. One tool-server serves every agent on this Argent install, so an unscoped call tears down their devices too. This does not change app or account data. Then restart and check status again.\n5. If it still fails, report an instrumentation blocker. Do not replace selectors with coordinates in a QA e2e test.\n\nUse the same explicit UDID throughout. Multiple booted simulators are not an injection fault. Pass `--device \u003cudid>` when CLI device selection is ambiguous.\n\n### Terminally non-injectable iOS apps\n\nThis fallback applies only to `com.apple.*` system apps. A connection failure in another app never authorizes it.\n\nArgent refuses `com.apple.*` bundle ids at every native-devtools read that names one, because a system app is never the app under test. The instrumentation has been seen both loading and not loading into one, depending on the simulator runtime; either way it is no basis for a selector. `restart-app`, `launch-app`, and `describe` still work on one; it just never gets a runner tree.\n\nGive the test a `launch:` step as usual. On iOS the launch waits the full devtools budget out, then passes for one of these bundle ids: starting the app is all that step is for, and a coordinate-driven test needs nothing more. The test stays standalone; it just pays roughly sixteen seconds at the launch. Where the refusal bites is selector resolution, and the first selector step reports it there (terminally, naming the coordinate remedy) rather than as a launch failure. The rest of the tree-free form:\n\n- Raw `tool: await-ui-element` accessibility checks.\n- Point taps or long-presses derived from `describe`, each named by an echo.\n- A point focus tap plus a raw text-only `keyboard` with `delayMs: 500`, and a second raw `keyboard` with `key: \"enter\"` to submit.\n- Raw swipes with `momentum: false` because `scroll-to` needs the missing runner tree. Momentum-free scrolling keeps later coordinate taps valid. `momentum: false` needs `durationMs` of at least 150 and is rejected below it, so keep the 300 default or raise it.\n\nEvery point tap, long-press or coordinate swipe in such a test passes **carrying a warning** for as long as the app serves no tree: each [selector-less gesture](e2e-yaml.md#directives) dispatches unsettled. Nothing here repairs it. Accept the warnings, read each green as \"the gesture was sent, not that it landed\", and put an explicit `wait:` or a raw `tool: await-ui-element` before a gesture that follows a transition. Raw `tool:` steps take no settle, so they never carry that warning.\n\nA recorded wait carries a different warning: it adds about one second and reports that the runner tree is unavailable. That warning is expected too. Keep the wait as a raw `tool:` step.\n\nReport that the test has no runner tree and its coordinates are not portable. It cannot satisfy the QA contract. Report the artifact and platform blocker instead.\n\nA normally injectable app that is broken in the environment gets the same coordinate-only treatment, but not the same launch: there the `launch:` step fails, since the gate withholds its verdict only for a bundle id argent refuses outright. Start such a test with a raw `tool: restart-app`, which terminates and relaunches without the readiness gate, and accept that the result is a **fragment**: its first step that is neither `echo:` nor `script:` is not `launch:`, so the runner never classifies it as standalone, and it cannot complete `argent-qa-e2e`, which requires a leading `launch:`. Report the blocker rather than labeling that fallback a completed QA test.\n\n## Tree source recovery on Android, Chromium, and Vega\n\nWhile the required source is down, selector failures and raw-point capture are void. Restore the source and re-record affected taps.\n\n| Platform | Symptom | Recovery |\n| -------- | -------------------------------------- | -------------------------------------------------------------------------------- |\n| Android | Cannot reach the argent android helper | Argent reinstalls it once; if it persists, read the device's reason in the error |\n| Chromium | No reachable CDP session | Boot again with `electronAppPath` and remote debugging |\n| Vega | Toolkit returns no page source | Relaunch an app built with automation support |\n\nOn Android, healthy `describe` output does not prove the runner tree is available. It can fall back to legacy `uiautomator`, while the runner refuses that trimmed fallback.\n\n## Strong transition gates\n\nEvery navigation needs destination identity followed by readiness. Do not identify a screen with a shared header, persistent tab bar, source element, positional id, counter, username, timestamp, or other data-derived value.\n\nPrefer navigation with a fixed destination. A back button or swipe pops one stack entry, so repeated visits can change its destination. Use back only when back navigation is under test, and gate its result like any other screen change.\n\n## Obscured targets and persistent overlays\n\nA selector tap can resolve the intended element while an overlay receives the touch.\n\nWhen an overlay intersects the next target:\n\n1. Record the overlay as `visible` while it exists.\n2. Record its real dismissal action.\n3. Record the same selector as `hidden`.\n4. Only then touch the covered region.\n\nDo not rely on auto-dismiss timers. Prefer an app e2e affordance that disables transient overlays. On iOS, use `native-user-interactable-view-at-point` for hit-test diagnosis. Other platforms rely on the recorded visibility trio.\n\nKeep a dismissal swipe only when the UI supports it. Pass it through the coordinate gate and hard-check that the overlay disappeared.\n\n## Diagnose a replay failure\n\nClassify before editing:\n\n| Outcome | Meaning | Response |\n| ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Hard failure | A step fails and later steps skip | Inspect that step and actual state |\n| Environment error | The reason says the check could not run | Repair the environment and rerun; it is no verdict about the app. A failed `launch:` is `errored` too but **is** a verdict; treat it as a hard failure |\n| Silent misfire | The run passes but final state is wrong | Restore the first wrong screen and record a stronger gate |\n| Partial divergence | An intermediate result disagrees with its echo | Find the first divergent transition |\n| Acceptance failure | Actions pass but a requested check fails | Preserve the check and investigate behavior |\n| Idle warning | A readiness step passes without settling | Read [which of the six warnings](e2e-yaml.md#idle-readiness) it is, then gate the next action on a stable element |\n| Unsettled gesture | A selector-less gesture passes unsettled | Restore the tree source, usually by relaunching the app; the green says [only that the gesture was sent](e2e-yaml.md#directives) |\n\nThen:\n\n1. Record the first failure or divergence index and message.\n2. Capture `screenshot` and `describe`. Use native or React Native discovery when needed.\n3. Compare actual state with the preceding echo and expected destination.\n4. Classify the cause: selector, screen, missing element, readiness, stale data, optional interstitial, or product behavior.\n5. State the diagnosis in one sentence before correcting it.\n\n## Correct the smallest justified unit\n\n- For one parameter or selector error, edit the YAML and prefer a stable selector.\n- For readiness or identity failure, repair that gate and audit every transition with the same shape.\n- For one missing transition or two to three structural steps, copy the working prefix and re-record the affected span live.\n- For four or more broken steps, unclear state, or a comparison or profiling test, fully re-record.\n- Treat manual recovery as diagnosis only. It never counts as a replay pass.\n\nStarting again under the same name truncates the YAML. Copy any working prefix before re-recording.\n\n### Make every replacement gate stronger\n\n| Weak gate | Do not use | Add the missing proof |\n| ----------------------------- | -------------- | ----------------------------------------- |\n| Shared or positional identity | Longer timeout | Destination-only root or control |\n| Tap lost during motion | Fixed wait | `idle` after destination identity |\n| Toast absorbs tap | Retry | Verified overlay dismissal |\n| `hidden` never established | Longer timeout | Same-selector `visible`, action, `hidden` |\n| Typed value is wrong | Retype | Assert the committed value |\n\nState the added proof before rerunning.\n\n### Correction limit\n\nAfter each correction, audit and replay from the declared start. Stop after two unsuccessful correction cycles and report the remaining blocker. If failures move while the test grows, re-record the affected span instead of adding more patches.\n\nNever weaken, remove, or hide a requested check to obtain a pass. Keep a failing product check and report the test as an unproven regression artifact. QA remains incomplete until its two-pass gate succeeds.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":14405,"content_sha256":"db6524f2288a69c8dd7197c1dfe9ab243314d940f1ebbe18bf17de47ffa9d2ae"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Create an Argent e2e test","type":"text"}]},{"type":"paragraph","content":[{"text":"An Argent e2e test is a replayable sequence in ","type":"text"},{"text":".argent/e2e/\u003cname>.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":".argent/flows/","type":"text","marks":[{"type":"code_inline"}]},{"text":" is still read).","type":"text"}]},{"type":"paragraph","content":[{"text":"For a saved QA test case, ticket, or acceptance criterion, load ","type":"text"},{"text":"argent-qa-e2e","type":"text","marks":[{"type":"code_inline"}]},{"text":" first. It adds deterministic setup, acceptance evidence, and two-pass proof.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Read the relevant reference","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Before creating or changing an e2e test, read ","type":"text"},{"text":"Live authoring","type":"text","marks":[{"type":"link","attrs":{"href":"references/live-authoring.md","title":null}}]},{"text":" completely.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When polishing, composing, or manually reviewing YAML, read ","type":"text"},{"text":"E2E YAML","type":"text","marks":[{"type":"link","attrs":{"href":"references/e2e-yaml.md","title":null}}]},{"text":". For Vega, read its platform limits before recording remote or keyboard tools.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"E2E tests run on physical iPhones (an iOS ","type":"text"},{"text":"list-devices","type":"text","marks":[{"type":"code_inline"}]},{"text":" entry with kind ","type":"text"},{"text":"\"device\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as ","type":"text"},{"text":"device","type":"text","marks":[{"type":"code_inline"}]},{"text":" (CLI ","type":"text"},{"text":"--device","type":"text","marks":[{"type":"code_inline"}]},{"text":"), and only a ","type":"text"},{"text":"connected","type":"text","marks":[{"type":"code_inline"}]},{"text":" phone can run. ","type":"text"},{"text":"pinch","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"rotate","type":"text","marks":[{"type":"code_inline"}]},{"text":" steps run there as two-finger gestures, in apps drawn in portrait. On hardware the runner tree is the ","type":"text"},{"text":"describe","type":"text","marks":[{"type":"code_inline"}]},{"text":" tree: same ids and roles, no UIView hierarchy. See ","type":"text"},{"text":"argent-ios-device-interact","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the hardware contract.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"On capture warnings, raw coordinates, unavailable trees, mistimed transitions, overlays, or replay failures, read ","type":"text"},{"text":"Reliability and recovery","type":"text","marks":[{"type":"link","attrs":{"href":"references/reliability-and-recovery.md","title":null}}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Non-negotiable rules","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Record the first walkthrough.","type":"text","marks":[{"type":"strong"}]},{"text":" Start the recorder before the first launch or in-app action. Do not reconstruct a rehearsed path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Record checks when their states appear.","type":"text","marks":[{"type":"strong"}]},{"text":" Record ","type":"text"},{"text":"await-ui-element","type":"text","marks":[{"type":"code_inline"}]},{"text":" live, then convert it during polish. An echo records intent or diagnostic context, not app behavior or a verdict. A screenshot is human evidence, not an executable verdict. For absence, record the same selector as ","type":"text"},{"text":"visible","type":"text","marks":[{"type":"code_inline"}]},{"text":", perform the removing action, then record it as ","type":"text"},{"text":"hidden","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use semantic targets.","type":"text","marks":[{"type":"strong"}]},{"text":" Prefer a strict id, then stable text or an accessibility label. Use ","type":"text"},{"text":"scroll-to","type":"text","marks":[{"type":"code_inline"}]},{"text":" for off-screen elements. Resolve every raw-point warning immediately through the ","type":"text"},{"text":"coordinate fallback gate","type":"text","marks":[{"type":"link","attrs":{"href":"references/reliability-and-recovery.md#coordinate-fallback-gate","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prove every screen change.","type":"text","marks":[{"type":"strong"}]},{"text":" Record a destination-only identity check. During polish, follow it with ","type":"text"},{"text":"await: { idle: true }","type":"text","marks":[{"type":"code_inline"}]},{"text":". Stillness does not prove identity, and ","type":"text"},{"text":"idle","type":"text","marks":[{"type":"code_inline"}]},{"text":" can pass with a warning.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polish only executed behavior.","type":"text","marks":[{"type":"strong"}]},{"text":" Convert recorded steps without changing their meaning. Record any missing action or structural check live. The only unrecorded insertions are a planned ","type":"text"},{"text":"snapshot:","type":"text","marks":[{"type":"code_inline"}]},{"text":", a navigation ","type":"text"},{"text":"await: { idle: true }","type":"text","marks":[{"type":"code_inline"}]},{"text":", and the documented Chromium packaging ","type":"text"},{"text":"launch:","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use scripts only when the user requests them.","type":"text","marks":[{"type":"strong"}]},{"text":" Read ","type":"text"},{"text":"E2E YAML: Local scripts","type":"text","marks":[{"type":"link","attrs":{"href":"references/e2e-yaml.md#local-scripts","title":null}}]},{"text":", then record each script with ","type":"text"},{"text":"e2e-add-script","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replay the final YAML end to end.","type":"text","marks":[{"type":"strong"}]},{"text":" A normal e2e test needs one uninterrupted full pass. ","type":"text"},{"text":"argent-qa-e2e","type":"text","marks":[{"type":"code_inline"}]},{"text":" requires two consecutive passes.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Stable selectors","type":"text"}]},{"type":"paragraph","content":[{"text":"A stable selector is fixed by app code and survives account, data, time, count, order, and every locale and environment the e2e test supports. Prefer ids such as ","type":"text"},{"text":"settings-screen","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do not gate on values such as ","type":"text"},{"text":"Today","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Item 4","type":"text","marks":[{"type":"code_inline"}]},{"text":", usernames, counters, or timestamps.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"YAML-only selector scopes","type":"text"}]},{"type":"paragraph","content":[{"text":"During polish, use ","type":"text"},{"text":"within","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code_inline"}]},{"text":" to disambiguate repeated elements. Read ","type":"text"},{"text":"E2E YAML: Relational scopes","type":"text","marks":[{"type":"link","attrs":{"href":"references/e2e-yaml.md#relational-scopes","title":null}}]},{"text":" for their frame-based semantics and failure cases.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choose the e2e test type:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"standalone:","type":"text","marks":[{"type":"strong"}]},{"text":" the first step that is not ","type":"text"},{"text":"echo:","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"script:","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"launch:","type":"text","marks":[{"type":"code_inline"}]},{"text":". The test controls process start.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fragment:","type":"text","marks":[{"type":"strong"}]},{"text":" there is no leading launch. Declare a precise ","type":"text"},{"text":"executionPrerequisite","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follow ","type":"text"},{"text":"Live authoring","type":"text","marks":[{"type":"link","attrs":{"href":"references/live-authoring.md","title":null}}]},{"text":": start, record one verified step at a time, finish, polish, audit, and replay.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report the file, replay command, result, prerequisite or side effects, and every coordinate or raw-gesture exception.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Proactive recording","type":"text"}]},{"type":"paragraph","content":[{"text":"Before repeating three or more interactions, tell the user and start a recording. Record that run and replay it afterward. A completed path cannot be recorded retroactively.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Repair","type":"text"}]},{"type":"paragraph","content":[{"text":"When replay fails, follow ","type":"text"},{"text":"Reliability and recovery","type":"text","marks":[{"type":"link","attrs":{"href":"references/reliability-and-recovery.md","title":null}}]},{"text":". Inspect the first divergence, correct the smallest justified unit, audit, and replay the full e2e test. Stop after two unsuccessful correction cycles. Never weaken a requested check to obtain a pass.","type":"text"}]}]},"metadata":{"date":"2026-11-02","name":"argent-create-e2e","author":"@skillopedia","source":{"stars":3146,"repo_name":"argent","origin_url":"https://github.com/software-mansion/argent/blob/HEAD/packages/skills/skills/argent-create-e2e/SKILL.md","repo_owner":"software-mansion","body_sha256":"8ecc6108e8ec450f27b30e5f86c95cebe902a5becb4c2f754bb201caa84c5c5e","cluster_key":"2153af11555dcede9af8db0516b76390e935c19f8fbdbbb2bad0ead6d01ebeba","clean_bundle":{"format":"clean-skill-bundle-v1","source":"software-mansion/argent/packages/skills/skills/argent-create-e2e/SKILL.md","text_bytes":66735,"source_commit":"f672f06390bff38192a577a4e55cb3ca6c9d6a46","skills_sh_rank":7398,"attachment_count":3,"text_attachments":3,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"packages/skills/skills/argent-create-e2e/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"testing-qa","category_label":"Testing"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"testing-qa","import_tag":"skills-sh-top20k-2026-11","description":"Create, record, edit, replay, or repair reusable Argent e2e test YAML files. Use when the user asks to record, replay, or run an e2e test or a repeatable device path, set up profiling or an A/B comparison, or invoke the authoring engine behind argent-qa-e2e. Also use before repeating three or more interactions. For one-off UI checks, acceptance-driven regression tests, or screen video, use argent-test-ui-flow, argent-qa-e2e, or argent-screen-recording respectively."}},"renderedAt":1793661322590}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.