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 (рекомендуется)

# Полный визуальный пайплайн (захват + сравнение + элементы + ошибки)
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

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 скрипт автоматически создаёт их. Для обновления:

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)

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

{
  "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:

# Убедитесь, что 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

# Захват 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