Test and Verify
2 min read
Test and Verify
Time required: 15–45 minutes per phase
What this does:Comprehensive testing and visual verification of each build phase.
When to use: After completing each build phase (after Build).
What you will have after this: A fully tested, security-reviewed, visually verified phase with 80%+ coverage and all ACs confirmed.
Step 1: Run the automated test suite
Open Claude Code in your project folder and ask:
Run the full test suite with coverage reporting. Show me: 1. Total tests run, passed, failed, skipped2. Code coverage percentage (line, branch, function)3. Any uncovered files or functions4. Full output of any failing testsWhat to do with the results:
All tests pass and coverage is 80%+: Continue to Step 2
Tests fail: Fix them before continuing. Tell Claude to fix each failure.
Coverage below 80%: Tell Claude to write additional tests for uncovered code.
Say this if the tests fall below 80%:
The minimum coverage per metric, file or test scenario needs to be at minimum 80% coverage, please write the remaining tests required to ensure we hit this requirement. This of course should be within reason if the tests need to covered through mock testing they can be delayed till laterStep 2: Run a security review
Ensure the security & infrastructure agent are updated, prompt:
Please ensure that security-auditor.md & infrastructure-auditor.md are updated to be contextually aware of the project in its current stateRun this after creating the audit agents:
Run the following audit agents against the full codebase:
Step 1: Security audit.Run the security auditor agent at /.claude/agents/security-auditor.mdagainst all code in /src/.Show me the full findings ranked by severity.
Step 2: Infrastructure audit.Run the infrastructure auditor agent at /.claude/agents/infrastructure-auditor.mdagainst the full project.Show me the full findings ranked by severity.
Step 3: Combined report.Combine both audit results into a single report at /docs/audit-report.md with:- Date of audit- Summary: total findings by severity across both audits- Security findings (grouped by severity)- Infrastructure findings (grouped by severity)- Each finding with its recommended fix
Step 4: Fix plan.For all findings rated Critical or High:- Group related fixes together into logical batches- Show me the fix plan and wait for approval before proceeding
For Medium and Low findings:- Create a single Beads issue using `bd create` titled "Address Medium/Low audit findings" listing all remaining items -- these can be tackled later
Step 5: Implement approved fixes.After I approve the fix plan:- Create a branch: fix/post-build-audit- Implement all approved fixes- Run the full test suite after each fix batch- Re-run both audit agents to verify fixes resolved the issues- Update /docs/audit-report.md with resolution status- Commit and push
Step 6: Close out.- Mark any Beads issues as complete- Show me the before/after summary: how many findings existed vs how many remainFix any issues before continuing.
Step 3: Run targeted review agents
After the security and infrastructure audits, use the pr-review-toolkit agents to check specific risk areas:
Tell Claude:
Check if the tests cover all edge cases for this phase. Then review the error handling -- look for silent failures.The pr-test-analyzer and silent-failure-hunter agents will activate automatically based on these prompts. Fix any critical findings before continuing.
Step 4: Setup Playwright MCP (for UI review) -- ONLY NEEDS TO BE DONE ONCE
Run this once before your first UI review.
Install and configure Playwright MCP for browser-based UI testing.1. Install the Playwright MCP server if not already installed2. Add the Playwright MCP configuration to /.claude/settings.json3. Verify the connection works by navigating to a test URL and taking a screenshot4. Confirm you can: - Navigate to URLs - Take screenshots at specific viewport sizes - Read browser console output - Interact with page elements (click, type, hover) - Capture network requestsStep 5: Create UI Review Command -- ONLY NEEDS TO BE DONE ONCE
Run this once to create the reusable slash command.
Create the following file at /.claude/commands/ui-review-fix.md:
---description: Autonomous UI/UX review and fix cycle using Playwright MCPallowed-tools: Write, Read, Bash, mcp__playwright*---You are running an autonomous UI/UX review and fix cycle. Work through every page systematically. Do NOT ask me questions -- make decisions yourself and keep going until every page is reviewed and fixed.
### Setup
1. Read /docs/design-system/MASTER.md for the design system rules2. Read /docs/design-system/pages/ for page specs3. Read /.claude/skills/ui-ux-pro-max/ skill files for anti-patterns and best practices4. Confirm the dev server is running -- if not, start it5. Use Playwright MCP for all browser interactions
### For EACH page in the application:
**Step 1: Screenshot and Audit**Using Playwright MCP:
- Navigate to the page- Take a screenshot at desktop (1440px), tablet (768px), and mobile (375px)- Capture any browser console errors or warnings- Capture any failed network requests
**Step 2: Visual Review**Review each screenshot against the design system and the page spec for this page.
Check:- [ ] Colour consistency (matches design system palette)- [ ] Typography (correct font pairing, sizes, weights, line heights)- [ ] Spacing/padding consistency (matches design system spacing scale)- [ ] Hover states present on all clickable elements- [ ] cursor-pointer on all interactive elements- [ ] No emojis used as icons (should be SVG: Lucide/Heroicons or per design system)- [ ] Transitions on hover/focus (150-300ms)- [ ] Contrast ratio 4.5:1 minimum for text- [ ] Focus states visible for keyboard navigation- [ ] Responsive layout correct at all three breakpoints- [ ] No orphaned text or awkward line breaks- [ ] Consistent border radius usage- [ ] Loading states present where data is fetched- [ ] Empty states present where lists could be empty- [ ] Error states display correctly- [ ] Components match what the page spec says should be used- [ ] Layout matches the page spec structure
Accessibility:- [ ] All images have meaningful alt text- [ ] All form inputs have associated labels (label element or aria-label)- [ ] Heading hierarchy is correct (h1 > h2 > h3, no skipped levels)- [ ] ARIA roles and attributes used correctly where needed- [ ] Interactive elements are reachable and operable via keyboard- [ ] Focus order follows a logical reading sequence- [ ] No information conveyed by colour alone
**Step 3: Console and Functionality Check**Using Playwright MCP, interact with the page:
- [ ] No console errors- [ ] No console warnings (except known/acceptable ones)- [ ] No failed network requests- [ ] All links navigate correctly- [ ] Forms submit and validate correctly- [ ] Interactive elements respond to clicks- [ ] Test keyboard navigation through the page (Tab, Enter, Escape)
**Step 4: Fix Issues**For each issue found:
1. Log: [PAGE] [SEVERITY] [ISSUE]2. Make the code fix3. Wait for hot reload4. Use Playwright MCP to re-screenshot and verify the fix5. If the fix introduced new issues, fix those too6. If a fix requires changing shared components, use Playwright MCP to check ALL pages that use that component still work
**Step 5: Re-verify**Using Playwright MCP:
- Take fresh screenshots at all 3 breakpoints- Confirm all previous issues are resolved- Confirm no new issues introduced- Check console is still clean
### Severity Classification- **CRITICAL**: Broken layout, console errors, non-functional features- **HIGH**: Wrong colours, missing hover states, accessibility failures- **MEDIUM**: Spacing inconsistencies, minor responsive issues- **LOW**: Polish items, micro-interaction improvements
### Fix Rules- Fix CRITICAL and HIGH issues always- Fix MEDIUM issues unless the fix risks breaking something else- Log LOW issues but only fix if trivial- If you break something, revert and try a different approach- After completing all pages, do one final pass on the first page
### OutputWhen complete, create /docs/ui-review-report.md with:- Date of review- Summary of pages reviewed- Total issues found by severity- All fixes applied with before/after description- Any remaining LOW issues not addressed- Commit all fixes with message: "fix: UI/UX review -- [N] issues resolved"Step 6: Run UI Review -- CAN BE RUN WHENEVER NEEDED
Run this when you want to execute the review.
Start the dev server if it's not already running.Then run /ui-review-fixStep 7: Cross-check acceptance criteria
Read /docs/prd/acceptance-checklist.md. For every acceptance criterion that this phase is supposed to satisfy:
1. Look at the code to verify it is implemented2. Run a specific test (or manual verification) to confirm it works3. Report the result: - ✅ AC-XXX: [description] — Verified by [test name or manual check]- ❌ AC-XXX: [description] — NOT MET because [reason]- ⚠️ AC-XXX: [description] — Partially met, needs [what is missing]ALL acceptance criteria for this phase must be ✅ before moving on. Fix any ❌ or ⚠️ items.
Step 8: Update documentation
Update the following based on what was built in this phase: 1. /docs/prd/acceptance-checklist.md — check off all verified ACs2. CLAUDE.md — add any new commands, endpoints, or configuration that was created3. Beads — mark the phase issue as complete with `bd complete [issue-id]`Step 9: Final commit and push
Stage all changes. Commit with message: "test: verified phase [N] - all ACs passing, [X]% coverage"Push the branch.Checkpoint
After verification, you should have:
100% of this phase's tests passing
80%+ code coverage
All acceptance criteria for this phase verified ✅
Security review passed
Visual verification passed (for web apps)
Documentation updated
Branch pushed
If this is the final phase, or you want to merge: Open Review and Deploy. If there are more phases to build: Go back to Build and start the next phase.
Sign up to read the full guide
Free access to all 12 workflow guides. No password needed.