learningcircuit--local-deep-research/tests/ui_tests/playwright/README.md

# Playwright Mobile UI Tests

Modern mobile UI testing with visual regression for Local Deep Research.

## Why Playwright Instead of Puppeteer?

Based on [industry research](https://www.browserstack.com/guide/playwright-vs-puppeteer), Playwright is the superior choice for mobile testing:

| Feature | Puppeteer | Playwright |
|---------|-----------|------------|
| Browser Support | Chromium only | Chromium, Firefox, **WebKit (Safari)** |
| Device Profiles | Limited | 100+ built-in devices |
| Touch Gestures | Basic | Full support (swipe, pinch, etc.) |
| Visual Regression | None | Built-in screenshot comparison |
| Cross-browser | No | Yes |
| Mobile Safari Testing | No | Yes (via WebKit) |

## What This Tests

### 1. Visual Regression Testing
- **Full page screenshots** compared against baselines
- **Bottom section screenshots** for the "mashed together" area
- **Form actions area** where elements were cramped

### 2. Element Spacing
- Verifies minimum 8px gap between form elements
- Detects overlapping interactive elements
- Catches the "mashed together" layout bugs

### 3. Touch Targets (iOS Accessibility)
- All buttons >= 44x44px (Apple HIG requirement)
- Checkboxes have adequate touch areas
- Links are tappable on mobile

### 4. Mobile Nav Clearance
- Last element has 16px+ clearance above nav
- Page has adequate bottom padding (76px+)
- Content not hidden behind bottom navigation

### 5. Scroll Behavior
- All content reachable by scrolling
- No horizontal scroll on mobile
- Help panel visible when scrolled to bottom

## Quick Start

```bash
# Install dependencies
npm install

# Install browsers
npm run install-browsers

# Run all tests
npm test

# Run only mobile tests
npm run test:mobile

# Update visual baselines
npm run test:visual

# Debug mode with UI
npm run test:ui
```

## Device Coverage

### Mobile (Primary)
- iPhone SE (375x667) - Smallest common iPhone
- iPhone 14 (393x852) - Current standard
- iPhone 14 Pro Max (430x932) - Large phone
- Pixel 5 (393x851) - Android reference
- Galaxy S23 (360x780) - Samsung flagship

### Tablet
- iPad Mini (768x1024) - Breakpoint threshold
- iPad Pro 11 (834x1194) - Large tablet

### Desktop
- Chrome, Firefox, Safari

### Landscape (Critical for layout bugs)
- iPhone SE Landscape
- iPhone 14 Landscape

## Visual Regression Workflow

1. **First run**: Creates baseline screenshots
2. **Subsequent runs**: Compares against baselines
3. **On failure**: Shows visual diff highlighting changes
4. **To update**: Run `npm run test:visual`

### Screenshot Storage

```
tests/
  research-page-full.png-snapshots/
    research-page-full-iPhone-SE.png
    research-page-full-iPhone-14.png
    ...
```

## CI/CD Integration

Add to your GitHub Actions workflow:

```yaml
- name: Run Playwright tests
  run: |
    cd tests/ui_tests/playwright
    npm ci
    npx playwright install --with-deps
    npm test

- name: Upload test results
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: playwright-report
    path: tests/ui_tests/playwright/playwright-report/
```

## Key Files

- `playwright.config.js` - Device configurations and settings
- `tests/research-page.spec.js` - Research page mobile tests
- `package.json` - Dependencies and scripts

## Sources

- [BrowserStack: Playwright vs Puppeteer](https://www.browserstack.com/guide/playwright-vs-puppeteer)
- [Panto AI: Visual Regression in Mobile QA](https://www.getpanto.ai/blog/visual-regression-testing-in-mobile-qa)
- [Quash: Responsive Design Testing 2025](https://quashbugs.com/blog/responsive-design-testing-mobile-screen-size-2025)
- [Playwright Emulation Docs](https://playwright.dev/docs/emulation)