Skip to content

Commit ff18615

Browse files
committed
fix: preserve Maestro coordinate swipes on Android
1 parent 952bc37 commit ff18615

23 files changed

Lines changed: 706 additions & 85 deletions

‎docs/adr/0002-persistent-platform-helper-sessions.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,11 @@ part of that first step. The first reliable win is infrastructure reuse, not dat
5151
implementation keeps the existing one-shot instrumentation helper as the fallback for startup,
5252
socket, protocol, and request failures.
5353

54+
Android permits only one reliable instrumentation-owned `UiAutomation` context per device. Before
55+
starting a different instrumentation helper, such as touch synthesis, the daemon must stop the
56+
persistent snapshot helper session and let the next snapshot restart it lazily. Helper reuse must
57+
never turn process ownership into cross-command interference.
58+
5459
For iOS, keep the XCTest runner session as the reference implementation for lifecycle and
5560
invalidation behavior. Android does not need to copy iOS internals, but it should reuse the same
5661
daemon-side ideas: per-device session manager, readiness checks, structured protocol errors,
@@ -82,7 +87,7 @@ should show meaningful wall-clock improvement on a realistic app state, not just
8287

8388
Session managers need more lifecycle tests than one-shot helpers: startup, ready protocol, reuse,
8489
timeout, malformed response, helper version mismatch, device disconnect, install invalidation,
85-
shutdown, and one-shot fallback.
90+
shutdown, exclusive instrumentation handoff, and one-shot fallback.
8691

8792
Observability should report whether a command used a persistent session, started one, reused one,
8893
invalidated one, or fell back to one-shot. This keeps CI and user bug reports diagnosable when a
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import type { SessionAction } from '../../../daemon/types.ts';
4+
import { parseMaestroReplayFlow } from '../replay-flow.ts';
5+
6+
test('bare launchApp uses Maestro default stop-and-relaunch semantics', () => {
7+
const parsed = parseMaestroReplayFlow(`appId: com.pagerviewexample
8+
---
9+
- launchApp
10+
`);
11+
12+
assert.deepEqual(projectAction(parsed.actions[0]), [
13+
'open',
14+
['com.pagerviewexample'],
15+
{ relaunch: true },
16+
]);
17+
});
18+
19+
test('launchApp stopApp false opts out of relaunch', () => {
20+
const parsed = parseMaestroReplayFlow(`appId: com.pagerviewexample
21+
---
22+
- launchApp:
23+
stopApp: false
24+
`);
25+
26+
assert.deepEqual(projectAction(parsed.actions[0]), ['open', ['com.pagerviewexample'], {}]);
27+
});
28+
29+
function projectAction(action: SessionAction | undefined) {
30+
if (!action) throw new Error('expected parsed action');
31+
return [action.command, action.positionals, action.flags];
32+
}
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { parseMaestroReplayFlow } from '../replay-flow.ts';
4+
5+
test('coordinate endpoints take precedence over from like Maestro', () => {
6+
const parsed = parseMaestroReplayFlow(`appId: com.pagerviewexample
7+
---
8+
- swipe:
9+
from:
10+
id: pager-view
11+
start: 90%, 50%
12+
end: 10%, 50%
13+
duration: 100
14+
`);
15+
16+
assert.deepEqual(
17+
parsed.actions.map((entry) => [entry.command, entry.positionals]),
18+
[['__maestroSwipeScreen', ['percent', '90', '50', '10', '50', '100']]],
19+
);
20+
});
21+
22+
test('coordinate swipes require both endpoints even when from is present', () => {
23+
assert.throws(
24+
() =>
25+
parseMaestroReplayFlow(`---
26+
- swipe:
27+
from:
28+
id: pager-view
29+
start: 90%, 50%
30+
`),
31+
/both start and end coordinates/i,
32+
);
33+
});
34+
35+
test('coordinate swipes reject direction like Maestro', () => {
36+
assert.throws(
37+
() =>
38+
parseMaestroReplayFlow(`---
39+
- swipe:
40+
direction: LEFT
41+
start: 90%, 50%
42+
end: 10%, 50%
43+
`),
44+
/cannot combine direction with start\/end coordinates/i,
45+
);
46+
});

