native-qa-macos

Files (6)

• SKILL.md
• macos-automation.md · references/
• test-patterns.md · references/
• flow.md · templates/
• scenarios.md · templates/
• test-case.md · templates/

SKILL.md (first lines)

# macOS Native QA Skill — Complete Runbook

**Platform**: macOS 12 Monterey+
**Automation**: AppleScript + screencapture + Accessibility API
**Invoked by**: Root `SKILL.md` after platform selection (Step 0) and workspace init (Steps 1–3)

This file is self-contained. All scripts are inlined. No external file dependencies.

---

## Shared Principles & Fallback Discipline

Before Step 4, you MUST have read the cross-platform base layer:
- [skills/_shared/principles.md](../_shared/principles.md) — how Claude thinks (screenshot protocol, selector hierarchy, session limits, runtime script evolution)
- [skills/_shared/fingerprint-questions.md](../_shared/fingerprint-questions.md) — the 5 questions answered in root SKILL.md Step 3.5; `qa/platform-fingerprint.md` drives strategy selection
- [skills/_shared/fallback-discipline.md](../_shared/fallback-discipline.md) — **non-negotiable rule**: every strategy, runtime script, and test step must declare a fallback. If primary approach stalls, fall back and continue — never break the flow.

macOS does not yet have a `strategies/` directory — the default exploration flow in this file IS the strategy. If future runs document alternatives, they land under `skills/macos/strategies/` and follow the same selection + decisions-log + fallback pattern as the web skill.

---

## Pre-Step: Load Prior Knowledge

Before doing anything else, check what the root skill extracted from `qa/context/` in Step 3.

```bash
# Check if prior knowledge was extracted
ls qa/knowledgebase/ui-inventory.md 2>/dev/null && echo "EXISTS" || echo "NONE"
ls qa/context/ 2>/dev/null
```

**If `qa/knowledgebase/ui-inventory.md` exists** — read it now. It contains the candidate flow list and known features extracted from any files the user dropped into `qa/context/`. Use this as your starting map for exploration:
- Prioritize flows named in the inventory — discover these first
- If Figma screens were provided, you already know the screen structure — confirm visually
- If a PRD was provided, you know the features and acceptance criteria — test against them

**If `qa/context/` has unread files** (PNGs, `.md`, `.txt` not yet processed) — read them now before launching the app.

**If nothing exists** — cold start. Discover everything visually from scratch.

---

## STOP / PAUSE / SAVE STATE

Follow the root SKILL.md **"STOP / PAUSE / SAVE STATE — Immediate Handler"** exactly. No macOS-specific differences — the root handler applies as-is.

---

## Step 4: App Metadata

### 4.1 Locate the App

```bash
APP_NAME="[user input from Step 2]"

if [ -d "/Applications/${APP_NAME}.app" ]; then
  APP_PATH="/Applications/${APP_NAME}.app"
elif [ -d "$HOME/Applications/${APP_NAME}.app" ]; then
  APP_PATH="$HOME/Applications/${APP_NAME}.app"
else
  APP_PATH=$(mdfind "kMDItemKind == 'Application'" | grep -i "${APP_NAME}" | head -1)
fi
echo "Resolved: $APP_PATH"
```

If not found, ask the user to provide the full path or drag the `.app` bundle.

### 4.2 Read App Metadata

```bash
python3 - <<'PYEOF'
import plistlib, sys
app_path = "/Applications/APPNAME.app"  # replace with resolved path
with open(app_path + "/Contents/Info.plist", "rb") as f:
    p = plistlib.load(f)
print("Name:      ", p.get("CFBundleName", p.get("CFBundleExecutable", "N/A")))
print("BundleID:  ", p.get("CFBundleIdentifier", "N/A"))
print("Version:   ", p.get("CFBundleShortVersionString", "N/A"))
print("Build:     ", p.get("CFBundleVersion", "N/A"))
print("Min macOS: ", p.get("LSMinimumSystemVersion", "N/A"))
PYEOF

sw_vers -productVersion
uname -m
```

### 4.3 Update Config and Write Planning Files

Update `qa/.qa-config.json` with: `app_name`, `app_path`, `app_identifier` (bundle ID), `app_version`, `os_version`, `architecture`.

Write the following planning files using the templates at the end of this file:
- `qa/planning/platforms.md`
- `qa/guardrails/do-and-dont.md`
- `qa/credentials/access.md`
- `qa/scope/contract.md`

→ **Write checkpoint** to `qa/state.md`. Record: app name, bundle ID, version, macOS version, architecture.

---

## Step 5: Launch App and Take First Screenshot

### 5.1 Check Accessibility Permission

```bash
osascript -e 'tell application "System Events" to get name of every process' > /dev/null 2>&1 \
  && echo "✅ Accessibility OK" \
  || echo "❌ BLOCKED"
```

If blocked, **stop immediately** and tell the user:
> "I need Accessibility permission to explore [AppName]'s UI.
>
> Please go to: **System Settings → Privacy & Security → Accessibility**
> Enable access for **Terminal** (or your IDE if running from there).
>
> Then let me know when done — I'll continue from here."

Do not attempt any further automation until the user confirms permission is granted.

From mtkinverse/claude-qa, MIT.

More from mtkinverse/claude-qa