---
name: qa
description: |
  Use after making changes to visually validate the app in the iOS Simulator.
  Builds, installs, launches the app, then uses screenshots and accessibility
  descriptions to verify the change looks and behaves correctly.
user-invocable: true
---

# QA — Visual Validation via iOS Simulator

Validate changes by building, installing, and inspecting the app in the
iOS Simulator using the `ios-simulator` MCP server.

## Prerequisites

The iOS Simulator must be booted before starting. Use
`mcp__ios-simulator__get_booted_sim_id` to confirm. If no simulator is
booted, use `mcp__ios-simulator__open_simulator` first.

## Workflow

1. **Regenerate the Tuist project** so the workspace reflects any file
   changes:

       tuist generate --no-open

2. **Build for simulator** using the workspace (required for
   dependency resolution):

       xcodebuild build -workspace Ruckus.xcworkspace -scheme Ruckus \
         -destination 'platform=iOS Simulator,name=iPhone 17 Pro'

   This uses Xcode's default DerivedData location. If the build fails,
   fix the errors before continuing.

3. **Find the built `.app` bundle.** After a successful build, locate
   it in Xcode's DerivedData:

       find ~/Library/Developer/Xcode/DerivedData \
         -name "Ruckus.app" \
         -path "*/Debug-iphonesimulator/*" \
         -maxdepth 5 \
         -newer Ruckus.xcworkspace \
         2>/dev/null | head -1

   Use the most recently modified match.

4. **Install the app.**

   Use `mcp__ios-simulator__install_app` with the `.app` path found
   in the previous step.

5. **Launch the app.**

   Use `mcp__ios-simulator__launch_app` with `bundle_id: io.defn.Ruckus`
   and `terminate_running: true` to ensure a fresh start.

6. **Take a screenshot and describe the UI.**

   - Use `mcp__ios-simulator__screenshot` to capture the current state.
   - Use `mcp__ios-simulator__ui_describe_all` to get the accessibility
     tree for the visible screen.
   - Read the screenshot to visually inspect the result.

7. **Navigate to the relevant screen.** If the change is not on the
   initial screen, use taps, swipes, and text input to navigate there:
   - `mcp__ios-simulator__ui_tap` — tap coordinates
   - `mcp__ios-simulator__ui_swipe` — scroll or swipe
   - `mcp__ios-simulator__ui_type` — enter text

   After each navigation action, take another screenshot and describe
   the UI to confirm you reached the right screen.

8. **Validate the change.** Compare what you see against the expected
   behavior:
   - Does the UI reflect the change?
   - Are labels, colors, and layout correct?
   - Is the accessibility tree reasonable?

   Report your findings — what looks correct and what (if anything)
   looks wrong.

9. **If something is wrong,** describe the issue clearly. Do NOT
   attempt to fix it automatically unless the caller asks you to.

## Tips

- When you don't know the coordinates of a UI element, use
  `mcp__ios-simulator__ui_describe_all` to find it in the accessibility
  tree — elements include their frame coordinates.
- Take screenshots liberally. They are the ground truth for visual QA.
- If the app crashes on launch, check the build logs and simulator
  system log for clues.