Skip to content

Commit ab1743c

Browse files
committed
refactor(android): extract helper touch dispatch into focused classes; split session tests; document helper API v2 (PR #1281 review)
Addresses findings 2 and 3 from PR #1281 review (finding 1, viewport session-stop ordering, was already fixed in 5961b92). - Extract SnapshotInstrumentation.java's one-shot/session touch dispatch into TouchCommandHandler.java (viewport/gesture population, UiAutomation- parameterized) and SessionResponseWriter.java (session response encoding), with shared PROTOCOL/HELPER_API_VERSION/OUTPUT_FORMAT constants moved to a tiny HelperProtocol.java. SnapshotInstrumentation.java shrinks from 908 to 803 lines; wire format (header keys/values, error shapes) is unchanged. - Split touch-helper.test.ts (~720 lines) into touch-helper.test.ts (normalize/parse/one-shot gesture+viewport+result envelope) and touch-helper-session.test.ts (persistent-session transport + fake-session harness), moving shared device/plan/install-probe fixtures used by both files into touch-helper.fixtures.ts. - Update android/snapshot-helper/README.md to document helper API v2: the one-shot viewport/gesture modes, the android-touch-plan-v1 payload shape, and the persistent session's socket command/response contract.
1 parent 5961b92 commit ab1743c

8 files changed

Lines changed: 631 additions & 500 deletions

File tree

‎android/snapshot-helper/README.md‎

Lines changed: 51 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,51 @@ can run.
4646
`waitForIdleTimeoutMs` defaults to `500`, which is a maximum wait, not a fixed sleep. Direct helper
4747
invocations can pass `0` when immediate capture during ongoing animation is preferred.
4848

49+
## One-Shot Modes
50+
51+
Passing `-e mode snapshot|viewport|gesture` selects what a single instrumentation run does; `snapshot`
52+
is the default and matches the `Run` section above.
53+
54+
```sh
55+
# Read the interactive-window viewport without capturing a snapshot.
56+
adb shell am instrument -w -e mode viewport \
57+
com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation
58+
59+
# Inject a planned touch gesture, described by a base64 JSON payload.
60+
adb shell am instrument -w -e mode gesture -e payloadBase64 "$PAYLOAD" \
61+
com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation
62+
```
63+
64+
The `gesture` payload is a base64-encoded JSON object using protocol `android-touch-plan-v1`:
65+
66+
- `kind`: `swipe` (one pointer) or `transform` (two pointers, e.g. pinch/rotate)
67+
- `durationMs`: integer, `0`-`120000`
68+
- `pointers`: array of `{ pointerId, samples }`, `pointerId`s ordered from `0`, one pointer for
69+
`swipe` and exactly two for `transform`
70+
- each pointer's `samples` is `{ offsetMs, x, y }[]` with at least two entries; `offsetMs` values
71+
must be strictly increasing (equal offsets are only allowed when `durationMs` is `0`), the first
72+
sample's `offsetMs` must be `0`, and the last must equal `durationMs`. For `transform` gestures,
73+
both pointers must share the same `offsetMs` sequence.
74+
75+
## Persistent Session
76+
77+
Passing `-e sessionPort <port>` keeps the instrumentation alive after startup and serves repeated
78+
commands over a local TCP socket on `127.0.0.1:<port>`, instead of exiting after one snapshot. This
79+
avoids paying UiAutomation connect/teardown cost per call. Each line sent to the socket is one
80+
command; the instrumentation replies once per command and keeps the connection open for the next
81+
one:
82+
83+
- `snapshot <requestId>` — capture and return an XML snapshot, same semantics as the default mode
84+
- `viewport <requestId>` — return interactive-window viewport bounds
85+
- `gesture <requestId> <payloadBase64>` — inject a planned touch gesture (same payload as the
86+
one-shot `gesture` mode)
87+
- `quit <requestId>` — acknowledge and stop the session
88+
89+
`viewport` and `gesture` responses are headers-only (no body): `kind`, `injectedEvents`,
90+
`elapsedMs` for `gesture`, and `x`, `y`, `width`, `height` for `viewport`. `snapshot` responses carry
91+
the XML body after the header block, as described below. The response protocol literal is always
92+
`android-snapshot-helper-v1`, regardless of session or one-shot transport.
93+
4994
## Output Contract
5095

5196
The APK emits instrumentation status records using
@@ -64,10 +109,10 @@ Each XML chunk is sent with:
64109
- `chunkCount`
65110
- `payloadBase64`
66111

67-
The final instrumentation result includes:
112+
The final instrumentation result for the default `snapshot` mode includes:
68113

69114
- `ok=true`
70-
- `helperApiVersion=1`
115+
- `helperApiVersion=2`
71116
- `waitForIdleTimeoutMs`
72117
- `waitForIdleQuietMs`
73118
- `timeoutMs`
@@ -80,6 +125,10 @@ The final instrumentation result includes:
80125
- `truncated`
81126
- `elapsedMs`
82127

128+
`viewport` and `gesture` one-shot results carry `agentDeviceProtocol`/`helperApiVersion`/
129+
`outputFormat` plus the mode-specific fields described under "One-Shot Modes" above, instead of the
130+
`snapshot`-mode fields listed here.
131+
83132
Failures return `ok=false`, `errorType`, and `message` in the final result.
84133

85134
The release manifest is a stable provider contract for the current helper protocol. Providers should
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
package com.callstack.agentdevice.snapshothelper;
2+
3+
/** Wire-protocol constants shared by the one-shot and persistent-session response paths. */
4+
final class HelperProtocol {
5+
static final String PROTOCOL = "android-snapshot-helper-v1";
6+
static final String OUTPUT_FORMAT = "uiautomator-xml";
7+
static final String HELPER_API_VERSION = "2";
8+
9+
private HelperProtocol() {}
10+
}
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
package com.callstack.agentdevice.snapshothelper;
2+
3+
import android.os.Bundle;
4+
import java.io.IOException;
5+
import java.io.OutputStream;
6+
import java.nio.charset.StandardCharsets;
7+
8+
/** Encodes persistent-session socket responses as newline-delimited headers plus a body. */
9+
final class SessionResponseWriter {
10+
private SessionResponseWriter() {}
11+
12+
static Bundle sessionResponseBundle(String requestId) {
13+
Bundle result = new Bundle();
14+
result.putString("agentDeviceProtocol", HelperProtocol.PROTOCOL);
15+
result.putString("helperApiVersion", HelperProtocol.HELPER_API_VERSION);
16+
result.putString("outputFormat", HelperProtocol.OUTPUT_FORMAT);
17+
result.putString("requestId", requestId);
18+
return result;
19+
}
20+
21+
static void writeSessionOk(OutputStream output, String requestId) throws IOException {
22+
Bundle result = sessionResponseBundle(requestId);
23+
result.putString("ok", "true");
24+
writeSessionResponse(output, result, "");
25+
}
26+
27+
static void writeSessionError(
28+
OutputStream output, String requestId, String errorType, String message) throws IOException {
29+
Bundle result = sessionResponseBundle(requestId);
30+
result.putString("ok", "false");
31+
result.putString("errorType", errorType);
32+
result.putString("message", message);
33+
writeSessionResponse(output, result, "");
34+
}
35+
36+
static void writeSessionResponse(OutputStream output, Bundle result, String body)
37+
throws IOException {
38+
StringBuilder headers = new StringBuilder();
39+
for (String key : result.keySet()) {
40+
Object value = result.get(key);
41+
if (value != null) {
42+
headers.append(key).append('=').append(sanitizeHeaderValue(value.toString())).append('\n');
43+
}
44+
}
45+
headers.append('\n');
46+
output.write(headers.toString().getBytes(StandardCharsets.UTF_8));
47+
output.write(body.getBytes(StandardCharsets.UTF_8));
48+
output.flush();
49+
}
50+
51+
private static String sanitizeHeaderValue(String value) {
52+
return value.replace('\r', ' ').replace('\n', ' ');
53+
}
54+
}

‎android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java‎

Lines changed: 21 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,6 @@
2626
import java.util.concurrent.TimeoutException;
2727

2828
public final class SnapshotInstrumentation extends Instrumentation {
29-
private static final String PROTOCOL = "android-snapshot-helper-v1";
30-
private static final String OUTPUT_FORMAT = "uiautomator-xml";
31-
private static final String HELPER_API_VERSION = "2";
3229
private static final long GESTURE_UI_AUTOMATION_CONNECT_TIMEOUT_MS = 8_000;
3330
private static final int CHUNK_SIZE = 2 * 1024;
3431
// Match the host default: bounded wait for microinteraction reliability without the stock
@@ -111,9 +108,9 @@ private static void putBaseMetadata(
111108
long timeoutMs,
112109
int maxDepth,
113110
int maxNodes) {
114-
result.putString("agentDeviceProtocol", PROTOCOL);
115-
result.putString("helperApiVersion", HELPER_API_VERSION);
116-
result.putString("outputFormat", OUTPUT_FORMAT);
111+
result.putString("agentDeviceProtocol", HelperProtocol.PROTOCOL);
112+
result.putString("helperApiVersion", HelperProtocol.HELPER_API_VERSION);
113+
result.putString("outputFormat", HelperProtocol.OUTPUT_FORMAT);
117114
result.putString("waitForIdleTimeoutMs", Long.toString(waitForIdleTimeoutMs));
118115
result.putString("waitForIdleQuietMs", Long.toString(waitForIdleQuietMs));
119116
result.putString("timeoutMs", Long.toString(timeoutMs));
@@ -131,22 +128,12 @@ private static void putCaptureMetadata(Bundle result, CaptureResult capture, lon
131128
}
132129

133130
private void runOneShotViewport(Bundle result) {
134-
android.graphics.Rect viewport =
135-
GestureViewportReader.read(getConnectedUiAutomationUnchecked());
136-
result.putString("ok", "true");
137-
result.putString("kind", "viewport");
138-
putViewportMetadata(result, viewport);
131+
TouchCommandHandler.populateViewport(result, getConnectedUiAutomationUnchecked());
139132
finishSafely(0, result);
140133
}
141134

142135
private void runOneShotGesture(Bundle result, String payloadBase64) throws Exception {
143-
long startedAtMs = System.currentTimeMillis();
144-
TouchPlan plan = TouchPlan.parseBase64(payloadBase64);
145-
int injectedEvents = TouchPlanInjector.inject(getConnectedUiAutomationUnchecked(), plan);
146-
result.putString("ok", "true");
147-
result.putString("kind", plan.kind);
148-
result.putString("injectedEvents", Integer.toString(injectedEvents));
149-
result.putString("elapsedMs", Long.toString(System.currentTimeMillis() - startedAtMs));
136+
TouchCommandHandler.populateGesture(result, getConnectedUiAutomationUnchecked(), payloadBase64);
150137
finishSafely(0, result);
151138
}
152139

@@ -158,13 +145,6 @@ private UiAutomation getConnectedUiAutomationUnchecked() {
158145
}
159146
}
160147

161-
private static void putViewportMetadata(Bundle result, android.graphics.Rect viewport) {
162-
result.putString("x", Integer.toString(viewport.left));
163-
result.putString("y", Integer.toString(viewport.top));
164-
result.putString("width", Integer.toString(viewport.width()));
165-
result.putString("height", Integer.toString(viewport.height()));
166-
}
167-
168148
private void runSnapshotSession(
169149
int sessionPort,
170150
long waitForIdleQuietMs,
@@ -189,27 +169,32 @@ private void runSnapshotSession(
189169
new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8))
190170
.readLine();
191171
if (command == null) {
192-
writeSessionError(socket.getOutputStream(), "", "java.io.EOFException", "empty command");
172+
SessionResponseWriter.writeSessionError(
173+
socket.getOutputStream(), "", "java.io.EOFException", "empty command");
193174
continue;
194175
}
195176
String[] parts = command.trim().split("\\s+", 3);
196177
String action = parts.length > 0 ? parts[0] : "";
197178
String requestId = parts.length > 1 ? parts[1] : "";
198179
if ("quit".equals(action)) {
199-
writeSessionOk(socket.getOutputStream(), requestId);
180+
SessionResponseWriter.writeSessionOk(socket.getOutputStream(), requestId);
200181
return;
201182
}
202183
if ("viewport".equals(action)) {
203-
writeSessionViewport(socket.getOutputStream(), requestId);
184+
TouchCommandHandler.writeSessionViewport(
185+
socket.getOutputStream(), requestId, getConnectedUiAutomationUnchecked());
204186
continue;
205187
}
206188
if ("gesture".equals(action)) {
207-
writeSessionGesture(
208-
socket.getOutputStream(), requestId, parts.length > 2 ? parts[2] : "");
189+
TouchCommandHandler.writeSessionGesture(
190+
socket.getOutputStream(),
191+
requestId,
192+
parts.length > 2 ? parts[2] : "",
193+
getConnectedUiAutomationUnchecked());
209194
continue;
210195
}
211196
if (!"snapshot".equals(action)) {
212-
writeSessionError(
197+
SessionResponseWriter.writeSessionError(
213198
socket.getOutputStream(),
214199
requestId,
215200
"java.lang.IllegalArgumentException",
@@ -248,106 +233,16 @@ private void writeSessionSnapshot(
248233
result.putString("ok", "true");
249234
putCaptureMetadata(result, capture, System.currentTimeMillis() - startedAtMs);
250235
result.putString("byteLength", Integer.toString(capture.xml.getBytes(StandardCharsets.UTF_8).length));
251-
writeSessionResponse(output, result, capture.xml);
236+
SessionResponseWriter.writeSessionResponse(output, result, capture.xml);
252237
} catch (Throwable error) {
253-
writeSessionError(
238+
SessionResponseWriter.writeSessionError(
254239
output,
255240
requestId,
256241
error.getClass().getName(),
257242
error.getMessage() == null ? error.getClass().getName() : error.getMessage());
258243
}
259244
}
260245

261-
private void writeSessionViewport(OutputStream output, String requestId) throws IOException {
262-
Bundle result = sessionResponseBundle(requestId);
263-
try {
264-
android.graphics.Rect viewport =
265-
GestureViewportReader.read(getConnectedUiAutomationUnchecked());
266-
result.putString("ok", "true");
267-
result.putString("kind", "viewport");
268-
putViewportMetadata(result, viewport);
269-
writeSessionResponse(output, result, "");
270-
} catch (Throwable error) {
271-
writeSessionError(
272-
output,
273-
requestId,
274-
error.getClass().getName(),
275-
error.getMessage() == null ? error.getClass().getName() : error.getMessage());
276-
}
277-
}
278-
279-
private void writeSessionGesture(OutputStream output, String requestId, String payloadBase64)
280-
throws IOException {
281-
Bundle result = sessionResponseBundle(requestId);
282-
try {
283-
long startedAtMs = System.currentTimeMillis();
284-
TouchPlan plan = TouchPlan.parseBase64(payloadBase64);
285-
int injectedEvents = TouchPlanInjector.inject(getConnectedUiAutomationUnchecked(), plan);
286-
result.putString("ok", "true");
287-
result.putString("kind", plan.kind);
288-
result.putString("injectedEvents", Integer.toString(injectedEvents));
289-
result.putString("elapsedMs", Long.toString(System.currentTimeMillis() - startedAtMs));
290-
writeSessionResponse(output, result, "");
291-
} catch (Throwable error) {
292-
writeSessionError(
293-
output,
294-
requestId,
295-
error.getClass().getName(),
296-
error.getMessage() == null ? error.getClass().getName() : error.getMessage());
297-
}
298-
}
299-
300-
private static Bundle sessionResponseBundle(String requestId) {
301-
Bundle result = new Bundle();
302-
result.putString("agentDeviceProtocol", PROTOCOL);
303-
result.putString("helperApiVersion", HELPER_API_VERSION);
304-
result.putString("outputFormat", OUTPUT_FORMAT);
305-
result.putString("requestId", requestId);
306-
return result;
307-
}
308-
309-
private static void writeSessionOk(OutputStream output, String requestId) throws IOException {
310-
Bundle result = new Bundle();
311-
result.putString("agentDeviceProtocol", PROTOCOL);
312-
result.putString("helperApiVersion", HELPER_API_VERSION);
313-
result.putString("outputFormat", OUTPUT_FORMAT);
314-
result.putString("requestId", requestId);
315-
result.putString("ok", "true");
316-
writeSessionResponse(output, result, "");
317-
}
318-
319-
private static void writeSessionError(
320-
OutputStream output, String requestId, String errorType, String message) throws IOException {
321-
Bundle result = new Bundle();
322-
result.putString("agentDeviceProtocol", PROTOCOL);
323-
result.putString("helperApiVersion", HELPER_API_VERSION);
324-
result.putString("outputFormat", OUTPUT_FORMAT);
325-
result.putString("requestId", requestId);
326-
result.putString("ok", "false");
327-
result.putString("errorType", errorType);
328-
result.putString("message", message);
329-
writeSessionResponse(output, result, "");
330-
}
331-
332-
private static void writeSessionResponse(OutputStream output, Bundle result, String body)
333-
throws IOException {
334-
StringBuilder headers = new StringBuilder();
335-
for (String key : result.keySet()) {
336-
Object value = result.get(key);
337-
if (value != null) {
338-
headers.append(key).append('=').append(sanitizeHeaderValue(value.toString())).append('\n');
339-
}
340-
}
341-
headers.append('\n');
342-
output.write(headers.toString().getBytes(StandardCharsets.UTF_8));
343-
output.write(body.getBytes(StandardCharsets.UTF_8));
344-
output.flush();
345-
}
346-
347-
private static String sanitizeHeaderValue(String value) {
348-
return value.replace('\r', ' ').replace('\n', ' ');
349-
}
350-
351246
private static String readStringArgument(Bundle arguments, String key) {
352247
if (arguments == null || !arguments.containsKey(key)) {
353248
return null;
@@ -610,9 +505,9 @@ private void emitChunks(String payload) {
610505
int start = index * CHUNK_SIZE;
611506
int end = Math.min(bytes.length, start + CHUNK_SIZE);
612507
Bundle status = new Bundle();
613-
status.putString("agentDeviceProtocol", PROTOCOL);
614-
status.putString("helperApiVersion", HELPER_API_VERSION);
615-
status.putString("outputFormat", OUTPUT_FORMAT);
508+
status.putString("agentDeviceProtocol", HelperProtocol.PROTOCOL);
509+
status.putString("helperApiVersion", HelperProtocol.HELPER_API_VERSION);
510+
status.putString("outputFormat", HelperProtocol.OUTPUT_FORMAT);
616511
status.putString("chunkIndex", Integer.toString(index));
617512
status.putString("chunkCount", Integer.toString(chunkCount));
618513
status.putString(

0 commit comments

Comments
 (0)