uat-testing

What this skill does

# UAT Testing

End-to-end UAT workflow: analyze → generate test cases → set up environment → execute → report.

## Workflow Overview

```
Phase 1: Discovery
  ├─ Read spec/requirements (if provided)
  ├─ Analyze git branch diff against base
  └─ Identify what was built/changed

Phase 2: Environment Setup
  ├─ Determine target: local or production/staging?
  ├─ Local path:
  │   ├─ Check for .env.local → ask user if missing
  │   └─ Start dev server (npm run dev or equivalent)
  ├─ Prod/staging path:
  │   └─ Get application URL, verify reachable
  └─ Ask user for test account credentials (both paths)

Phase 3: Test Case Generation
  ├─ Write uat-test-cases.md (see references/test-case-template.md)
  ├─ Cover: happy path, errors, persistence, auth, responsive
  └─ Present to user for review before execution

Phase 4: Test Execution
  ├─ Start dev server (framework-appropriate command)
  ├─ Authenticate with test account via browser
  ├─ Execute test cases with Playwright MCP tools
  ├─ Take screenshots as evidence
  └─ If a test fails → document the failure, continue testing

Phase 5: Reporting
  ├─ Write uat-results.md (see references/results-template.md)
  ├─ Include: summary table, detailed results, screenshots, fixes
  └─ Present overall PASS/FAIL verdict
```

## Phase 1: Discovery

### Finding the Spec

Look for feature context in this priority order:

1. **User-provided spec**: If user gives a path to a spec, requirements doc, or thread — read it first
2. **Spec directory**: Check `specs/[branch-name]/spec.md` or `specs/[feature-id]/spec.md`
3. **Tasks/todo**: Check `tasks/todo.md` or similar for what was planned
4. **PR description**: If a PR exists, read it via `gh pr view`

### Analyzing Branch Changes

```bash
# What branch are we on?
git branch --show-current

# What changed vs base branch?
git log main..HEAD --oneline
git diff main..HEAD --stat

# What files were modified?
git diff main..HEAD --name-only
```

Read the changed files to understand what was built. Focus on:
- New components or pages (user-facing features)
- Modified API routes or backend logic (behavior changes)
- Schema changes (data model additions)
- Config changes (new env vars needed)

### Output

Summarize findings to the user:
- "This branch adds [feature] based on [spec]"
- "Key changes: [list of modified areas]"
- "I'll generate test cases covering [scope]"

## Phase 2: Environment Setup

### Determine Target Environment

Ask the user (or infer from context) whether this is local or production testing:

> Are we testing **locally** (I'll start the dev server) or against a **deployed environment** (provide the URL)?

| Aspect | Local | Production / Staging |
|--------|-------|----------------------|
| **Server** | Start with `npm run dev` | Already running at provided URL |
| **Env vars** | Need `.env.local` with all keys | N/A — app is already configured |
| **Test data** | May need seeding or setup | Uses existing real/staging data |
| **Auth** | Test account on local auth provider | Test account on prod/staging auth |
| **Base URL** | `http://localhost:3000` (or configured port) | `https://app.example.com` |

### Local Environment Path

#### Check Environment Variables

```bash
# Check if env file exists
ls -la .env.local .env 2>/dev/null
```

**If `.env.local` does not exist**, ask the user:

> I don't see a `.env.local` file. Do you have an environment file or credentials I should use? Common needs:
> - Database connection (e.g., Convex URL/deploy key)
> - Auth provider keys (e.g., Clerk publishable/secret key)
> - API keys (e.g., AI model keys, external service keys)
>
> Please provide the file path or paste the required variables.

#### Start Dev Server

Detect the framework and start the dev server:

| Signal | Framework | Start Command |
|--------|-----------|---------------|
| `next.config.*` | Next.js | `npm run dev` |
| `vite.config.*` | Vite | `npm run dev` |
| `angular.json` | Angular | `ng serve` |
| `nuxt.config.*` | Nuxt | `npm run dev` |
| `package.json` scripts | Generic | Read `dev` script |

If the project needs multiple services (e.g., Next.js + Convex), start all of them.

Verify the server is reachable before proceeding:
```bash
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
```

### Production / Staging Environment Path

No server startup or env file needed. Ask the user for:

> Please provide:
> 1. **Application URL** (e.g., `https://app.example.com`)
> 2. **Any test data considerations** (is there a staging org/business to use?)

Verify the URL is reachable:
```bash
curl -s -o /dev/null -w "%{http_code}" https://app.example.com
```

### Request Test Account (Both Environments)

Always ask before attempting to authenticate:

> For UAT testing I need a test account to log in. Most auth systems require email verification, so I can't create a new account.
>
> Please provide:
> 1. **Login URL** (if not the default `/sign-in`)
> 2. **Email/username** for the test account
> 3. **Password**
> 4. **Any 2FA/MFA steps** I should be aware of
> 5. **Which business/org/team** to select after login (if applicable)

## Phase 3: Test Case Generation

Read `references/test-case-template.md` for the full template format.

### Generation Rules

1. **Map spec to test cases**: Each user story or requirement gets at least one test case
2. **Prioritize**: Critical (P1) = core happy path; High (P2) = error handling; Medium (P3) = edge cases
3. **Be specific**: Each step should be a concrete action ("Type 'hello' in the input field"), not vague ("Test the input")
4. **Include expected data**: Use actual values from the seeded test data or spec examples
5. **Cover persistence**: Always include a "reload page and verify" test case for stateful features
6. **Cover auth boundaries**: If the feature has role-based access, test with different roles

### Writing the File

Write `uat-test-cases.md` to the spec directory (e.g., `specs/[feature-id]/uat-test-cases.md`) or to the project root if no spec directory exists.

**Present the test cases to the user for review before executing.** Ask:

> I've generated [N] test cases in [file path]. Review them and let me know:
> - Any test cases to add or remove?
> - Any priority adjustments?
> - Ready to proceed with execution?

## Phase 4: Test Execution

### Playwright MCP Setup

Load the Playwright tools via ToolSearch before starting:
```
ToolSearch: "playwright browser"
```

Key tools: `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill_form`, `browser_type`, `browser_press_key`, `browser_take_screenshot`, `browser_wait_for`, `browser_console_messages`, `browser_evaluate`.

See `references/agent-guide.md` for the full tool reference and auth handling patterns.

### Execution Pattern

For each test case:
1. Navigate to the target page
2. Wait for page load (`browser_wait_for` or snapshot check)
3. Perform the test actions (click, type, submit)
4. Wait for the expected result
5. Verify via `browser_snapshot` (check accessibility tree for expected text/elements)
6. Take `browser_take_screenshot` for evidence
7. Check `browser_console_messages` for JS errors
8. Record PASS or FAIL with details

### Failure Handling

When a test fails:
- **Document exactly what happened** (expected vs actual)
- **Take a screenshot** of the failure state
- **Check console for errors** (`browser_console_messages`)
- **Continue testing** other cases — do not stop on first failure
- **If the fix is obvious and small** (< 5 lines), ask user if you should fix it. If yes, fix, re-verify, and document the fix in the results report

### Screenshot Naming Convention

Save screenshots to the project root with descriptive names:
```
uat-tc001-invoice-card.png
uat-tc002-cashflow-dashboard.png
uat-tc003-fail-missing-button.png
```

## Phase 5: Reporting

Read `references/results-template.md` for the full report format.

### Writing the Report

Write `uat-results.md` alongside the test cases file.

Include:
1. **Summary table**: P