You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9a4b41e
Browse filesBrowse the repository at this point in the historyBrowse files
fix(ad-script): address review — strict shell parity for single quotes, pinned grammar rules
Single-quoted script values now decode exactly what the shell hands over: the
only escape is `\'` (the one deliberate extension, since a shell's single quotes
cannot carry an apostrophe and a `label="don't"` selector has to be writable in
a script), and a backslash keeps its own character instead of collapsing.
- The tokenizer comment states the scoped guarantee: a whole-word quoted run
gains the shell reading (that is the change), a run the shell would not read
as one argument keeps its old bare meaning.
- The admission test now asserts every script token is a long `--` spelling, so
an `-d`/`-s` regression fails there.
- The `wait` long-form-only comment carries the real trade: writer parity, and
realistic short-flag-waited-text versus an almost-impossible literal that
quoting already solves.
- Docs: script flags are declared-and-recorded ones (no contradiction with the
scroll pixel note), single-quote decode rules match the code, and the
discovery counts sentence is scoped to the no-match error as it actually
behaves.
Copy file name to clipboardExpand all lines: src/commands/schema/cli-help.ts
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -164,7 +164,7 @@ Script paths are the caller's:
164
164
test --json marks a failed test with infrastructure: true only when the owning runtime classified a device, runner, boot, or transport failure. It remains a failed test; consumers may use the tag to distinguish "the oracle did not run" from a behavioral replay divergence without weakening either gate.
165
165
166
166
Script line grammar:
167
-
A .ad line is <command> [positional...] [flag...]. Whitespace splits tokens; a token quoted with " or ' is one argument, and single quotes keep a double quote literal, exactly as at the shell (press 'id="far"' is one selector). Values in double quotes are JSON strings (escape \\\\, \\", \\t, \\n); values in single quotes are literal except for \\' and \\\\. A command reads only its own declared flags, so the CLI form and the script line are the same text: scroll down --until 'id="x"', wait 'label="Sign in"' --raw, snapshot -i. Recorded lines carry what the flag declaration marks recorded; per-request options (--settle, --verify) are not part of a step and are not written.
167
+
A .ad line is <command> [positional...] [flag...]. Whitespace splits tokens; a token quoted with " or ' is one argument, and single quotes keep a double quote literal, exactly as at the shell (press 'id="far"' is one selector). Values in double quotes are JSON strings (escape \\\\, \\", \\t, \\n). Values in single quotes are literal, as at the shell: a backslash keeps its own character and the only escape is \\' for an apostrophe. A script carries only the flags declared for that command and marked recorded, so the script form of a step matches the CLI form: scroll down --until 'id="x"', wait 'label="Sign in"' --raw. CLI-only spellings and per-request options are not part of a step: --settle, --verify, scroll --pixels/--duration-ms, and the device-selection flags (--platform, --serial, --device) are the common ones a script does not carry.
168
168
Reaching an off-screen target is viewport-independent in a script the same way it is at the CLI: write scroll down --until <selector>, not a fixed scroll amount that passes on one screen size and fails on another.
Copy file name to clipboardExpand all lines: website/docs/docs/replay-e2e.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,8 +53,8 @@ close
53
53
```
54
54
55
55
- A token quoted with `"` or `'` is one argument. Single quotes keep a `"` literal, so `'id="far-button"'` and `"id=\"far-button\""` are the same selector — write whichever matches how you typed the command at the shell.
56
-
- Values in double quotes are JSON strings, so escape `\\`, `\"`, `\t`, and `\n`. Values in single quotes are literal except for `\'`and `\\`.
57
-
- A command accepts only its own flags. A flag the CLI accepts is available in a script when it belongs to the step; per-request options are not part of a step. `--settle`, `--verify`, and the device-selection flags (`--platform`, `--serial`, `--device`) are the common ones a script does not carry.
56
+
- Values in double quotes are JSON strings, so escape `\\`, `\"`, `\t`, and `\n`. Values in single quotes are literal, as at the shell: a backslash keeps its own character, and the only escape is `\'` for an apostrophe.
57
+
- A script carries only the flags declared for that command and marked recorded; CLI-only spellings and per-request options are not part of a step. `--settle`, `--verify`, `scroll --pixels`/`--duration-ms`, and the device-selection flags (`--platform`, `--serial`, `--device`) are the common ones a script does not carry.
58
58
-`help <command>` prints the flags each command accepts. `help scripting` prints this grammar.
59
59
60
60
Reaching an off-screen element is viewport-independent in a script exactly as it is at the CLI. Prefer the stop condition over a fixed amount, which passes on one screen size and fails on another:
@@ -68,7 +68,7 @@ scroll down 0.8
68
68
scroll bottom
69
69
```
70
70
71
-
A `#` only starts a comment at the beginning of a line. A scroll line carries `--until` and keeps its distance as a positional; `--pixels` and `--duration-ms` belong to the CLI invocation, not to a step. `wait` carries `--raw`, `--depth <n>`, and `--scope <selector|@ref>` to choose the capture its target is read from.
71
+
A `#` only starts a comment at the beginning of a line. A scroll line carries `--until` and keeps its distance as a positional (`scroll down 0.8 --until <selector>`). `wait` carries `--raw`, `--depth <n>`, and `--scope <selector|@ref>` (long spellings; the `-d`/`-s` CLI aliases stay out of scripts so a hand-written line like `wait text -s so funny` keeps meaning its literal text) to choose the capture its target is read from.
-`test` discovers `.ad` files from files, directories, or globs and runs them serially.
161
161
- Quote relative globs to expand them on the caller from its working directory, including when the directory name contains glob characters such as `[` or `{`. A missing file input without glob characters reports an error.
162
162
-`context platform=...` inside each `.ad` file is the target source of truth for suite execution.
163
-
-`--platform` is a filter for suite discovery; files without platform metadata are skipped when a filter is present, and the run reports how many sources were skipped for having no `context platform=` header versus how many declared another platform. Add the header to run a file under a filter, or omit `--platform` and let the selected device decide.
163
+
-`--platform` is a filter for suite discovery; files without platform metadata are skipped when a filter is present. When filtering leaves no runnable sources, the no-match error reports how many sources were skipped for having no `context platform=` header versus how many declared another platform. Add the header to run a file under a filter, or omit `--platform` and let the selected device decide.
164
164
-`context timeout=...` and `context retries=...` can be declared per script; CLI flags override metadata. Retries are capped at `3`, and duplicate keys in the context header fail fast instead of silently overriding each other.
165
165
- By default, suite artifacts are written under `.agent-device/test-artifacts/<run-id>/...`. Each attempt writes `replay.ad`, `result.txt`, and `replay-timing.ndjson`. Failed attempts also keep copied logs and artifact files when the replay produced them.
166
166
- Copied diagnostic artifacts receive numbered filenames when their names collide with another artifact, a replay source, timing trace, or attempt manifest. `result.txt` lists the retained names in `copiedArtifacts`.
0 commit comments