test(android-e2e): make an alert-dismiss failure self-explaining

The Android smoke scenario asserted the post-alert canary text with a
screen-wide `wait text`, whose timeout report is a top-6-label surface
dump that may not include the element in question at all. Assert the
canary through the specific automation-alert-result element instead, so
a failure states its actual current value directly.

Also record the tapped alert button's coordinates alongside its label
(already recorded) in the Android alert-handled result, and capture a
screenshot artifact when an e2e `wait` step times out, so a flake has
more to go on than the surface dump.

Author: thymikee

packages/platform-android/src/__tests__/alert.test.ts

@@ -0,0 +1,114 @@
+import { test, vi } from 'vitest';
+import assert from 'node:assert/strict';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
+
+const runAndroidAdb = vi.fn(async (_device: DeviceInfo, _args: string[]) => ({
+  exitCode: 0,
+  stdout: '',
+  stderr: '',
+}));
+vi.mock('../adb.ts', () => ({ runAndroidAdb }));
+
+const { handleAndroidAlert } = await import('../alert.ts');
+
+const device: DeviceInfo = {
+  platform: 'android',
+  id: 'emulator-5554',
+  name: 'Pixel',
+  kind: 'emulator',
+  booted: true,
+};
+
+test('dismissing a button alert records the tapped button and its coordinates', async () => {
+  runAndroidAdb.mockClear();
+  const result = await handleAndroidAlert(device, 'dismiss', {
+    captureNodes: async () => [
+      node(0, 'android.app.AlertDialog'),
+      text(1, 'Automation confirmation', 'android:id/alertTitle'),
+      button(2, 'Cancel', 'android:id/button2', { x: 210, y: 612 }),
+    ],
+  });
+
+  assert.deepEqual(result, {
+    kind: 'alertHandled',
+    platform: 'android',
+    action: 'dismiss',
+    handled: true,
+    alert: {
+      title: 'Automation confirmation',
+      buttons: ['Cancel'],
+      platform: 'android',
+      source: 'native-dialog',
+      packageName: 'com.example.app',
+    },
+    button: 'Cancel',
+    coordinates: { x: 274, y: 638 },
+    message: 'Alert dismissed',
+  });
+  assert.deepEqual(runAndroidAdb.mock.calls[0]?.[1], ['shell', 'input', 'tap', '274', '638']);
+});
+
+test('accepting a button alert records the tapped button and its coordinates', async () => {
+  runAndroidAdb.mockClear();
+  const result = await handleAndroidAlert(device, 'accept', {
+    captureNodes: async () => [
+      node(0, 'android.app.AlertDialog'),
+      text(1, 'Automation confirmation', 'android:id/alertTitle'),
+      button(2, 'OK', 'android:id/button1', { x: 52, y: 612 }),
+    ],
+  });
+
+  assert.equal(result.kind, 'alertHandled');
+  assert.deepEqual('coordinates' in result ? result.coordinates : undefined, { x: 116, y: 638 });
+});
+
+test('a fallback Back dismissal (no matching button) carries no coordinates', async () => {
+  runAndroidAdb.mockClear();
+  const result = await handleAndroidAlert(device, 'dismiss', {
+    captureNodes: async () => [
+      node(0, 'android.app.AlertDialog'),
+      text(1, 'Automation confirmation', 'android:id/alertTitle'),
+    ],
+  });
+
+  assert.equal(result.kind, 'alertHandled');
+  assert.ok(result.kind === 'alertHandled' && !('coordinates' in result));
+  assert.equal(result.kind === 'alertHandled' ? result.button : undefined, 'Back');
+  assert.deepEqual(runAndroidAdb.mock.calls[0]?.[1], ['shell', 'input', 'keyevent', '4']);
+});
+
+function node(
+  index: number,
+  type: string,
+  overrides: Partial<RawSnapshotNode> = {},
+): RawSnapshotNode {
+  return {
+    index,
+    parentIndex: index === 0 ? undefined : 0,
+    type,
+    bundleId: 'com.example.app',
+    ...overrides,
+  };
+}
+
+function text(index: number, label: string, identifier: string, parentIndex = 0): RawSnapshotNode {
+  return node(index, 'android.widget.TextView', { label, identifier, parentIndex });
+}
+
+function button(
+  index: number,
+  label: string,
+  identifier: string,
+  origin: { x: number; y: number },
+  parentIndex = 0,
+): RawSnapshotNode {
+  return node(index, 'android.widget.Button', {
+    label,
+    identifier,
+    bundleId: 'com.example.app',
+    parentIndex,
+    rect: { ...origin, width: 128, height: 52 },
+    hittable: true,
+  });
+}

packages/platform-android/src/alert.ts

@@ -47,6 +47,7 @@ export type AndroidAlertResult =
       handled: true;
       alert: AndroidAlertInfo;
       button: string;
