feat: add AI-powered visual regression testing infrastructure

- Add docker-compose.web-testing.yml with vlmkit service - Add 5 test scripts: capture, compare, pipeline, console-monitor, link-checker - Add vrt.config.json with 3 viewports + maskSelectors - Add package.json with @mizchi/vlmkit and Node >=24 - Add tests/README.md with VRT documentation - Update .gitignore for test artifacts Based on APAW issue #144 / milestone #106
2026-06-30 21:09:30 +01:00
parent f2d4d6d3b1
commit 8d85776135
10 changed files with 1049 additions and 44 deletions
--- a/tests/README.md
+++ b/tests/README.md
@@ -0,0 +1,188 @@
+# 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