# iPhone Browser Tool — Design Spec

## Context

The test suite currently only supports Chromium via Playwright. There is no way to test how WODA pages look or behave on an iPhone (WebKit/Safari). The goal is to add iPhone/WebKit support in two forms:

1. A standalone CLI tool (`iphone_browser.py`) for manual inspection — mirroring the existing `browser.py`
2. Integration with the automated test suite via a `--browser=webkit` flag

## Device Profile

- **Default device**: iPhone 15 Pro Max (Playwright built-in profile)
- **Viewport**: 430x932
- **Device scale factor**: 3x
- **User agent**: Safari on iOS
- **Touch**: enabled
- **isMobile**: true

## Architecture

### `iphone_browser.py` — Standalone CLI Tool

**Location**: `Components/me/hannesnortje/TestSuite/2.0.0/iphone_browser.py`

A standalone script mirroring `browser.py` but using WebKit with iPhone emulation instead of Chromium.

**Launch mechanism** (differs from `browser.py`):
- `browser.py` launches a raw Chromium binary via subprocess and connects via CDP
- `iphone_browser.py` uses `playwright.webkit.launch_server(headless=False)` which starts a WebKit browser as a background process and returns a WebSocket endpoint
- A daemon process keeps the Playwright server alive after the launch command exits
- State saved to `/tmp/playwright-iphone-browser-state.json` (separate from browser.py's `/tmp/playwright-browser-state.json`)
- A browser context is created with `playwright.devices["iPhone 15 Pro Max"]` applied

**Connect mechanism**:
- `playwright.webkit.connect(ws_endpoint)` reconnects to the running browser
- Accesses the existing context and page

**CLI commands** — identical to `browser.py`:
- `launch [--headless]`, `status`, `navigate <url>`, `screenshot`, `click`, `fill`, `type`, `key`, `evaluate`, `text`, `html`, `find`, `tabs`, `new_tab`, `switch`, `close_tab`, `drag`, `wait`, `back`, `forward`, `reload`, `close`

**Removed from browser.py**:
- `--port` flag (WebSocket port assigned automatically)
- `--devtools` flag (not supported by WebKit)

**Chromium-specific args removed**:
- `--no-sandbox`, `--disable-dev-shm-usage`, `--window-position`, etc. are not passed to WebKit

### Test Suite Integration

**`playwright_setup.py`** — modified:
- `create_playwright_context()` gains a `browser_type` parameter (default: `"chromium"`)
- When `"webkit"` is passed: launch WebKit, apply iPhone 15 Pro Max device profile, skip Chromium-specific args
- When `"chromium"` (default): behavior is unchanged

**`run_tests.py`** — modified:
- Accepts `--browser=webkit` flag
- Forwards the flag to the underlying test script
- Default remains Chromium (no change to existing behavior)

**Test scripts** (e.g. `TestWodaCanvasGauges.py`) — minimal change:
- Accept `--browser=webkit` via argparse
- Pass value through to `create_playwright_context()`
- All test logic, XPaths, and assertions remain unchanged

### Screenshot Directories

When running with `--browser=webkit`, screenshots use an `_iphone` suffix:
- Latest: `screenshots/latest/canvas_gauges_iphone/`
- Golden: `screenshots/golden/canvas_gauges_iphone/`

Default (Chromium) directories remain unchanged:
- Latest: `screenshots/latest/canvas_gauges/`
- Golden: `screenshots/golden/canvas_gauges/`

## Files Changed

| File | Action | Description |
|---|---|---|
| `TestSuite/2.0.0/iphone_browser.py` | New | Standalone iPhone/WebKit browser CLI tool |
| `TestSuite/2.0.0/utils/playwright_setup.py` | Modify | Add `browser_type` param, WebKit + iPhone device profile |
| `TestSuite/2.0.0/run_tests.py` | Modify | Pass through `--browser` flag |
| Test scripts (per test) | Modify | Add `--browser` argparse flag, pass to setup |

## Verification

1. **Manual browser tool**: `python iphone_browser.py launch` then `navigate` to a WODA page, `screenshot` — confirm iPhone dimensions and Safari UA
2. **Automated test**: `./run_tests.py canvas_gauges --browser=webkit` — confirm WebKit is used, iPhone viewport applied, screenshots saved to `canvas_gauges_iphone/`
3. **Default unchanged**: `./run_tests.py canvas_gauges` (no flag) — confirm Chromium at 1920x1080, no behavioral change

## Implementation Notes

Deviations from the original spec made during implementation:

- **Unix socket daemon instead of `launch_server()`**: Playwright 1.58 does not have `BrowserType.launch_server()`. The `iphone_browser.py` tool uses a daemon process that calls `webkit.launch()` and accepts commands via a Unix domain socket (`/tmp/playwright-iphone-browser.sock`), with a length-prefixed JSON protocol.
- **Auto-install of venv and WebKit**: Added in a follow-up commit — `iphone_browser.py` automatically creates the venv and installs WebKit on first use, unlike `browser.py` which requires manual setup.