APAW/tests/README.md

# Web Testing Suite — APAW

Автоматическое тестирование веб-приложений. Запускается целиком в Docker без зависимостей на хосте.

## Возможности

| Тест | Скрипт | Описание |
|------|--------|----------|
| **Visual Regression** | `visual-test-pipeline.js` | Скриншоты + pixelmatch + извлечение UI-элементов с bbox |
| **Screenshot Capture** | `capture-screenshots.js` | Захват baseline/current скриншотов в 3 viewport |
| **Screenshot Compare** | `compare-screenshots.js` | Сравнение PNG через pixelmatch |
| **Console Errors** | `console-error-monitor-standalone.js` | Ловит JS ошибки, network 4xx/5xx, request failures |
| **Link Checking** | `link-checker.js` | Проверка ссылок на 404/500 |

## Быстрый старт

### Вариант 1: Docker Compose (рекомендуется)

```bash
# Полный визуальный пайплайн (захват + сравнение + элементы + ошибки)
docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com \
  -e PAGES=/ \
  visual-tester

# Только захват baseline-скриншотов
docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com \
  screenshot-baseline

# Только захват текущих скриншотов
docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com \
  screenshot-current

# Только сравнение (pixelmatch)
docker compose -f docker/docker-compose.web-testing.yml run --rm visual-compare

# Мониторинг консольных ошибок
docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com \
  console-monitor
```

### Вариант 2: Прямой docker run

```bash
docker run --rm \
  --add-host=host.docker.internal:host-gateway \
  --shm-size=2g \
  -v $(pwd)/tests:/app/tests \
  -e TARGET_URL=https://example.com \
  -e PAGES=/ \
  mcr.microsoft.com/playwright:v1.52.0-noble \
  sh -c "cd /app/tests && npm install --ignore-scripts && node scripts/visual-test-pipeline.js"
```

## Структура

```
tests/
├── scripts/
│   ├── visual-test-pipeline.js          # Полный пайплайн (захват + сравнение + элементы)
│   ├── capture-screenshots.js            # Захват скриншотов (baseline|current)
│   ├── compare-screenshots.js            # Сравнение PNG (pixelmatch)
│   ├── console-error-monitor-standalone.js  # Мониторинг console/network ошибок
│   ├── console-error-monitor.js          # Мониторинг через Playwright MCP
│   └── link-checker.js                  # Проверка ссылок
├── visual/
│   ├── baseline/                         # Эталонные скриншоты (git-tracked)
│   ├── current/                          # Текущие скриншоты (gitignored)
│   └── diff/                             # Diff-изображения (gitignored)
├── reports/                              # JSON-отчёты (gitignored)
│   ├── visual-test-report.json
│   └── console-error-report.json
├── package.json
└── README.md
```

## Переменные окружения

| Переменная | По умолчанию | Описание |
|------------|--------------|----------|
| `TARGET_URL` | `http://host.docker.internal:3000` | URL тестируемого приложения |
| `PAGES` | `/,/admin/login` | Список путей через запятую |
| `PIXELMATCH_THRESHOLD` | `0.05` | Допустимый % отличий (5%) |
| `REPORTS_DIR` | `./reports` | Папка для отчётов |

## Visual Regression — как работает

1. **Захват скриншотов** — Playwright открывает страницу в 3 viewport (mobile 375x667, tablet 768x1024, desktop 1280x720)
2. **Извлечение элементов** — обходит DOM, собирает bbox, tag, className, text, href для каждого видимого элемента
3. **Сравнение** — pixelmatch сравнивает текущие PNG с baseline, генерирует diff-изображение
4. **Отчёт** — JSON с результатами: элементы, console/network ошибки, diff-процент

### Baseline-скриншоты

При первом запуске без baseline скрипт автоматически создаёт их. Для обновления:

```bash
docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com screenshot-baseline
```

### Обнаруживаемые проблемы

- Наложение элементов (кнопка вне viewportа)
- Сдвиг шрифтов / неверные цвета
- Отсутствующие / лишние элементы
- Микро-кнопки (width < 10px)
- Console JS errors
- Network errors (4xx/5xx)

## Пример отчёта

```json
{
  "summary": {
    "screenshotsCaptured": 3,
    "totalElements": 702,
    "comparisonsPassed": 3,
    "comparisonsFailed": 0,
    "totalConsoleErrors": 0,
    "totalNetworkErrors": 25
  },
  "elements": {
    "homepage_desktop": [
      { "tag": "button", "text": "Buy Now", "bbox": {"x":318,"y":349,"width":644,"height":47} }
    ]
  }
}
```

## Docker-образ

Используется `mcr.microsoft.com/playwright:v1.52.0-noble` — предустановленный Playwright с Chromium.

## See Also

- `docker/docker-compose.web-testing.yml` — Docker Compose конфигурация
- `.kilo/agents/visual-tester.md` — Агент визуального тестирования
- `.kilo/commands/e2e-test.md` — E2E workflow