+      coordinates?: { x: number; y: number };
       message?: string;
     };
 
@@ -102,7 +103,10 @@ async function handleAndroidAlertAction(
   const button = chooseAndroidAlertButton(candidate.buttons, action);
   if (button) {
     await pressAndroid(device, button.x, button.y);
-    return buildAndroidAlertHandledResponse(action, candidate.alert, button.label);
+    return buildAndroidAlertHandledResponse(action, candidate.alert, button.label, {
+      x: button.x,
+      y: button.y,
+    });
   }
 
   if (action === 'dismiss') {
@@ -153,6 +157,7 @@ function buildAndroidAlertHandledResponse(
   action: 'accept' | 'dismiss',
   alert: AndroidAlertInfo,
   button: string,
+  coordinates?: { x: number; y: number },
 ): AndroidAlertResult {
   return {
     kind: 'alertHandled',
@@ -161,6 +166,7 @@ function buildAndroidAlertHandledResponse(
     handled: true,
     alert,
     button,
+    ...(coordinates ? { coordinates } : {}),
     ...successText(`Alert ${action}ed`),
   };
 }

test/integration/android-emulator-e2e/live-automation-scenario.ts

@@ -164,10 +164,10 @@ export async function assertAutomationSystem(context: LiveContext): Promise<void
   const alert = await runStep(context, 'inspect Android native alert', ['alert', 'get']);
   assertJsonContains(alert, 'Automation confirmation', 'alert get should expose fixture dialog');
   await runStep(context, 'dismiss Android native alert', ['alert', 'dismiss']);
-  await assertWaitText(context, 'Alert result: cancelled');
+  await assertElementText(context, 'id="automation-alert-result"', 'Alert result: cancelled');
   await runStep(context, 'reopen Android native alert', ['click', 'id="automation-open-alert"']);
   await runStep(context, 'accept Android native alert', ['alert', 'accept']);
-  await assertWaitText(context, 'Alert result: accepted');
+  await assertElementText(context, 'id="automation-alert-result"', 'Alert result: accepted');
   verifyCommand(context, C.alert, 'alert wait/get/dismiss/accept produce fixture-visible results');
 
   await assertHomeAndRecentsRestoration(context);

test/integration/live-device-e2e/runtime.ts

@@ -140,7 +140,7 @@ export function createLiveDeviceHarness<
       status: result.status,
       step,
     });
-    assertStepOutcome(context, step, fullArgs, result, failedAsExpected, stepOptions);
+    await assertStepOutcome(context, step, fullArgs, result, failedAsExpected, stepOptions);
     updateSessionState(context, args[0], result.status);
     return result;
   }
@@ -158,21 +158,24 @@ export function createLiveDeviceHarness<
     writeStepHistory(context);
   }
 
-  function assertStepOutcome(
+  async function assertStepOutcome(
     context: Context,
     step: string,
     fullArgs: string[],
     result: CliJsonResult,
     failedAsExpected: boolean,
     stepOptions: RunStepOptions,
-  ): void {
+  ): Promise<void> {
     const unexpectedFailure =
       result.status !== 0 && !failedAsExpected && stepOptions.allowFailure !== true;
     if (unexpectedFailure) {
+      const screenshotPath =
+        fullArgs[0] === 'wait' ? await captureWaitTimeoutScreenshot(context) : undefined;
       const message = [
         formatResultDebug(step, fullArgs, result),
         `scenario: ${context.currentScenario}`,
         `artifacts: ${context.artifactDir}`,
+        `screenshot: ${screenshotPath ?? '(capture failed or not applicable)'}`,
       ].join('\n');
       fs.writeFileSync(path.join(context.artifactDir, 'failed-step.txt'), message);
       assert.fail(message);
@@ -182,6 +185,27 @@ export function createLiveDeviceHarness<
     }
   }
 
+  /**
+   * Best-effort evidence for a `wait` timeout: the daemon's own surface dump caps at a handful of
+   * labels, so a screenshot is the only artifact that shows the whole screen the wait gave up on.
+   * A failed capture must not mask the original wait failure, so this never throws.
+   */
+  async function captureWaitTimeoutScreenshot(context: Context): Promise<string | undefined> {
+    const screenshotPath = path.join(
+      context.artifactDir,
+      `wait-timeout-${context.stepHistory.length}.png`,
+    );
+    try {
+      const capture = await (options.runCli ?? runBuiltCliJson)(
+        options.commonFlags(context, ['screenshot', screenshotPath]),
+        context.env,
+      );
+      return capture.status === 0 ? screenshotPath : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   function updateSessionState(context: Context, command: string | undefined, status: number): void {
     if (status !== 0) return;
     if (command === 'open') context.sessionOpen = true;