ios-qa

Files (3)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/

SKILL.md (first lines)

# iOS Visual QA

## When NOT to use

- Web app QA (use frontend-qa with Playwright MCP)
- Android app QA
- Unit testing Swift/Objective-C code without visual verification
- Backend API testing that doesn't involve the iOS UI

## Overview

Visual QA is a two-phase process:

1. **Run Go tests** — deterministic flows using gowda element selectors, capturing screenshots at each step
2. **Evaluate screenshots** — read each image with Claude Vision, verify against DESIGN.md and Linear story acceptance criteria

## Phase 1: Run Go Tests

### Setup

```bash
export PATH="/opt/devcell/.local/share/mise/installs/go/1.26.0/bin:$PATH"
export WDA_URL="${WDA_URL:-http://host.docker.internal:8100}"
```

### Run tests

Run specific test or all tests. Each test saves numbered screenshots to `tests/results/<timestamp>-<TestName>/`.

```bash
# Run a specific flow
go test ./tests/ -run TestLoginFlow -v

# Run all flows
go test ./tests/ -v

# Run from Docker
WDA_URL=http://host.docker.internal:8100 go test ./tests/ -v
```

### Available tests

Each test maps to a Linear user story:

| Test | Story | What it covers |
|------|-------|----------------|
| `TestLoginFlow` | KIWA-372 | Empty screen → error → fill fields → sign in → Explore |
| `TestLoginEmptyUsername` | KIWA-372 | Validation error on empty submit |
| `TestBrowseGuidesAndTrips` | KIWA-373 | Guides list → scroll → Trips tab → scroll → back |
| `TestViewGuideDetail` | KIWA-374 | Tap guide → detail sheet → scroll → dismiss |
| `TestSignOut` | KIWA-375 | Sign out → back to login |

### Screenshot output

Tests save screenshots to `tests/results/<timestamp>-<TestName>/`:

```
tests/results/2026-07-16T14-30-00-TestLoginFlow/
├── 01-login-empty.png
├── 02-login-error.png
├── 03-login-fill-username.png
├── 04-login-fill-password.png
└── 05-login-signed-in.png
```

## Phase 2: Visual QA Evaluation

After tests complete, evaluate each screenshot.

### Step 1: Find the results directory

```bash
ls -td tests/results/*/ | head -5
```

Pick the most recent run for the test(s) you want to evaluate.

### Step 2: Read each screenshot

Use the **Read tool** to view each PNG file in order. For each screenshot, evaluate against the checklist below.

### Step 3: Load acceptance criteria

Read the Linear story for the test being evaluated (story ID is in the test comment). Use `get_issue` to fetch acceptance criteria. Compare each screenshot against the relevant acceptance criteria.

### Step 4: Evaluate against DESIGN.md

Read `docs/DESIGN.md` for design system reference. For each screenshot check:

**Layout** (DESIGN.md → Spacing & Layout)
- Elements properly aligned, no overlaps or clipping
- Content respects safe areas (top ~59pt, bottom ~34pt on iPhone 16)
- Spacing follows 8pt grid (4, 8, 12, 16, 20, 24, 32)
- Screen-edge padding: 20px
- Between cards: 12px, card internal padding: 16px

**Typography** (DESIGN.md → Typography)
- Large Title: 34px bold for screen titles
- Headline: 17px semibold for card titles
- Body: 17px regular for reading text
- Caption: 12-13px for metadata, tags
- Clear hierarchy, no truncated titles

**Colors** (DESIGN.md → Color System)
- Accent blue (#007AFF) ONLY on interactive elements
- Error text in red, never blue
- Tag/pill backgrounds: accent at 8% opacity
- Sufficient contrast

**Liquid Glass** (DESIGN.md → Liquid Glass)
- Glass on navigation chrome ONLY (toolbars, tab bars)
- NO glass on cards or content areas
- No nested glass

**Cards** (DESIGN.md → Components → Cards)
- Opaque background (NOT glass/material)
- 12px radius, 16px padding
- No nested cards

From DimmKirr/skills, MIT.

More from DimmKirr/skills