Skip to content

Commit a5052c5

Browse files
committed
docs(help): route stale React Native state to reads, not UI navigation
1 parent 495e0e5 commit a5052c5

3 files changed

Lines changed: 88 additions & 77 deletions

File tree

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
export const reactNativeHelpTopic = {
2+
summary: 'React Native app automation hazards and routing',
3+
body: `agent-device help react-native
4+
5+
Use this when the target app is React Native, Expo, or a React Native dev client.
6+
This topic covers React Native-specific automation hazards and routes deeper
7+
questions to the owning help topic.
8+
9+
Choose the next help topic:
10+
Routine QA/dogfood/manual-test flow (open, snapshot -i, press/fill --settle, verify, close): help manual-qa; it has the concrete command shapes, so you should not need generic navigation help for a normal pass.
11+
Deep exploration of navigation/selector/ref edge cases, or a serial-command question manual-qa does not answer: help workflow (full reference, larger read).
12+
Logs, network, diagnostics, traces, permission dialogs, or runtime failures: help debugging.
13+
Component tree, props/state/hooks, slow renders, rerenders, render causes, or dropped frames in React: help react-devtools.
14+
JS heap growth, heap snapshots, allocation hotspots, or retained-object leaks: help cdp.
15+
A wrong or stale value that may come from app state or storage (AsyncStorage, MMKV, a feature flag): see Stale state below.
16+
Remote/cloud config, leases, and local service tunnels: help remote.
17+
18+
React Native dev loop:
19+
Do not run doctor as routine QA/dogfood prep. Use doctor only when the user asks for setup diagnostics or a command failure points to an unhealthy device, runner, dev-server, or remote environment.
20+
For "start from screen X" flows, prefer open --relaunch before the first snapshot so the app does not reuse a prior in-progress navigation state.
21+
JS-only change with Metro or Re.Pack connected:
22+
agent-device metro reload
23+
agent-device find "Home"
24+
Do not use agent-device reload. Use open --relaunch for native startup reset.
25+
Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability. For app/package launches, run metro prepare when the app cannot reach the local dev server.
26+
Verify Metro/Re.Pack from the same host context that owns the dev server. If a sandboxed shell cannot curl localhost:8081/status but an unrestricted host shell can, the dev server is running and the sandbox probe is not authoritative.
27+
adb reverse only affects Android device-to-host traffic. It does not prove host-to-dev-server reachability, and it does not fix a redbox caused by a stale or wrong bundle/app state.
28+
Multiple local worktrees can reuse one native iOS simulator build by running each worktree's dev server on a different port and opening the same installed app on different simulators with explicit runtime hints:
29+
agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081 --relaunch
30+
agent-device open "React Navigation Example" --platform ios --device "iPhone 17 Pro" --session rn-b --metro-host 127.0.0.1 --metro-port 8082 --relaunch
31+
iOS simulator opens write bare React Native's per-simulator debug server settings before launch. Detected Expo development clients receive their server URL through a launch link instead. Use separate sessions/devices, close both sessions when done, and rebuild only for native changes or dependency changes that affect the binary. One simulator cannot run two copies of the same bundle id.
32+
Expo Go/dev clients are host shells. Use provided project URLs, verify with snapshot -i after opening, and ask instead of inventing app ids or URLs. Help workflow owns the full Expo URL command shapes.
33+
34+
Overlays and busy RN UIs:
35+
If snapshot reports a React Native warning/error overlay, handle it before interacting with the app: run agent-device react-native dismiss-overlay. The command sends the safe LogBox/RedBox action and verifies the overlay is gone with a fresh post-dismiss snapshot -i.
36+
If the command reports the overlay is still visible, use screenshot --overlay-refs for visual evidence and report the overlay instead of pressing warning/error text manually.
37+
Do not manually press warning/error text bodies, collapsed banner bodies, full-screen warning parents, or broad LogBox/RedBox refs. The dismiss-overlay command owns the narrow LogBox/RedBox targeting policy.
38+
Report the overlay in the final summary. Use screenshot --overlay-refs before dismissing only if visual evidence is required.
39+
Minimal overlay continuation:
40+
agent-device snapshot -i
41+
agent-device react-native dismiss-overlay
42+
agent-device snapshot -i
43+
agent-device press 'id="submit-order"'
44+
Do not use a plain snapshot after dismiss-overlay when the next step needs current refs; use snapshot -i.
45+
When overlay evidence is required before continuing, keep the sequence explicit:
46+
agent-device snapshot -i
47+
agent-device screenshot --overlay-refs
48+
agent-device react-native dismiss-overlay
49+
agent-device snapshot -i
50+
agent-device press 'id="submit-order"'
51+
If snapshot times out because the UI never becomes idle, Android accessibility may be blocked by busy or continuously changing app UI. After that timeout, use screenshot as visual truth instead of repeatedly retrying snapshots.
52+
If iOS snapshot reports AX unavailable or returns only a sparse root, the current screen's accessibility state is invalid. Use plain screenshot as visual truth, coordinate navigation to leave the bad screen, then take a fresh snapshot -i before returning to selector/@ref commands.
53+
agent-device screenshot
54+
agent-device press 124 817
55+
agent-device snapshot -i
56+
Android runtime permission dialogs and native alerts are handled by alert wait/accept/dismiss. If alert reports no alert but a sheet is visible, alert did not recognize it: use snapshot -i and press @ref on the visible button.
57+
58+
React DevTools routing:
59+
Keep the agent-device react-devtools prefix on every React DevTools command.
60+
Use help react-devtools for component trees, props/state/hooks, render profiles, slow renders, rerenders, and their causes.
61+
If React DevTools cannot attach, report the error and continue with logs, network, perf frames, perf memory, screenshot, and trace evidence instead of blocking the whole flow.
62+
63+
CDP memory routing:
64+
Keep the agent-device cdp prefix on every CDP command.
65+
Use help cdp for JS heap usage samples, heap snapshots, snapshot diffs, leak-triplet analysis, allocation hotspots, and retained-object paths.
66+
Use perf memory sample or perf memory snapshot for native/process memory; use cdp only for JavaScript heap evidence.
67+
68+
Stale state:
69+
If a wrong or stale value may come from app state or storage, read the value. Do not navigate the UI to infer it.
70+
JS state through Metro, after cdp target select (help cdp):
71+
agent-device cdp runtime eval --expr '<expression>' --await
72+
Stored AsyncStorage on an iOS simulator is under the data container from xcrun simctl get_app_container <udid> <bundle-id> data, in Library/Application Support/<bundle-id>/RCTAsyncLocalStorage_V1. On Android, read databases/RKStorage with adb shell run-as <package>.
73+
74+
Slow-flow investigation:
75+
Keep one session, open the app first, and snapshot -i before interacting.
76+
Start React Native slow-flow plans with this ordered scaffold:
77+
agent-device open "Agent Device Tester" --platform android
78+
agent-device snapshot -i
79+
If the task says to open the app, include the open command even when it also describes the current screen.
80+
Use help react-devtools for the narrow React profile window: react-devtools profile start right before the interaction and react-devtools profile stop after it.
81+
Use help debugging for logs clear --restart, logs mark, network dump --include headers, perf frames, perf memory, native profiles, traces, and runtime failure evidence.
82+
For 15-20s async work, use wait with the exact expected text or selector instead of repeated snapshots.
83+
Report React render offenders separately from network/backend waits and device frame/CPU/memory findings.`,
84+
};

