APAW/.kilo/commands/web-test.md

# /web-test Command

Run visual regression testing pipeline in Docker. Captures screenshots, extracts UI elements with bounding boxes, compares against baselines, and detects console/network errors.

## Usage

```bash
/web-test <url> [--pages /,/about] [--threshold 0.05]
```

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `url` | Yes | Target URL to test |

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `--pages` | `/` | Comma-separated page paths |
| `--threshold` | `0.05` | Visual diff threshold (5%) |
| `--visual` | true | Run visual regression |
| `--console` | true | Run console error detection |
| `--auto-fix` | false | Auto-create Gitea Issues for errors |
| `--issue` | — | Gitea Issue number to post results |

## Examples

### Basic

```bash
/web-test https:// bbox.wtf
```

### Multiple pages

```bash
/web-test https://my-app.com --pages /,/login,/about
```

### Strict threshold

```bash
/web-test https://my-app.com --threshold 0.01
```

### Post results to Gitea Issue

```bash
/web-test https://my-app.com --issue 42
```

## Pipeline Steps

```
/web-test <url>
      ↓
1. Docker container starts (mcr.microsoft.com/playwright:v1.52.0-noble)
2. npm install pixelmatch, pngjs inside container
3. For each page × viewport (mobile, tablet, desktop):
   - Navigate to URL
   - Wait for networkidle
   - Capture fullPage screenshot
   - Extract all visible DOM elements with bounding boxes
   - Collect console errors and network failures
4. Compare current screenshots against baselines (pixelmatch)
   - Auto-create baselines on first run
   - Generate diff images (red pixels = differences)
5. Generate JSON report at tests/reports/visual-test-report.json
6. If GITEA_ISSUE is set, post formatted report + diff screenshots to Gitea Issue
7. Exit 0 if all passed, 1 if failures
```

## Output

| File | Description |
|------|-------------|
| `tests/visual/baseline/` | Reference screenshots (gitignored) |
| `tests/visual/current/` | Latest screenshots (gitignored) |
| `tests/visual/diff/` | Diff images (gitignored) |
| `tests/reports/visual-test-report.json` | Full report: elements, errors, diff % |

## Docker Compose Services

| Service | Command |
|---------|---------|
| `visual-tester` | Full pipeline (default) |
| `screenshot-baseline` | Capture baselines only |
| `screenshot-current` | Capture current only |
| `visual-compare` | pixelmatch comparison only |
| `console-monitor` | Console/network errors only |


## Docker Networking

Playwright containers need proper DNS resolution. Two modes:

### Local app testing (bridge network)

Default — uses `host.docker.internal` to reach services on the host:

```bash
docker compose -f docker/docker-compose.web-testing.yml up visual-tester
```

### External site testing (host network)

Required for testing external URLs where Docker DNS fails:

```bash
NETWORK_MODE=host docker compose -f docker/docker-compose.web-testing.yml up visual-tester
```

The `NETWORK_MODE` env var controls `network_mode` in docker-compose. Default is `bridge`
(for local apps), set to `host` for external sites.

All Playwright scripts include `--dns-resolution-order=hostname-first` via the shared
`browser-launcher.js` module when `DNS_RESOLUTION_ORDER=hostname-first` is set.

## Gitea Integration

When `GITEA_ISSUE` is set (via `--issue` flag or env var), the pipeline posts results to the specified Gitea Issue:

- **Comment body**: Markdown summary table with metrics, comparison details, errors
- **Attachments**: Diff screenshots uploaded as issue assets (if any differences found)
- **Auth**: Uses `GITEA_TOKEN` env var or `GITEA_USER`+`GITEA_PASS` (see `.kilo/shared/gitea-auth.md`)

### Docker usage

```bash
GITEA_ISSUE=42 docker compose -f docker/docker-compose.web-testing.yml up visual-tester
```

### Env vars

| Variable | Required | Description |
|----------|----------|-------------|
| `GITEA_ISSUE` | No | Issue number to post results |
| `GITEA_TOKEN` | No | Pre-existing API token (else Basic Auth) |
| `GITEA_API_URL` | No | API base URL (default: https://git.softuniq.eu/api/v1) |
| `GITEA_REPO` | No | Repository path (default: UniqueSoft/APAW) |

## Agent Flow

```
/web-test <url>
      ↓
@visual-tester — runs pipeline in Docker
      ↓
[issues found?]
      ↓ yes
@the-fixer — fixes UI bugs
      ↓
@visual-tester — re-runs to verify
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All tests passed |
| 1 | Visual diff > threshold or errors found |

## See Also

- `docker/docker-compose.web-testing.yml` — Docker Compose config
- `tests/scripts/visual-test-pipeline.js` — Pipeline implementation
- `.kilo/agents/visual-tester.md` — Agent definition