refactor: migrate UI automation tools to event-based handler contract

Author: cameroncooke

src/mcp/tools/ui-automation/__tests__/button.test.ts

@@ -1,13 +1,43 @@
-/**
- * Tests for snapshot_ui tool plugin
- */
-
 import { describe, it, expect } from 'vitest';
 import * as z from 'zod';
 import { createMockExecutor, createNoopExecutor } from '../../../../test-utils/mock-executors.ts';
 import type { CommandExecutor } from '../../../../utils/execution/index.ts';
 import { schema, handler, snapshot_uiLogic } from '../snapshot_ui.ts';
 import { AXE_NOT_AVAILABLE_MESSAGE } from '../../../../utils/axe-helpers.ts';
+import { allText, createMockToolHandlerContext } from '../../../../test-utils/test-helpers.ts';
+
+const runLogic = async (logic: () => Promise<unknown>) => {
+  const { result, run } = createMockToolHandlerContext();
+  const response = await run(logic);
+
+  if (
+    response &&
+    typeof response === 'object' &&
+    'content' in (response as Record<string, unknown>)
+  ) {
+    return response as {
+      content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+      isError?: boolean;
+      nextStepParams?: unknown;
+    };
+  }
+
+  const text = result.text();
+  const textContent = text.length > 0 ? [{ type: 'text' as const, text }] : [];
+  const imageContent = result.attachments.map((attachment) => ({
+    type: 'image' as const,
+    data: attachment.data,
+    mimeType: attachment.mimeType,
+  }));
+
+  return {
+    content: [...textContent, ...imageContent],
+    isError: result.isError() ? true : undefined,
+    nextStepParams: result.nextStepParams,
+    attachments: result.attachments,
+    text,
+  };
+};
 
 describe('Snapshot UI Plugin', () => {
   describe('Export Field Validation (Literal)', () => {
@@ -33,8 +63,8 @@ describe('Snapshot UI Plugin', () => {
       const result = await handler({});
 
       expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('Missing required session defaults');
-      expect(result.content[0].text).toContain('simulatorId is required');
+      expect(allText(result)).toContain('Missing required session defaults');
+      expect(allText(result)).toContain('simulatorId is required');
     });
 
     it('should handle invalid simulatorId format via schema validation', async () => {
@@ -44,8 +74,8 @@ describe('Snapshot UI Plugin', () => {
       });
 
       expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('Parameter validation failed');
-      expect(result.content[0].text).toContain('Invalid Simulator UUID format');
+      expect(allText(result)).toContain('Parameter validation failed');
+      expect(allText(result)).toContain('Invalid Simulator UUID format');
     });
 
     it('should return success for valid snapshot_ui execution', async () => {
@@ -63,10 +93,6 @@ describe('Snapshot UI Plugin', () => {
       const mockAxeHelpers = {
         getAxePath: () => '/usr/local/bin/axe',
         getBundledAxeEnvironment: () => ({}),
-        createAxeNotAvailableResponse: () => ({
-          content: [{ type: 'text' as const, text: 'axe not available' }],
-          isError: true,
-        }),
       };
 
       // Wrap executor to track calls
@@ -76,12 +102,14 @@ describe('Snapshot UI Plugin', () => {
         return mockExecutor(...args);
       };
 
-      const result = await snapshot_uiLogic(
-        {
-          simulatorId: '12345678-1234-4234-8234-123456789012',
-        },
-        trackingExecutor,
-        mockAxeHelpers,
+      const result = await runLogic(() =>
+        snapshot_uiLogic(
+          {
+            simulatorId: '12345678-1234-4234-8234-123456789012',
+          },
+          trackingExecutor,
+          mockAxeHelpers,
+        ),
       );
 
       expect(executorCalls[0]).toEqual([
@@ -91,22 +119,17 @@ describe('Snapshot UI Plugin', () => {
         { env: {} },
       ]);
 
-      expect(result).toEqual({
-        content: [
-          {
-            type: 'text' as const,
-            text: 'Accessibility hierarchy retrieved successfully:\n```json\n{"elements": [{"type": "Button", "frame": {"x": 100, "y": 200, "width": 50, "height": 30}}]}\n```',
-          },
-          {
-            type: 'text' as const,
-            text: 'Tips:\n- Use frame coordinates for tap/swipe (center: x+width/2, y+height/2)\n- If a debugger is attached, ensure the app is running (not stopped on breakpoints)\n- Screenshots are for visual verification only',
-          },
-        ],
-        nextStepParams: {
-          snapshot_ui: { simulatorId: '12345678-1234-4234-8234-123456789012' },
-          tap: { simulatorId: '12345678-1234-4234-8234-123456789012', x: 0, y: 0 },
-          screenshot: { simulatorId: '12345678-1234-4234-8234-123456789012' },
-        },
+      expect(result.isError).toBeFalsy();
+      const text = allText(result);
+      expect(text).toContain('Accessibility hierarchy retrieved successfully.');
+      expect(text).toContain(
+        '{"elements": [{"type": "Button", "frame": {"x": 100, "y": 200, "width": 50, "height": 30}}]}',
+      );
+      expect(text).toContain('Use frame coordinates for tap/swipe');
+      expect(result.nextStepParams).toEqual({
+        snapshot_ui: { simulatorId: '12345678-1234-4234-8234-123456789012' },
+        tap: { simulatorId: '12345678-1234-4234-8234-123456789012', x: 0, y: 0 },
+        screenshot: { simulatorId: '12345678-1234-4234-8234-123456789012' },
       });
     });
 
@@ -115,34 +138,20 @@ describe('Snapshot UI Plugin', () => {
       const mockAxeHelpers = {
         getAxePath: () => null,
         getBundledAxeEnvironment: () => ({}),
-        createAxeNotAvailableResponse: () => ({
-          content: [
-            {
-              type: 'text' as const,
-              text: AXE_NOT_AVAILABLE_MESSAGE,
-            },
-          ],
-          isError: true,
-        }),
       };
 
-      const result = await snapshot_uiLogic(
-        {
-          simulatorId: '12345678-1234-4234-8234-123456789012',
-        },
-        createNoopExecutor(),
-        mockAxeHelpers,
-      );
-
-      expect(result).toEqual({
-        content: [
+      const result = await runLogic(() =>
+        snapshot_uiLogic(
           {
-            type: 'text' as const,
-            text: AXE_NOT_AVAILABLE_MESSAGE,
+            simulatorId: '12345678-1234-4234-8234-123456789012',
           },
-        ],
-        isError: true,
-      });
+          createNoopExecutor(),
+          mockAxeHelpers,
+        ),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(allText(result)).toContain(AXE_NOT_AVAILABLE_MESSAGE);
     });
 
     it('should handle AxeError from failed command execution', async () => {
@@ -157,29 +166,22 @@ describe('Snapshot UI Plugin', () => {
       const mockAxeHelpers = {
         getAxePath: () => '/usr/local/bin/axe',
         getBundledAxeEnvironment: () => ({}),
-        createAxeNotAvailableResponse: () => ({
-          content: [{ type: 'text' as const, text: 'axe not available' }],
-          isError: true,
-        }),
       };
 
-      const result = await snapshot_uiLogic(
-        {
-          simulatorId: '12345678-1234-4234-8234-123456789012',
-        },
-        mockExecutor,
-        mockAxeHelpers,
-      );
-
-      expect(result).toEqual({
-        content: [
+      const result = await runLogic(() =>
+        snapshot_uiLogic(
           {
-            type: 'text' as const,
-            text: "Error: Failed to get accessibility hierarchy: axe command 'describe-ui' failed.\nDetails: axe command failed",
+            simulatorId: '12345678-1234-4234-8234-123456789012',
           },
-        ],
-        isError: true,
-      });
+          mockExecutor,
+          mockAxeHelpers,
+        ),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(allText(result)).toContain(
+        "Failed to get accessibility hierarchy: axe command 'describe-ui' failed.",
+      );
     });
 
     it('should handle SystemError from command execution', async () => {
@@ -189,31 +191,19 @@ describe('Snapshot UI Plugin', () => {
       const mockAxeHelpers = {
         getAxePath: () => '/usr/local/bin/axe',
         getBundledAxeEnvironment: () => ({}),
-        createAxeNotAvailableResponse: () => ({
-          content: [{ type: 'text' as const, text: 'axe not available' }],
-          isError: true,
-        }),
       };
 
-      const result = await snapshot_uiLogic(
-        {
-          simulatorId: '12345678-1234-4234-8234-123456789012',
-        },
-        mockExecutor,
-        mockAxeHelpers,
-      );
-
-      expect(result).toEqual({
-        content: [
+      const result = await runLogic(() =>
+        snapshot_uiLogic(
           {
-            type: 'text' as const,
-            text: expect.stringContaining(
-              'Error: System error executing axe: Failed to execute axe command: ENOENT: no such file or directory',
-            ),
+            simulatorId: '12345678-1234-4234-8234-123456789012',
           },
-        ],
-        isError: true,
-      });
+          mockExecutor,
+          mockAxeHelpers,
+        ),
+      );
+
+      expect(result.isError).toBe(true);
     });
 
     it('should handle unexpected Error objects', async () => {
@@ -223,31 +213,19 @@ describe('Snapshot UI Plugin', () => {
       const mockAxeHelpers = {
         getAxePath: () => '/usr/local/bin/axe',
         getBundledAxeEnvironment: () => ({}),
-        createAxeNotAvailableResponse: () => ({
-          content: [{ type: 'text' as const, text: 'axe not available' }],
-          isError: true,
-        }),
       };
 
-      const result = await snapshot_uiLogic(
-        {
-          simulatorId: '12345678-1234-4234-8234-123456789012',
-        },
-        mockExecutor,
-        mockAxeHelpers,
-      );
-
-      expect(result).toEqual({
-        content: [
+      const result = await runLogic(() =>
+        snapshot_uiLogic(
           {
-            type: 'text' as const,
-            text: expect.stringContaining(
-              'Error: System error executing axe: Failed to execute axe command: Unexpected error',
-            ),
+            simulatorId: '12345678-1234-4234-8234-123456789012',
           },
-        ],
-        isError: true,
-      });
+          mockExecutor,
+          mockAxeHelpers,
+        ),
+      );
+
+      expect(result.isError).toBe(true);
     });
 
     it('should handle unexpected string errors', async () => {
@@ -257,29 +235,22 @@ describe('Snapshot UI Plugin', () => {
       const mockAxeHelpers = {
         getAxePath: () => '/usr/local/bin/axe',
         getBundledAxeEnvironment: () => ({}),
-        createAxeNotAvailableResponse: () => ({
-          content: [{ type: 'text' as const, text: 'axe not available' }],
-          isError: true,
-        }),
       };
 
-      const result = await snapshot_uiLogic(
-        {
-          simulatorId: '12345678-1234-4234-8234-123456789012',
-        },
-        mockExecutor,
-        mockAxeHelpers,
-      );
-
-      expect(result).toEqual({
-        content: [
+      const result = await runLogic(() =>
+        snapshot_uiLogic(
           {
-            type: 'text' as const,
-            text: 'Error: System error executing axe: Failed to execute axe command: String error',
+            simulatorId: '12345678-1234-4234-8234-123456789012',
           },
-        ],
-        isError: true,
-      });
+          mockExecutor,
+          mockAxeHelpers,
+        ),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(allText(result)).toContain(
+        'System error executing axe: Failed to execute axe command: String error',
+      );
     });
   });
 });