‎src/commands/schema/cli-help-topics.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -624,6 +624,8 @@ test('usageForCommand resolves react-native help topic', async () => {
624624
assert.match(help, /agent-device react-native dismiss-overlay/);
625625
assert.match(help, /verifies the overlay is gone with a fresh post-dismiss snapshot -i/);
626626
assert.match(help, /Do not use a plain snapshot after dismiss-overlay/);
627+
assert.match(help, /agent-device cdp runtime eval --expr '<expression>' --await/);
628+
assert.match(help, /RCTAsyncLocalStorage_V1/);
627629
assert.match(help, /When overlay evidence is required before continuing/);
628630
assert.match(help, /overlay is still visible/);
629631
assert.match(help, /Do not manually press warning\/error text bodies/);

‎src/commands/schema/cli-help.ts‎

Lines changed: 2 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import {
2121
} from './cli-help-workflows.ts';
2222
import { renderCliHelpOverview } from './cli-help-overview.ts';
2323
import { foldableHelpTopic } from './cli-help-foldable.ts';
24+
import { reactNativeHelpTopic } from './cli-help-react-native.ts';
2425
import { TV_PLUGIN_FLOWS } from './cli-help-tv.ts';
2526
import { providerPluginHelp } from '../provider-plugin-catalog.ts';
2627

@@ -366,83 +367,7 @@ Output contract:
366367
Target caveats:
367368
React Native/Hermes implements a subset of browser CDP. If a command reports an unsupported method, keep the target selected and switch to heap usage samples plus heap snapshots. Prefer react-devtools profile for render causes; prefer perf memory sample or perf memory snapshot for native/process memory.`,
368369
},
369-
'react-native': {
370-
summary: 'React Native app automation hazards and routing',
371-
body: `agent-device help react-native
372-
373-
Use this when the target app is React Native, Expo, or a React Native dev client.
374-
This topic covers React Native-specific automation hazards and routes deeper
375-
questions to the owning help topic.
376-
377-
Choose the next help topic:
378-
Routine QA/dogfood/manual-test flow (open, snapshot -i, press/fill --settle, verify, close): help manual-qa; it has the concrete command shapes, so you should not need generic navigation help for a normal pass.
379-
Deep exploration of navigation/selector/ref edge cases, or a serial-command question manual-qa does not answer: help workflow (full reference, larger read).
380-
Logs, network, diagnostics, traces, permission dialogs, or runtime failures: help debugging.
381-
Component tree, props/state/hooks, slow renders, rerenders, render causes, or dropped frames in React: help react-devtools.
382-
JS heap growth, heap snapshots, allocation hotspots, or retained-object leaks: help cdp.
383-
Remote/cloud config, leases, and local service tunnels: help remote.
384-
385-
React Native dev loop:
386-
Do not run doctor as routine QA/dogfood prep. Use doctor only when the user asks for setup diagnostics or a command failure points to an unhealthy device, runner, dev-server, or remote environment.
387-
For "start from screen X" flows, prefer open --relaunch before the first snapshot so the app does not reuse a prior in-progress navigation state.
388-
JS-only change with Metro or Re.Pack connected:
389-
agent-device metro reload
390-
agent-device find "Home"
391-
Do not use agent-device reload. Use open --relaunch for native startup reset.
392-
Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability. For app/package launches, run metro prepare when the app cannot reach the local dev server.
393-
Verify Metro/Re.Pack from the same host context that owns the dev server. If a sandboxed shell cannot curl localhost:8081/status but an unrestricted host shell can, the dev server is running and the sandbox probe is not authoritative.
394-
adb reverse only affects Android device-to-host traffic. It does not prove host-to-dev-server reachability, and it does not fix a redbox caused by a stale or wrong bundle/app state.
395-
Multiple local worktrees can reuse one native iOS simulator build by running each worktree's dev server on a different port and opening the same installed app on different simulators with explicit runtime hints:
396-
agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081 --relaunch
397-
agent-device open "React Navigation Example" --platform ios --device "iPhone 17 Pro" --session rn-b --metro-host 127.0.0.1 --metro-port 8082 --relaunch
398-
iOS simulator opens write bare React Native's per-simulator debug server settings before launch. Detected Expo development clients receive their server URL through a launch link instead. Use separate sessions/devices, close both sessions when done, and rebuild only for native changes or dependency changes that affect the binary. One simulator cannot run two copies of the same bundle id.
399-
Expo Go/dev clients are host shells. Use provided project URLs, verify with snapshot -i after opening, and ask instead of inventing app ids or URLs. Help workflow owns the full Expo URL command shapes.
400-
401-
Overlays and busy RN UIs:
402-
If snapshot reports a React Native warning/error overlay, handle it before interacting with the app: run agent-device react-native dismiss-overlay. The command sends the safe LogBox/RedBox action and verifies the overlay is gone with a fresh post-dismiss snapshot -i.
403-
If the command reports the overlay is still visible, use screenshot --overlay-refs for visual evidence and report the overlay instead of pressing warning/error text manually.
404-
Do not manually press warning/error text bodies, collapsed banner bodies, full-screen warning parents, or broad LogBox/RedBox refs. The dismiss-overlay command owns the narrow LogBox/RedBox targeting policy.
405-
Report the overlay in the final summary. Use screenshot --overlay-refs before dismissing only if visual evidence is required.
406-
Minimal overlay continuation:
407-
agent-device snapshot -i
408-
agent-device react-native dismiss-overlay
409-
agent-device snapshot -i
410-
agent-device press 'id="submit-order"'
411-
Do not use a plain snapshot after dismiss-overlay when the next step needs current refs; use snapshot -i.
412-
When overlay evidence is required before continuing, keep the sequence explicit:
413-
agent-device snapshot -i
414-
agent-device screenshot --overlay-refs
415-
agent-device react-native dismiss-overlay
416-
agent-device snapshot -i
417-
agent-device press 'id="submit-order"'
418-
If snapshot times out because the UI never becomes idle, Android accessibility may be blocked by busy or continuously changing app UI. After that timeout, use screenshot as visual truth instead of repeatedly retrying snapshots.
419-
If iOS snapshot reports AX unavailable or returns only a sparse root, the current screen's accessibility state is invalid. Use plain screenshot as visual truth, coordinate navigation to leave the bad screen, then take a fresh snapshot -i before returning to selector/@ref commands.
420-
agent-device screenshot
421-
agent-device press 124 817
422-
agent-device snapshot -i
423-
Android runtime permission dialogs and native alerts are handled by alert wait/accept/dismiss. If alert reports no alert but a sheet is visible, alert did not recognize it: use snapshot -i and press @ref on the visible button.
424-
425-
React DevTools routing:
426-
Keep the agent-device react-devtools prefix on every React DevTools command.
427-
Use help react-devtools for component trees, props/state/hooks, render profiles, slow renders, rerenders, and their causes.
428-
If React DevTools cannot attach, report the error and continue with logs, network, perf frames, perf memory, screenshot, and trace evidence instead of blocking the whole flow.
429-
430-
CDP memory routing:
431-
Keep the agent-device cdp prefix on every CDP command.
432-
Use help cdp for JS heap usage samples, heap snapshots, snapshot diffs, leak-triplet analysis, allocation hotspots, and retained-object paths.
433-
Use perf memory sample or perf memory snapshot for native/process memory; use cdp only for JavaScript heap evidence.
434-
435-
Slow-flow investigation:
436-
Keep one session, open the app first, and snapshot -i before interacting.
437-
Start React Native slow-flow plans with this ordered scaffold:
438-
agent-device open "Agent Device Tester" --platform android
439-
agent-device snapshot -i
440-
If the task says to open the app, include the open command even when it also describes the current screen.
441-
Use help react-devtools for the narrow React profile window: react-devtools profile start right before the interaction and react-devtools profile stop after it.
442-
Use help debugging for logs clear --restart, logs mark, network dump --include headers, perf frames, perf memory, native profiles, traces, and runtime failure evidence.
443-
For 15-20s async work, use wait with the exact expected text or selector instead of repeated snapshots.
444-
Report React render offenders separately from network/backend waits and device frame/CPU/memory findings.`,
445-
},
370+
'react-native': reactNativeHelpTopic,
446371
'physical-device': {
447372
summary: 'Connected phone/tablet setup and iOS signing prerequisites',
448373
body: `agent-device help physical-device

0 commit comments

Comments
 (0)