| name | qa-macos-ui |
| description | Use when validating Seance or another macOS UI flow from `cargo run`, especially when the test requires AppleScript, `System Events`, Accessibility permissions, screenshots, and diagnostic logs to decide pass or fail. |
macOS UI QA
Use this skill for manual-but-agentic QA of the app from a local dev build.
Scope
- Launch the app from source with
cargo run.
- Drive the UI with AppleScript and
System Events.
- Capture screenshots and diagnostic logs as evidence.
- Decide pass/fail from both visual state and logs.
Workflow
- Create an artifact folder for the run.
- Start the app with
cargo run, usually with diagnostics enabled.
- Verify Accessibility and Automation before depending on
System Events.
- Drive the scenario with AppleScript or shell commands.
- Capture screenshots at the key checkpoints.
- Read the diagnostic log and stderr from the run.
- Mark the scenario
pass only if the UI state matches the expectation and the logs do not show a blocking failure.
Required Evidence
- Command used to launch the app.
- At least one screenshot of the state under test.
- Relevant log excerpt.
- Explicit pass/fail verdict with the observed reason.
Default Commands
- Launch:
cargo run -- --debug-ghostty dashboard
- Log file:
~/Library/Application Support/seance/diagnostic.log
- Screenshot:
screencapture -x /tmp/seance-qa/step.png
Accessibility Rules
- If
System Events returns not allowed assistive access or another -1719 error, treat that as an environment blocker, not an app pass.
- If AppleScript can launch the app but not manipulate windows, continue collecting screenshots and logs and report the blocker precisely.
- Prefer app-native AppleScript first. Use
System Events only for window placement, key presses, clicks, and UI tree inspection.
Pass/Fail Rules
Mark pass only when both are true:
- The screenshot or screenshots show the expected state.
- The logs do not contain a blocking runtime error for the tested path.
Mark fail when any of these are true:
- The expected UI state is absent or visibly wrong.
- The logs show a blocking error such as
AppleScript error, add flow step=..., panic, crash, or a command that never launches.
- The flow only succeeds because the skill skipped the feature under test.
Mark blocked when the environment prevents a valid run:
- Missing Accessibility permission.
- Missing Automation permission.
- Missing external dependency such as Ghostty, Claude, or Codex binaries.
References