‎src/compat/maestro/device-actions.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,13 @@ export function convertLaunchApp(
1616
context: MaestroParseContext,
1717
): SessionAction {
1818
if (value === null || value === undefined) {
19-
return action('open', [resolveMaestroString(requireAppId(config, 'launchApp'), context)]);
19+
return action('open', [resolveMaestroString(requireAppId(config, 'launchApp'), context)], {
20+
relaunch: true,
21+
});
22+
}
23+
if (typeof value === 'string') {
24+
return action('open', [resolveMaestroString(value, context)], { relaunch: true });
2025
}
21-
if (typeof value === 'string') return action('open', [resolveMaestroString(value, context)]);
2226
if (!isPlainRecord(value)) {
2327
throw new AppError('INVALID_ARGS', 'launchApp expects a string or map.');
2428
}
@@ -39,7 +43,7 @@ export function convertLaunchApp(
3943
);
4044
const launchArgs = readLaunchArgs(value, context);
4145
const shouldClearState = value.clearState === true;
42-
const shouldRelaunch = !shouldClearState && (value.stopApp === true || launchArgs.length > 0);
46+
const shouldRelaunch = !shouldClearState && value.stopApp !== false;
4347
return action('open', [appId], {
4448
...(shouldRelaunch ? { relaunch: true } : {}),
4549
...(shouldClearState ? { clearAppState: true } : {}),

‎src/compat/maestro/interactions.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,15 @@ export function convertSwipe(value: unknown, context: MaestroParseContext): Sess
188188
throw new AppError('INVALID_ARGS', 'swipe expects a map.');
189189
}
190190
assertOnlyKeys(value, 'swipe', ['start', 'end', 'direction', 'duration', 'from', 'label']);
191+
// Maestro classifies the command as coordinate-based when either endpoint key is present.
192+
if (Object.hasOwn(value, 'start') || Object.hasOwn(value, 'end')) {
193+
if (value.direction !== undefined) {
194+
throw unsupportedMaestroSyntax(
195+
'Maestro swipe cannot combine direction with start/end coordinates.',
196+
);
197+
}
198+
return convertCoordinateSwipe(value);
199+
}
191200
const from = value.from ?? (typeof value.label === 'string' ? value.label : undefined);
192201
if (from !== undefined) {
193202
return convertTargetedSwipe(value, from, context);
@@ -230,7 +239,7 @@ function readCoordinateSwipePoints(value: Record<string, unknown>): {
230239
if (typeof value.start === 'string' && typeof value.end === 'string') {
231240
return { start: parseMaestroPoint(value.start), end: parseMaestroPoint(value.end) };
232241
}
233-
throw unsupportedMaestroSyntax('Only Maestro swipe start/end coordinates are supported.');
242+
throw unsupportedMaestroSyntax('Maestro swipe requires both start and end coordinates.');
234243
}
235244

236245
function readSwipeDurationMs(duration: unknown): string | undefined {
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import { fileURLToPath } from 'node:url';
2+
3+
export const ANDROID_HELPER_FIXTURE_APK_PATH = fileURLToPath(
4+
new URL('./fixtures/helper-apk.fixture', import.meta.url),
5+
);
6+
7+
export const ANDROID_HELPER_FIXTURE_APK_SHA256 =
8+
'a5f6a2fba1163bba2f13026bd3a192f52ba2816524b7cfa83c6b7ca568f6710a';
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
agent-device Android helper test fixture

‎src/platforms/android/__tests__/ime-helper.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -115,15 +115,15 @@ test('ensureAndroidImeHelper installs with semantic provider install options', a
115115
assert.deepEqual(installCalls, [{ apkPath, replace: true, allowTestPackages: true }]);
116116
});
117117

118-
test('ensureAndroidImeHelper skips install when an equal-or-newer version is already present', async () => {
118+
test('ensureAndroidImeHelper skips install when a newer version is already present', async () => {
119119
const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ime-helper-current-'));
120120
const apkPath = path.join(tmpDir, 'helper.apk');
121121
await fs.writeFile(apkPath, 'helper-apk');
122122
const adb: AndroidAdbExecutor = async (args) => {
123123
if (args.includes('--show-versioncode')) {
124124
return {
125125
exitCode: 0,
126-
stdout: `package:${manifest.packageName} versionCode:${manifest.versionCode}`,
126+
stdout: `package:${manifest.packageName} versionCode:${manifest.versionCode + 1}`,
127127
stderr: '',
128128
};
129129
}
@@ -132,7 +132,7 @@ test('ensureAndroidImeHelper skips install when an equal-or-newer version is alr
132132
const adbProvider: AndroidAdbProvider = {
133133
exec: adb,
134134
install: async () => {
135-
throw new Error('install should not be called when the version is current');
135+
throw new Error('install should not be called when a newer version is present');
136136
},
137137
};
138138

‎src/platforms/android/__tests__/ime-lifecycle.test.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,16 @@ const PENDING_DIR = 'android-test-ime-pending';
1212
// the suite passes on a fresh checkout that hasn't packaged android-ime-helper/dist (CI Coverage).
1313
vi.mock('../ime-helper.ts', async (importOriginal) => {
1414
const actual = await importOriginal<typeof import('../ime-helper.ts')>();
15+
const fixture = await import('./android-helper-artifact.fixtures.ts');
1516
return {
1617
...actual,
1718
resolveAndroidImeHelperArtifact: vi.fn(async () => ({
18-
apkPath: '/fixture/helper.apk',
19+
apkPath: fixture.ANDROID_HELPER_FIXTURE_APK_PATH,
1920
manifest: {
2021
name: 'android-ime-helper' as const,
2122
version: '0.0.0',
2223
assetName: 'helper.apk',
23-
sha256: 'a'.repeat(64),
24+
sha256: fixture.ANDROID_HELPER_FIXTURE_APK_SHA256,
2425
packageName: 'com.callstack.agentdevice.imehelper',
2526
versionCode: 1,
2627
serviceComponent: HELPER_SERVICE,

0 commit comments

Comments
 (0)