Skip to content

Commit 2d7d741

Browse files
committed
docs(snapshot): put the never-idle screen rule where snapshot advice lives
The read that fails is shared hosted WebDriver behaviour, so it belongs on the Snapshots page rather than only under one provider. The provider page keeps the part that is about being metered. Both pages name the two dead ends, since both were tried on the reported run: a larger `--timeout`, which widens the command around the read, and `settings animations`, which hosted WebDriver sessions do not implement.
1 parent c19c7b1 commit 2d7d741

2 files changed

Lines changed: 2 additions & 1 deletion

File tree

website/docs/docs/aws-device-farm.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,4 +110,4 @@ If `connect` fails, use the reported `aws devicefarm get-*` error to check the c
110110

111111
On hosted WebDriver sessions, `fill` checks that the field received focus before it sends keys. If it cannot confirm focus, it fails without typing. Use `snapshot -i` to confirm the target. If the driver cannot expose focus at all, use `press <target>` followed by `type <text>`. That sends text without confirming the destination.
112112

113-
A screen that never goes still — a looping video, a live ticker, continuous animation — gives the driver no quiet moment to read the UI tree, so `snapshot` can run past its budget and fail with a reason that names the cause. The failed read is cancelled with its request instead of being dropped while it still runs, so it stops occupying the session and later commands are not queued behind a capture nobody is waiting for. That budget belongs to the read itself: a larger `--timeout` widens the command around it and cannot shorten the walk, so it is not the recovery. A `screenshot` of the same screen keeps working because it never reads the tree, and `@refs` an earlier snapshot captured stay valid to drive from. `--depth` trims a tree after it arrives, so it cannot shorten a read that never returned.
113+
A screen that never goes still — a looping video, a live ticker, continuous animation — gives the provider's driver no quiet moment to read the UI tree, so `snapshot -i` can run out of its read budget on a rented device while `screenshot` of the same screen still returns. Snapshots covers what that failure means and what to do instead; on a metered device the difference matters, because every second of the walk is billed. Take the screenshot, drive from `@refs` an earlier snapshot captured, and remember that `--depth` trims a tree after it arrives, so it cannot shorten a read that never returned.

website/docs/docs/snapshots.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ agent-device snapshot --diff # Alias for the same diff operation
6060
- Re-snapshot after any UI mutation before reusing refs.
6161
- On Android after navigation or submit, snapshot capture retries suspicious trees for a short post-action deadline and `@ref` interactions refresh while that freshness window is active. If `snapshot -i` still disagrees with the visible screen, trust `screenshot`, wait briefly, then take one fresh snapshot instead of looping stale snapshots.
6262
- For automation runs affected by Android animation churn, use `settings animations off` as an opt-in stabilizer and restore with `settings animations on` after the run.
63+
- On a device cloud the tree is read by the provider's driver, so a screen that never goes still — a looping video, a live ticker, continuous animation — gives that read no quiet moment and it can run out of its budget while `screenshot` still returns. The read is cancelled with the request that asked for it, so it does not leave later commands waiting behind a capture nobody wants. Two dead ends: the read carries its own budget, so a larger `--timeout` cannot lengthen it, and `settings animations` is not implemented on hosted WebDriver sessions.
6364
- Use `diff snapshot` between mutations to validate structural changes with lower output volume.
6465
- Use `snapshot --diff` when you discover the feature from snapshot help, but keep `diff snapshot` as the default exploration command.
6566
- Keep `--raw` for troubleshooting only when you need the full tree instead of visible-first output.

0 commit comments

Comments
 (0)