Visual Verification

iOS Sheet Detection Signals:

• Rounded corners at top
• Dimmed/translucent background behind
• Drag indicator at top-center
• Title bar with Cancel (left) and Create/Save (right)

Step 2: Apply HIG Pattern Recognition

Match visual patterns to known iOS/macOS conventions:

Step 3: Scoped Query for Precision

After visual analysis, query ONLY what's needed:

Visual: "I see a sheet with Create button in top-right"
Query: Find button with label "Create" in navigation bar area
Action: Click the specific element found

Step 4: Execute with Context

Click/type based on:

• Element role (button → click, textField → type)
• Expected visual feedback (sheet dismisses, list updates)
• Next state prediction (what should appear after action)

Step 5: Visual Verification Loop

After action, screenshot and verify:

• Did expected change occur? (sheet closed, item added)
• Any error states? (validation message, loading spinner)
• Ready for next action?

Example: "Add Peruna" Workflow

1. Screenshot iPhone → "I see a list view with items"
2. Visual analysis → "There's an 'Item' button to add new items"
3. Click 'Item' → Opens sheet
4. Screenshot → "I see a modal sheet with text field and Create button in top-right nav bar"
5. Type 'Peruna' in text field
6. Visual analysis → "Create button is in top-right corner of sheet's navigation bar"
7. Click 'Create' (top-right nav bar button)
8. Screenshot → "Sheet closed, Peruna appears in list"

The Loop

screenshot → understand context → interact → screenshot → validate → iterate if wrong

When done: listall_quit_macos (quit) or listall_hide_macos (keep running hidden)

Tools

Launch & Screenshot

# macOS
listall_launch_macos(app_name: "ListAll", launch_args: ["UITEST_MODE", "DISABLE_TOOLTIPS"])
listall_screenshot_macos(app_name: "ListAll", context: "feature-name")

# iOS/iPad Simulator
listall_boot_simulator(udid: "...")
listall_launch(udid: "booted", bundle_id: "io.github.chmc.ListAll", launch_args: ["UITEST_MODE", "DISABLE_TOOLTIPS"])
listall_screenshot(udid: "booted", context: "feature-name")

# watchOS Simulator
listall_boot_simulator(udid: "WATCH_UDID")
listall_launch(udid: "booted", bundle_id: "io.github.chmc.ListAll.watchkitapp", launch_args: ["UITEST_MODE"])
listall_screenshot(udid: "booted", context: "feature-name")

Fresh Launch Behavior: When using UITEST_MODE, the app is always terminated/quit before launching to ensure:

• Fresh test data initialization
• Clean state without stale data from previous runs

This happens automatically - you don't need to manually quit first.

Interact

Works on macOS, iOS/iPad, and watchOS simulators. Note: watchOS interactions are slower (~10-30s per action) due to XCUITest bridge overhead.

App Activation (macOS): Interaction tools automatically activate the target app before performing actions. This ensures keyboard/mouse events go to the correct application even if you're working in a different window.

Cleanup

# Quit app (recommended when done)
listall_quit_macos(app_name: "ListAll")

# Or hide app (keep running for next iteration)
listall_hide_macos(app_name: "ListAll")

# To bring hidden app back, just re-launch:
listall_launch_macos(app_name: "ListAll", launch_args: [...])

# Shutdown simulators
listall_shutdown_simulator(udid: "all")

Background launch: Use BACKGROUND in launch_args for less intrusive verification:

listall_launch_macos(app_name: "ListAll", launch_args: ["UITEST_MODE", "BACKGROUND"])

Diagnostics

Run listall_diagnostics() if tools aren't working.

Platforms

Verify on all platforms affected by your change:

Context Naming

The context parameter groups screenshots. Name by what you're verifying: add-item, dark-mode, button-fix.

Screenshots save to .listall-mcp/{timestamp}-{context}/.