diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AutomationCommandHandler.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AutomationCommandHandler.java index 4b1868f965..7e1f63eb75 100644 --- a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AutomationCommandHandler.java +++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AutomationCommandHandler.java @@ -57,59 +57,165 @@ private static final class InputDispatch { boolean attempted; } + /** + * The budget of a host that sends none: a provider-supplied helper can be newer than its host, and + * an older host waits 30 s for input, less the 5 s answer margin. It never affords a retry. + */ + private static final long OLDER_HOST_BUDGET_MS = 25_000; + + /** The framework's accessibility interaction timeout, AccessibilityInteractionClient. */ + private static final long TEXT_ENTRY_RESERVE_MS = 5_000; + + /** The command deadline left too little time for the next step, so it was not started. */ + static final class InputBudgetExhausted extends IllegalStateException { + InputBudgetExhausted(String message) { + super(message); + } + } + + /** Refuses text entry the deadline cannot fit, after a focus tap that may have used the budget. */ + static void requireTextEntryTime(long deadline, long now) { + if (deadline - now < TEXT_ENTRY_RESERVE_MS) { + throw new InputBudgetExhausted("Fill text was not entered: too little time left after focus"); + } + } + private static void input(UiAutomation automation, JSONObject input, InputDispatch dispatch) throws Exception { + // The host's remaining time for this command bounds every retry decision. + long deadline = + SystemClock.uptimeMillis() + input.optLong("budgetMs", OLDER_HOST_BUDGET_MS); switch (input.getString("kind")) { case "tap": - tap(automation, input.getDouble("x"), input.getDouble("y"), dispatch); + tap(automation, input.getDouble("x"), input.getDouble("y"), dispatch, deadline); return; case "key": - key(automation, input.getInt("keyCode"), dispatch); + key(automation, input.getInt("keyCode"), dispatch, deadline); return; case "fill": - fill(automation, input.getInt("x"), input.getInt("y"), input.getString("text"), dispatch); + fill(automation, input.getInt("x"), input.getInt("y"), input.getString("text"), dispatch, + deadline); return; default: throw new IllegalArgumentException("Unknown input kind"); } } - private static void tap(UiAutomation automation, double x, double y, InputDispatch dispatch) { + private static void tap( + UiAutomation automation, double x, double y, InputDispatch dispatch, long deadline) { if (Double.isNaN(x) || Double.isInfinite(x) || Double.isNaN(y) || Double.isInfinite(y) || x < 0 || y < 0) { throw new IllegalArgumentException("Invalid tap coordinates"); } - long down = SystemClock.uptimeMillis(); - touch(automation, down, MotionEvent.ACTION_DOWN, (float) x, (float) y, dispatch); - touch(automation, down, MotionEvent.ACTION_UP, (float) x, (float) y, dispatch); + dispatch.attempted = true; + PressSequence.requireDispatched(PressSequence.run(new TouchPress(automation, (float) x, (float) y), deadline), "Touch"); } - private static void touch(UiAutomation automation, long down, int action, float x, float y, InputDispatch dispatch) { - MotionEvent event = MotionEvent.obtain(down, SystemClock.uptimeMillis(), action, x, y, 0); - event.setSource(InputDevice.SOURCE_TOUCHSCREEN); - try { - dispatch.attempted = true; - if (!automation.injectInputEvent(event, true)) { - throw new IllegalStateException("Touch injection was refused"); - } - } finally { - event.recycle(); + private static void key(UiAutomation automation, int code, InputDispatch dispatch, long deadline) { + if (code < 0 || code > KeyEvent.getMaxKeyCode()) throw new IllegalArgumentException("Invalid key code"); + dispatch.attempted = true; + PressSequence.requireDispatched(PressSequence.run(new KeyPress(automation, code), deadline), "Key"); + } + + private abstract static class Press implements PressSequence.Injections { + final UiAutomation automation; + + Press(UiAutomation automation) { + this.automation = automation; + } + + @Override + public long now() { + return SystemClock.uptimeMillis(); + } + + @Override + public boolean skipsAnimationWait() { + return UiAutomationInputDispatcher.skipsAnimationWait(); + } + + @Override + public boolean awaitAnimations() { + return UiAutomationInputDispatcher.awaitAnimations(automation); } } - private static void key(UiAutomation automation, int code, InputDispatch dispatch) { - if (code < 0 || code > KeyEvent.getMaxKeyCode()) throw new IllegalArgumentException("Invalid key code"); - long down = SystemClock.uptimeMillis(); - for (int action : new int[] {KeyEvent.ACTION_DOWN, KeyEvent.ACTION_UP}) { - KeyEvent event = new KeyEvent(down, SystemClock.uptimeMillis(), action, code, 0, 0, - KeyCharacterMap.VIRTUAL_KEYBOARD, 0, 0, InputDevice.SOURCE_KEYBOARD); - dispatch.attempted = true; - if (!automation.injectInputEvent(event, true)) { - throw new IllegalStateException("Key injection was refused"); + private static final class TouchPress extends Press { + private final float x; + private final float y; + + TouchPress(UiAutomation automation, float x, float y) { + super(automation); + this.x = x; + this.y = y; + } + + @Override + public boolean start(long downTime) { + return inject(MotionEvent.ACTION_DOWN, downTime, 0, true); + } + + @Override + public boolean end(long downTime) { + return inject(MotionEvent.ACTION_UP, downTime, 0, true); + } + + /** Not awaited: a window that received a timed-out DOWN may not finish handling the cancel. */ + @Override + public void releaseRefusedStart(long downTime) { + inject(MotionEvent.ACTION_CANCEL, downTime, MotionEvent.FLAG_CANCELED, false); + } + + private boolean inject(int action, long downTime, int flags, boolean waitForDispatch) { + MotionEvent event = TouchEvents.obtain( + downTime, SystemClock.uptimeMillis(), action, new float[] {x}, new float[] {y}, flags); + try { + return UiAutomationInputDispatcher.inject(automation, event, waitForDispatch); + } finally { + event.recycle(); } } } - private static void fill(UiAutomation automation, int x, int y, String text, InputDispatch dispatch) { + private static final class KeyPress extends Press { + private final int code; + + KeyPress(UiAutomation automation, int code) { + super(automation); + this.code = code; + } + + @Override + public boolean start(long downTime) { + return inject(KeyEvent.ACTION_DOWN, downTime, 0, true); + } + + @Override + public boolean end(long downTime) { + return inject(KeyEvent.ACTION_UP, downTime, 0, true); + } + + /** + * Android releases an interrupted key with an ACTION_UP that carries FLAG_CANCELED; receivers + * take no action on a canceled up. Not awaited, like the touch cancel. + */ + @Override + public void releaseRefusedStart(long downTime) { + inject(KeyEvent.ACTION_UP, downTime, KeyEvent.FLAG_CANCELED, false); + } + + private boolean inject(int action, long downTime, int flags, boolean waitForDispatch) { + return UiAutomationInputDispatcher.inject( + automation, event(action, downTime, flags), waitForDispatch); + } + + private KeyEvent event(int action, long downTime, int flags) { + return new KeyEvent(downTime, SystemClock.uptimeMillis(), action, code, 0, 0, + KeyCharacterMap.VIRTUAL_KEYBOARD, 0, flags, InputDevice.SOURCE_KEYBOARD); + } + } + + private static void fill( + UiAutomation automation, int x, int y, String text, InputDispatch dispatch, long deadline) { AccessibilityNodeInfo target = null; try { for (AccessibilityWindowInfo window : automation.getWindows()) { @@ -134,7 +240,8 @@ private static void fill(UiAutomation automation, int x, int y, String text, Inp } } if (target == null) throw new IllegalStateException("No editable field at the fill point"); - tap(automation, x, y, dispatch); + tap(automation, x, y, dispatch, deadline); + requireTextEntryTime(deadline, SystemClock.uptimeMillis()); if (!target.refresh()) throw new IllegalStateException("Fill target disappeared after focus"); if (!target.isFocused() && !target.performAction(AccessibilityNodeInfo.ACTION_FOCUS)) { throw new IllegalStateException("Field focus was refused"); diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/PressSequence.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/PressSequence.java new file mode 100644 index 0000000000..0c7fbf23dd --- /dev/null +++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/PressSequence.java @@ -0,0 +1,94 @@ +package com.callstack.agentdevice.snapshothelper; + +/** + * Sequences one tap or key press: a start event, then an end event with the same down time. + * + *

Every refused start is released before anything else is decided: the verifier and the policy + * record a start even when the dispatcher drops it, and a start refused by the injection timeout + * was delivered. Without the framework's animation wait, a start is often refused only because a + * transition leaves nothing able to receive it, so it is retried once after the animation sync, + * with a fresh down time, when the host's deadline still has room for that retry. + */ +final class PressSequence { + /** + * The room a retry decision reserves: the framework's animation-sync cap + * ({@code WindowManagerService.ANIMATION_COMPLETED_TIMEOUT_MS}) plus the retried start's injection + * deadline ({@code InputManagerService.INJECTION_TIMEOUT_MILLIS}). The end is not reserved: it + * blocks only while the app does not finish handling it, which a press without a retry meets the + * same way, and a 60 s press request could never reserve a second 30 s deadline. + */ + static final long RETRY_WORST_CASE_MS = 5_000 + 30_000; + + /** Builds and injects the platform events of one press. */ + interface Injections { + long now(); + + /** Whether {@link #start} skips the framework's animation wait on this runtime. */ + boolean skipsAnimationWait(); + + boolean start(long downTime); + + boolean end(long downTime); + + /** Releases a refused start that has this down time; the receiver may hold it. */ + void releaseRefusedStart(long downTime); + + /** Waits for the framework's animation sync; false when the runtime cannot wait separately. */ + boolean awaitAnimations(); + } + + enum Outcome { + DISPATCHED, + START_REFUSED, + END_REFUSED, + ANIMATION_SYNC_UNAVAILABLE, + } + + private PressSequence() {} + + /** Runs one press that must answer by {@code deadline}, on the {@link Injections#now} clock. */ + static Outcome run(Injections injections, long deadline) { + long downTime = injections.now(); + if (!injections.start(downTime)) { + release(injections, downTime); + if (!injections.skipsAnimationWait() + || deadline - injections.now() < RETRY_WORST_CASE_MS) { + return Outcome.START_REFUSED; + } + if (!injections.awaitAnimations()) return Outcome.ANIMATION_SYNC_UNAVAILABLE; + downTime = injections.now(); + if (!injections.start(downTime)) { + release(injections, downTime); + return Outcome.START_REFUSED; + } + } + // A refused end gets no cancel. The verifier records an event before the dispatcher drops it, + // so the press is closed there and a cancel would be inconsistent. The dispatcher drops an end + // only when no pointer or focus is still down, after it cancelled the receiving window itself + // ("touched window was removed", "focus left window"). A timed-out end was already enqueued, + // so the live window still receives it. + return injections.end(downTime) ? Outcome.DISPATCHED : Outcome.END_REFUSED; + } + + /** Turns an outcome into the helper's response: a typed exception for each failed press. */ + static void requireDispatched(Outcome outcome, String kind) { + switch (outcome) { + case DISPATCHED: + return; + case ANIMATION_SYNC_UNAVAILABLE: + throw new UnsupportedOperationException( + kind + " injection was refused and this runtime cannot wait for animations to retry it"); + case START_REFUSED: + case END_REFUSED: + throw new IllegalStateException(kind + " injection was refused"); + } + } + + private static void release(Injections injections, long downTime) { + try { + injections.releaseRefusedStart(downTime); + } catch (RuntimeException ignored) { + // The refused start stays the reported outcome. + } + } +} diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/TouchEvents.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/TouchEvents.java new file mode 100644 index 0000000000..d1630cbe3d --- /dev/null +++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/TouchEvents.java @@ -0,0 +1,31 @@ +package com.callstack.agentdevice.snapshothelper; + +import android.view.InputDevice; +import android.view.MotionEvent; + +/** Builds the touchscreen finger events that taps and touch plans inject. */ +final class TouchEvents { + private TouchEvents() {} + + /** One pointer per coordinate pair; pointer ids follow the array order. */ + static MotionEvent obtain( + long downTime, long eventTime, int action, float[] x, float[] y, int flags) { + int count = x.length; + MotionEvent.PointerProperties[] properties = new MotionEvent.PointerProperties[count]; + MotionEvent.PointerCoords[] coords = new MotionEvent.PointerCoords[count]; + for (int index = 0; index < count; index += 1) { + properties[index] = new MotionEvent.PointerProperties(); + properties[index].id = index; + properties[index].toolType = MotionEvent.TOOL_TYPE_FINGER; + coords[index] = new MotionEvent.PointerCoords(); + coords[index].x = x[index]; + coords[index].y = y[index]; + coords[index].pressure = 1.0f; + coords[index].size = 1.0f; + } + MotionEvent event = MotionEvent.obtain(downTime, eventTime, action, count, properties, coords, + 0, 0, 1.0f, 1.0f, 0, 0, InputDevice.SOURCE_TOUCHSCREEN, flags); + event.setSource(InputDevice.SOURCE_TOUCHSCREEN); + return event; + } +} diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/TouchPlanInjector.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/TouchPlanInjector.java index 315205cb7a..76413e0f49 100644 --- a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/TouchPlanInjector.java +++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/TouchPlanInjector.java @@ -2,7 +2,6 @@ import android.app.UiAutomation; import android.os.SystemClock; -import android.view.InputDevice; import android.view.MotionEvent; /** Injects a validated touch plan through UiAutomation with real-time sample pacing. */ @@ -104,37 +103,7 @@ private static void injectCancel( private static MotionEvent motionEvent( long downTime, long eventTime, int action, PointerState pointers) { - MotionEvent.PointerProperties[] properties = - new MotionEvent.PointerProperties[pointers.count]; - MotionEvent.PointerCoords[] coords = new MotionEvent.PointerCoords[pointers.count]; - for (int index = 0; index < pointers.count; index += 1) { - properties[index] = new MotionEvent.PointerProperties(); - properties[index].id = index; - properties[index].toolType = MotionEvent.TOOL_TYPE_FINGER; - coords[index] = new MotionEvent.PointerCoords(); - coords[index].x = pointers.x[index]; - coords[index].y = pointers.y[index]; - coords[index].pressure = 1.0f; - coords[index].size = 1.0f; - } - MotionEvent event = - MotionEvent.obtain( - downTime, - eventTime, - action, - pointers.count, - properties, - coords, - 0, - 0, - 1.0f, - 1.0f, - 0, - 0, - InputDevice.SOURCE_TOUCHSCREEN, - 0); - event.setSource(InputDevice.SOURCE_TOUCHSCREEN); - return event; + return TouchEvents.obtain(downTime, eventTime, action, pointers.x, pointers.y, 0); } private static final class PointerState { diff --git a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/UiAutomationInputDispatcher.java b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/UiAutomationInputDispatcher.java index 791edf083d..104413cfe2 100644 --- a/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/UiAutomationInputDispatcher.java +++ b/android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/UiAutomationInputDispatcher.java @@ -6,14 +6,16 @@ import java.lang.reflect.Method; /** - * Dispatches planned input without the framework's global animation synchronization. + * Dispatches input without the framework's global animation synchronization. * - *

The public two-argument overload waits for global animations before every event. Android's - * three-argument test API separates that policy from synchronous input dispatch, but the SDK stub - * hides the method, so the helper resolves it from the runtime framework. + *

The public two-argument overload waits for global animations before a gesture's first event + * and after its last one, up to five seconds each. Android's three-argument test API separates that + * policy from synchronous input dispatch, but the SDK stub hides the method, so the helper resolves + * it from the runtime framework. */ final class UiAutomationInputDispatcher { private static volatile Method injectWithoutAnimationWait = findInjectWithoutAnimationWait(); + private static volatile Method syncInputTransactions = findSyncInputTransactions(); private UiAutomationInputDispatcher() {} @@ -32,6 +34,30 @@ static boolean inject(UiAutomation automation, InputEvent event, boolean waitFor } } + /** Whether injection skips the framework's animation wait on this runtime. */ + static boolean skipsAnimationWait() { + return injectWithoutAnimationWait != null; + } + + /** + * Waits for the framework's animation sync. Returns false when the runtime does not expose or + * permit the separate sync. + */ + static boolean awaitAnimations(UiAutomation automation) { + Method method = syncInputTransactions; + if (method == null) return false; + try { + method.invoke(automation); + return true; + } catch (IllegalAccessException | IllegalArgumentException error) { + syncInputTransactions = null; + return false; + } catch (InvocationTargetException error) { + rethrowCause(error.getCause()); + throw new AssertionError("Unreachable"); + } + } + private static Method findInjectWithoutAnimationWait() { try { return UiAutomation.class.getMethod( @@ -41,6 +67,14 @@ private static Method findInjectWithoutAnimationWait() { } } + private static Method findSyncInputTransactions() { + try { + return UiAutomation.class.getMethod("syncInputTransactions"); + } catch (NoSuchMethodException | SecurityException error) { + return null; + } + } + private static void rethrowCause(Throwable cause) { if (cause instanceof RuntimeException) throw (RuntimeException) cause; if (cause instanceof Error) throw (Error) cause; diff --git a/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/FillTextEntryTimeTest.java b/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/FillTextEntryTimeTest.java new file mode 100644 index 0000000000..1aa9467942 --- /dev/null +++ b/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/FillTextEntryTimeTest.java @@ -0,0 +1,27 @@ +package com.callstack.agentdevice.snapshothelper; + +public final class FillTextEntryTimeTest { + private FillTextEntryTimeTest() {} + + static void run() { + entersTextWhenTheAccessibilityTimeoutStillFits(); + refusesTextEntryWithATypedBudgetRefusalWhenItNoLongerFits(); + } + + private static void entersTextWhenTheAccessibilityTimeoutStillFits() { + AutomationCommandHandler.requireTextEntryTime(15_000, 10_000); + } + + private static void refusesTextEntryWithATypedBudgetRefusalWhenItNoLongerFits() { + try { + AutomationCommandHandler.requireTextEntryTime(14_999, 10_000); + } catch (AutomationCommandHandler.InputBudgetExhausted refusal) { + String expected = "Fill text was not entered: too little time left after focus"; + if (!expected.equals(refusal.getMessage())) { + throw new AssertionError("Expected " + expected + ", got " + refusal.getMessage()); + } + return; + } + throw new AssertionError("Expected the text entry to be refused"); + } +} diff --git a/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/PressSequenceTest.java b/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/PressSequenceTest.java new file mode 100644 index 0000000000..56de9feeba --- /dev/null +++ b/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/PressSequenceTest.java @@ -0,0 +1,190 @@ +package com.callstack.agentdevice.snapshothelper; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +public final class PressSequenceTest { + private static final long ROOM = PressSequence.RETRY_WORST_CASE_MS; + /** A deadline far enough away that it never limits the press. */ + private static final long OPEN = Long.MAX_VALUE / 2; + + private PressSequenceTest() {} + + static void run() { + endsWithTheStartDownTime(); + releasesARefusedStartAndRetriesItAfterTheSyncWithAFreshDownTime(); + retriesWhenTheDeadlineLeavesExactlyRoomForTheRetry(); + releasesWithoutRetryingWhenTheDeadlineLeavesNoRoomForTheRetry(); + releasesWithoutRetryingAStartRefusedLateInTheBudget(); + releasesAStartRefusedAgainAfterTheSync(); + doesNotCancelARefusedEnd(); + releasesAndFailsADroppedStartAtOnceWhenInjectionWaitsForAnimations(); + reportsAnUnavailableAnimationSyncApartFromARefusal(); + retriesWhenTheReleaseThrows(); + failsARefusedPressAsARefusal(); + failsAnUnavailableSyncAsUnsupported(); + } + + private static void endsWithTheStartDownTime() { + FakeInjections injections = new FakeInjections(accepted()); + expect(PressSequence.run(injections, OPEN), PressSequence.Outcome.DISPATCHED); + expect(injections.calls, "start 1", "end 1"); + } + + private static void releasesARefusedStartAndRetriesItAfterTheSyncWithAFreshDownTime() { + FakeInjections injections = new FakeInjections(refusedAfter(0), accepted()); + expect(PressSequence.run(injections, OPEN), PressSequence.Outcome.DISPATCHED); + expect(injections.calls, "start 1", "release 1", "sync", "start 3", "end 3"); + } + + private static void retriesWhenTheDeadlineLeavesExactlyRoomForTheRetry() { + FakeInjections injections = new FakeInjections(refusedAfter(0), accepted()); + expect(PressSequence.run(injections, 2 + ROOM), PressSequence.Outcome.DISPATCHED); + expect(injections.calls, "start 1", "release 1", "sync", "start 3", "end 3"); + } + + private static void releasesWithoutRetryingWhenTheDeadlineLeavesNoRoomForTheRetry() { + FakeInjections injections = new FakeInjections(refusedAfter(0), accepted()); + expect(PressSequence.run(injections, 1 + ROOM), PressSequence.Outcome.START_REFUSED); + expect(injections.calls, "start 1", "release 1"); + } + + private static void releasesWithoutRetryingAStartRefusedLateInTheBudget() { + FakeInjections injections = new FakeInjections(refusedAfter(30_000), accepted()); + expect(PressSequence.run(injections, 40_000), PressSequence.Outcome.START_REFUSED); + expect(injections.calls, "start 1", "release 1"); + } + + private static void releasesAStartRefusedAgainAfterTheSync() { + FakeInjections injections = new FakeInjections(refusedAfter(0), refusedAfter(0)); + expect(PressSequence.run(injections, OPEN), PressSequence.Outcome.START_REFUSED); + expect(injections.calls, "start 1", "release 1", "sync", "start 3", "release 3"); + } + + private static void doesNotCancelARefusedEnd() { + FakeInjections injections = new FakeInjections(accepted()); + injections.endAccepted = false; + expect(PressSequence.run(injections, OPEN), PressSequence.Outcome.END_REFUSED); + expect(injections.calls, "start 1", "end 1"); + } + + private static void releasesAndFailsADroppedStartAtOnceWhenInjectionWaitsForAnimations() { + FakeInjections injections = new FakeInjections(refusedAfter(0), accepted()); + injections.skipsAnimationWait = false; + expect(PressSequence.run(injections, OPEN), PressSequence.Outcome.START_REFUSED); + expect(injections.calls, "start 1", "release 1"); + } + + private static void reportsAnUnavailableAnimationSyncApartFromARefusal() { + FakeInjections injections = new FakeInjections(refusedAfter(0), accepted()); + injections.syncAvailable = false; + expect(PressSequence.run(injections, OPEN), PressSequence.Outcome.ANIMATION_SYNC_UNAVAILABLE); + expect(injections.calls, "start 1", "release 1", "sync"); + } + + private static void retriesWhenTheReleaseThrows() { + FakeInjections injections = new FakeInjections(refusedAfter(0), accepted()); + injections.releaseThrows = true; + expect(PressSequence.run(injections, OPEN), PressSequence.Outcome.DISPATCHED); + expect(injections.calls, "start 1", "release 1", "sync", "start 3", "end 3"); + } + + private static void failsARefusedPressAsARefusal() { + FakeInjections injections = new FakeInjections(refusedAfter(0), refusedAfter(0)); + expectFailure(injections, IllegalStateException.class, "Key injection was refused"); + } + + private static void failsAnUnavailableSyncAsUnsupported() { + FakeInjections injections = new FakeInjections(refusedAfter(0), accepted()); + injections.syncAvailable = false; + expectFailure(injections, UnsupportedOperationException.class, + "Key injection was refused and this runtime cannot wait for animations to retry it"); + } + + private static void expectFailure( + FakeInjections injections, Class type, String message) { + try { + PressSequence.requireDispatched(PressSequence.run(injections, OPEN), "Key"); + } catch (RuntimeException error) { + if (error.getClass() != type || !message.equals(error.getMessage())) { + throw new AssertionError("Expected " + type.getName() + ": " + message + ", got " + error); + } + return; + } + throw new AssertionError("Expected " + type.getName() + ", but the press dispatched"); + } + + /** A start the framework accepts at once. */ + private static long accepted() { + return -1; + } + + /** A start the framework refuses after this many milliseconds. */ + private static long refusedAfter(long elapsedMs) { + return elapsedMs; + } + + private static void expect(PressSequence.Outcome actual, PressSequence.Outcome expected) { + if (actual != expected) throw new AssertionError("Expected " + expected + ", got " + actual); + } + + private static void expect(List actual, String... expected) { + if (!actual.equals(Arrays.asList(expected))) { + throw new AssertionError("Expected " + Arrays.asList(expected) + ", got " + actual); + } + } + + /** Each {@code now()} advances the clock by 1 ms; a refused start also advances it by its delay. */ + private static final class FakeInjections implements PressSequence.Injections { + final List calls = new ArrayList<>(); + private final long[] starts; + private int startIndex; + private long clock; + boolean skipsAnimationWait = true; + boolean syncAvailable = true; + boolean endAccepted = true; + boolean releaseThrows; + + FakeInjections(long... starts) { + this.starts = starts; + } + + @Override + public long now() { + return ++clock; + } + + @Override + public boolean skipsAnimationWait() { + return skipsAnimationWait; + } + + @Override + public boolean start(long downTime) { + calls.add("start " + downTime); + long refusedAfterMs = starts[startIndex++]; + if (refusedAfterMs < 0) return true; + clock += refusedAfterMs; + return false; + } + + @Override + public boolean end(long downTime) { + calls.add("end " + downTime); + return endAccepted; + } + + @Override + public void releaseRefusedStart(long downTime) { + calls.add("release " + downTime); + if (releaseThrows) throw new IllegalStateException("release failed"); + } + + @Override + public boolean awaitAnimations() { + calls.add("sync"); + return syncAvailable; + } + } +} diff --git a/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/SnapshotHelperTestSuite.java b/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/SnapshotHelperTestSuite.java index faca37a485..43209ba1b0 100644 --- a/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/SnapshotHelperTestSuite.java +++ b/android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/SnapshotHelperTestSuite.java @@ -5,6 +5,8 @@ private SnapshotHelperTestSuite() {} public static void main(String[] args) throws Exception { PointerEventScheduleTest.run(); + PressSequenceTest.run(); + FillTextEntryTimeTest.run(); AccessibilityCaptureStabilizerTest.run(); AccessibilityReadBatchTest.run(); AccessibilityTreeXmlTest.run(); diff --git a/packages/platform-android/src/__tests__/touch-helper-session.test.ts b/packages/platform-android/src/__tests__/touch-helper-session.test.ts index c9da0919b4..2947e435e0 100644 --- a/packages/platform-android/src/__tests__/touch-helper-session.test.ts +++ b/packages/platform-android/src/__tests__/touch-helper-session.test.ts @@ -727,10 +727,11 @@ test('input actions reuse the live automation socket without adb input calls', a await pressAndroidEnter(device); }, ); + // Outside a request deadline, each command gets the host's input cap less its answer margin. assert.deepEqual(inputs, [ - { kind: 'tap', x: 12, y: 34 }, - { kind: 'key', keyCode: 4 }, - { kind: 'key', keyCode: 66 }, + { kind: 'tap', x: 12, y: 34, budgetMs: 40_000 }, + { kind: 'key', keyCode: 4, budgetMs: 40_000 }, + { kind: 'key', keyCode: 66, budgetMs: 40_000 }, ]); assert.equal( adbCalls.some((args) => args.includes('input')), diff --git a/packages/platform-android/src/automation-helper-input-budget.test.ts b/packages/platform-android/src/automation-helper-input-budget.test.ts new file mode 100644 index 0000000000..61eabeb0f1 --- /dev/null +++ b/packages/platform-android/src/automation-helper-input-budget.test.ts @@ -0,0 +1,84 @@ +import { beforeEach, expect, test, vi } from 'vitest'; + +vi.mock('./snapshot-helper-session-lifecycle.ts', () => ({ + getLiveAndroidSnapshotHelperSession: () => ({ commands: new Set(['input']) }), + stopAndroidSnapshotHelperSession: vi.fn(), +})); +vi.mock('./automation-helper-artifact.ts', () => ({ + prepareAndroidAutomationHelper: vi.fn(async () => ({ artifact: {} })), + androidAutomationHelperIdentity: vi.fn(() => ({})), +})); +vi.mock('./snapshot-helper-session.ts', () => ({ + runAndroidSnapshotHelperSessionTouchCommand: vi.fn(async () => ({ ok: 'true' })), +})); +import type { DaemonResponse } from '@agent-device/kernel/contracts'; +import { AppError } from '@agent-device/kernel/errors'; +import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics'; +import { withRequestDeadline } from '@agent-device/host-kit/request'; +import { runAndroidAutomationHelper } from './automation-helper.ts'; +import { prepareAndroidAutomationHelper } from './automation-helper-artifact.ts'; +import { runAndroidSnapshotHelperSessionTouchCommand } from './snapshot-helper-session.ts'; +import { stopAndroidSnapshotHelperSession } from './snapshot-helper-session-lifecycle.ts'; +import { ANDROID_EMULATOR } from './__tests__/test-utils/device-fixtures.ts'; + +beforeEach(() => { + vi.clearAllMocks(); +}); + +function tap() { + return runAndroidAutomationHelper(ANDROID_EMULATOR, { + action: 'input', + input: { kind: 'tap', x: 10, y: 20 }, + }); +} + +async function withinRequestDeadline(remainingMs: number, run: () => Promise): Promise { + let result: T | undefined; + const requestId = `budget-${remainingMs}-${Math.random()}`; + await withDiagnosticsScope({ requestId }, () => + withRequestDeadline(requestId, remainingMs, async () => { + result = await run(); + return { ok: true } as unknown as DaemonResponse; + }), + ); + return result as T; +} + +function sentCommand() { + const [command] = vi.mocked(runAndroidSnapshotHelperSessionTouchCommand).mock.calls[0]!; + const payload = JSON.parse(Buffer.from(command.payloadBase64!, 'base64').toString('utf8')); + return { payload, timeoutMs: command.timeoutMs }; +} + +test('without a request deadline, input carries the host cap less the answer margin', async () => { + await expect(tap()).resolves.toBe(true); + const { payload, timeoutMs } = sentCommand(); + expect(payload).toMatchObject({ kind: 'tap', x: 10, y: 20 }); + expect(payload.budgetMs).toBe(timeoutMs - 5_000); +}); + +test('a request with room sends the helper only what remains of its deadline', async () => { + await withinRequestDeadline(34_000, tap); + const { payload, timeoutMs } = sentCommand(); + expect(timeoutMs).toBeLessThanOrEqual(34_000); + expect(timeoutMs).toBeGreaterThan(32_000); + expect(payload.budgetMs).toBe(timeoutMs - 5_000); +}); + +test('a request with room for one attempt but not the answer margin sends a zero budget', async () => { + await withinRequestDeadline(3_000, tap); + expect(sentCommand().payload.budgetMs).toBe(0); +}); + +test('a request without room for one attempt is refused before anything reaches the helper', async () => { + const refusal = await withinRequestDeadline(1_000, () => tap().catch((error: unknown) => error)); + expect(refusal).toBeInstanceOf(AppError); + expect((refusal as AppError).details).toMatchObject({ + reason: 'android-input-budget-exhausted', + minimumMs: 2_000, + dispatched: 'no', + }); + expect(runAndroidSnapshotHelperSessionTouchCommand).not.toHaveBeenCalled(); + expect(prepareAndroidAutomationHelper).not.toHaveBeenCalled(); + expect(stopAndroidSnapshotHelperSession).not.toHaveBeenCalled(); +}); diff --git a/packages/platform-android/src/automation-helper.ts b/packages/platform-android/src/automation-helper.ts index 10040b1cd1..3331fad5de 100644 --- a/packages/platform-android/src/automation-helper.ts +++ b/packages/platform-android/src/automation-helper.ts @@ -4,7 +4,8 @@ import { getLiveAndroidSnapshotHelperSession, stopAndroidSnapshotHelperSession, } from './snapshot-helper-session-lifecycle.ts'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; +import { emitDiagnostic, getDiagnosticsMeta } from '@agent-device/host-kit/diagnostics'; +import { getRequestDeadlineMs } from '@agent-device/host-kit/request'; import { getAndroidSnapshotHelperSessionDeviceKey } from './snapshot-helper-retirement.ts'; import { runAndroidSnapshotHelperSessionTouchCommand } from './snapshot-helper-session.ts'; import { @@ -38,12 +39,24 @@ type AndroidHelperAppResult = | { kind: 'launched'; output: string }; const ACTION_POLICY = { - input: { mutation: true, timeoutMs: 30_000 }, + // Less the 5 s answer margin, a 40 s helper budget lets a start refused at once still afford its + // one retry (PressSequence.RETRY_WORST_CASE_MS, 35 s); a later refusal is not retried. + input: { mutation: true, timeoutMs: 45_000 }, app: { mutation: true, timeoutMs: 30_000 }, screenshot: { mutation: false, timeoutMs: 30_000 }, focus: { mutation: false, timeoutMs: 2_000 }, } as const; +/** The helper must answer input this long before the host timeout so its typed result arrives. */ +const INPUT_ANSWER_MARGIN_MS = 5_000; + +/** + * The least wait a press is sent with: one injection attempt round trip. On an emulator a whole + * press takes 0.25-0.4 s through the helper or `adb shell input`, so 2 s keeps a wide margin; + * with less, neither path can be expected to answer before the host stops waiting. + */ +const MIN_INPUT_ATTEMPT_MS = 2_000; + /** Reuses the session's automation context without starting instrumentation for sessionless input. */ export function runAndroidAutomationHelper( device: DeviceInfo, @@ -71,17 +84,15 @@ export async function runAndroidAutomationHelper( const deviceKey = getAndroidSnapshotHelperSessionDeviceKey(device); if (!(await getLiveAndroidSnapshotHelperSession(deviceKey))?.commands.has(action)) return undefined; + const timeoutMs = action === 'input' ? admitInputTimeoutMs() : ACTION_POLICY[action].timeoutMs; const prepared = await prepareAndroidAutomationHelper(device); try { const headers = await runAndroidSnapshotHelperSessionTouchCommand({ deviceKey, action, helper: androidAutomationHelperIdentity(prepared.artifact), - payloadBase64: - 'input' in request - ? Buffer.from(JSON.stringify(request.input)).toString('base64') - : undefined, - timeoutMs: ACTION_POLICY[action].timeoutMs, + payloadBase64: encodeHelperPayload(request, timeoutMs), + timeoutMs, }); if (!headers) return undefined; switch (action) { @@ -134,6 +145,46 @@ function decodeHelperIndex(value: string | undefined): number | undefined { return value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined; } +/** + * The host waits for input up to its cap, or until the request's own deadline when that is sooner. + * A request with no room for one attempt is refused before anything is sent. The refusal is thrown + * before the helper call's fallback on purpose: that path stops the shared session, and + * `adb shell input` could not answer in that time either. + */ +function admitInputTimeoutMs(): number { + const capMs = ACTION_POLICY.input.timeoutMs; + const requestDeadlineMs = getRequestDeadlineMs(getDiagnosticsMeta().requestId); + const timeoutMs = + requestDeadlineMs === undefined + ? capMs + : Math.max(0, Math.min(capMs, requestDeadlineMs - Date.now())); + if (timeoutMs < MIN_INPUT_ATTEMPT_MS) { + throw new AppError( + 'COMMAND_FAILED', + 'Android input was not sent: the request has too little time left for one attempt', + { + reason: 'android-input-budget-exhausted', + remainingMs: timeoutMs, + minimumMs: MIN_INPUT_ATTEMPT_MS, + dispatched: 'no', + }, + ); + } + return timeoutMs; +} + +function encodeHelperPayload( + request: AndroidAutomationRequest, + timeoutMs: number, +): string | undefined { + if (!('input' in request)) return undefined; + const payload = + request.action === 'input' + ? { ...request.input, budgetMs: Math.max(0, timeoutMs - INPUT_ANSWER_MARGIN_MS) } + : request.input; + return Buffer.from(JSON.stringify(payload)).toString('base64'); +} + function decodeHelperPayload( headers: Record, field: string, diff --git a/test/repo-guards/android-helper-input-dispatch.test.ts b/test/repo-guards/android-helper-input-dispatch.test.ts new file mode 100644 index 0000000000..7327cacbc2 --- /dev/null +++ b/test/repo-guards/android-helper-input-dispatch.test.ts @@ -0,0 +1,35 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { test } from 'vitest'; + +const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'); +const helperSourceDir = path.join(repoRoot, 'android/snapshot-helper/src/main/java'); +const dispatcherFile = path.join( + 'com/callstack/agentdevice/snapshothelper', + 'UiAutomationInputDispatcher.java', +); + +// The public two-argument UiAutomation overload waits up to five seconds for global window +// animations before a gesture's first event and after its last one (#4590, #1356). +test('Android helper input reaches the framework only through the dispatcher without the animation wait', () => { + const sources = fs + .readdirSync(helperSourceDir, { recursive: true, encoding: 'utf8' }) + .filter((name) => name.endsWith('.java')); + assert.ok(sources.includes(dispatcherFile), 'the input dispatcher must exist'); + const directInjectors = sources.filter( + (name) => + name !== dispatcherFile && + /\.injectInputEvent\(/.test( + fs + .readFileSync(path.join(helperSourceDir, name), 'utf8') + .replaceAll(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, ''), + ), + ); + assert.deepEqual(directInjectors, []); + assert.match( + fs.readFileSync(path.join(helperSourceDir, dispatcherFile), 'utf8'), + /method\.invoke\(automation, event, waitForDispatch, false\)/, + ); +});