telegram-shop/tests/README.md

# Web Testing Suite

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

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

| Тест | Скрипт | Описание |
|------|--------|----------|
| **Visual Regression** | `visual-test-pipeline.js` | Скриншоты + pixelmatch + извлечение UI-элементов с bbox |
| **VLMKit AI VRT** | `@mizchi/vlmkit` | AI-powered pixel + computed-style + a11y tree diff |
| **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

# VLMKit AI-powered visual regression (новый)
docker compose -f docker/docker-compose.web-testing.yml run --rm \
  -e TARGET_URL=https://example.com \
  -e PAGES=/,/login,/cart \
  vlmkit
```

### Вариант 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
├── vrt.config.json                         # Конфигурация @mizchi/vlmkit
├── package.json
└── README.md
```

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

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

## 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} }
    ]
  }
}
```

## VLMKit AI-Powered Visual Regression

Для запуска AI-анализа визуальных регрессий через `@mizchi/vlmkit`:

```bash
# Убедитесь, что Node.js >= 24
docker compose -f docker/docker-compose.web-testing.yml run --rm vlmkit
```

### Требования

- **Node.js 24+**: `@mizchi/vlmkit` требует Node.js версии 24 или выше.
- **pnpm**: Рекомендуется для установки `@mizchi/vlmkit`.

### Команды VLMKit

```bash
# Захват baseline-скриншотов
npx vlmkit snapshot --url http://localhost:3000 --pages /,/login,/cart --out ./visual/baseline

# Сравнение текущих скриншотов с baseline
npx vlmkit diff --baseline ./visual/baseline --current ./visual/current --out ./visual/diff

# Проверка доступности (a11y)
npx vlmkit check a11y --url http://localhost:3000 --pages /,/login,/cart
```

### Конфигурация

Настройки `vrt.config.json`:
- `baseUrl`: URL тестируемого приложения
- `pages`: Список страниц для тестирования
- `viewports`: Разрешения экранов (mobile, tablet, desktop)
- `maskSelectors`: Селекторы для скрытия динамического контента
- `thresholds`: Пороги для pixel, style и a11y проверок
- `ai.generateCssFix`: Автоматическая генерация CSS-фиксов (требует API ключ)

## 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