12 KiB
12 KiB
BRD: UI/UX Auto-Testing Skill
Дата: 2026-05-12
Автор: Стрим
Статус: Draft
Проблема
Сейчас UI/UX тестирование в наших проектах — узкое место:
- Тест-кейсы пишутся (TEST_CASES_TERRAIN.md — 25 штук), но «ручные» висят неделями
- Стрим проверяет через curl/grep — ловит только «элемент есть в DOM», не «выглядит нормально»
- Мобильные тесты (TC-24, TC-25) вообще не проверяются — нет инструмента
- Визуальные баги (зелёные прямоугольники, прыжки карты) ловятся только когда Слава открывает сайт
- Нет regression-тестирования — после каждого деплоя может сломаться что угодно
Цель
Скилл, который позволяет Стрим автономно запускать полный цикл UI/UX тестирования без участия Славы:
- Открыть страницу в реальном браузере (desktop + mobile viewport)
- Выполнить сценарий (клики, скролл, зум, переключение темы)
- Сделать скриншоты на ключевых шагах
- Проанализировать скриншоты через vision-модель (визуальные артефакты, layout, читаемость)
- Сравнить с baseline (опционально — pixel diff)
- Сформировать отчёт: ✅/❌ по каждому тест-кейсу + скриншоты
Scope
В скоупе (MVP)
- Запуск тестов по файлу тест-кейсов (формат TEST_CASES_*.md)
- Desktop viewport (1280×720) + Mobile viewport (375×812)
- Базовые действия: navigate, click, scroll, wait, resize, screenshot
- Визуальный анализ скриншотов через image-модель (GPT-4o / Gemini)
- Отчёт в markdown с вложенными скриншотами
- Интеграция с browser-automation скиллом OpenClaw (Playwright)
В скоупе (v2, после MVP)
- Baseline screenshots + pixel diff (регрессия)
- Автозапуск после деплоя (хук в DEV_WORKFLOW)
- Performance метрики (LCP, CLS, FID через Lighthouse)
- Accessibility audit (axe-core через evaluate)
- Тестирование на реальных мобильных устройствах (через OpenClaw node)
Вне скоупа
- Unit/integration тесты бэкенда
- Нагрузочное тестирование
- Тестирование API (это curl/grep, уже работает)
Архитектура
Стрим: "Запусти UI-тесты для enduro-trails"
↓
Скилл ui-test: читает TEST_CASES файл
↓
Парсит тест-кейсы → список сценариев
↓
Для каждого сценария:
├── browser open (desktop viewport)
├── Выполнить шаги (click, wait, scroll...)
├── screenshot на ключевых точках
├── image analysis (vision model) → pass/fail
├── [опционально] resize → mobile → повторить
└── Записать результат
↓
Сформировать отчёт → reports/ui-test-YYYY-MM-DD.md
↓
Стрим: отправить саммари Славе (или молча если всё зелёное)
Компоненты
| Компонент | Технология | Назначение |
|---|---|---|
| Test runner | Python/Node скрипт | Парсинг тест-кейсов, оркестрация |
| Browser | OpenClaw browser tool (Playwright) | Реальный браузер, скриншоты |
| Vision analyzer | image tool (GPT-4o/Gemini) | Анализ скриншотов на артефакты |
| Reporter | Markdown generator | Отчёт с результатами и скриншотами |
Формат тест-кейсов
Расширение текущего формата TEST_CASES_*.md с добавлением UI-шагов:
### TC-XX — Название теста
**Тип:** ui
**Viewport:** desktop | mobile | both
**URL:** https://openclaw.mva154.duckdns.org/enduro/
**Шаги:**
1. navigate: {url}
2. wait: 3000
3. screenshot: "initial-load"
4. click: "#terrain-btn"
5. wait: 1000
6. screenshot: "terrain-popup"
7. check-visual: "Попап с чекбоксами виден, не перекрывает карту"
**Визуальные критерии:**
- Нет пустых белых/чёрных областей
- Текст читаем (контраст)
- Элементы не перекрывают друг друга
- Нет горизонтального скролла (mobile)
Визуальный анализ (Vision Model)
Ключевая фича — не pixel-perfect сравнение, а семантический анализ через vision-модель:
Промпт для анализа:
Ты — QA-инженер. Проанализируй скриншот веб-приложения.
Проверь:
1. Есть ли визуальные артефакты (пустые области, битые изображения, наложения)?
2. Текст читаем? Достаточный контраст?
3. Элементы UI расположены логично? Ничего не обрезано?
4. Для мобильного: нет горизонтального скролла? Кнопки достаточного размера (>44px)?
Дополнительный контекст: {описание из тест-кейса}
Ответь JSON:
{
"pass": true/false,
"issues": ["описание проблемы 1", ...],
"severity": "critical" | "major" | "minor" | "none"
}
Отчёт
Формат: tasks/{project}/reports/ui-test-YYYY-MM-DD-HHMMSS.md
# UI Test Report: enduro-trails
**Дата:** 2026-05-12 20:30 UTC
**Viewport:** desktop (1280×720) + mobile (375×812)
**URL:** https://openclaw.mva154.duckdns.org/enduro/
## Результаты
| # | Тест | Desktop | Mobile | Проблемы |
|---|------|---------|--------|----------|
| TC-07 | Кнопка terrain | ✅ | ✅ | — |
| TC-08 | Попап чекбоксы | ✅ | ❌ | Попап обрезан снизу |
| TC-24 | Мобильный попап | — | ❌ | Кнопка < 44px |
## Скриншоты
### TC-08 Mobile ❌
**Проблема:** Попап terrain обрезан снизу экрана, чекбокс hillshade не виден
## Саммари
- ✅ Пройдено: 18/20
- ❌ Провалено: 2/20
- Критичных: 0
- Важных: 1 (TC-08 mobile)
- Минорных: 1 (TC-24)
Интеграция с текущим процессом
Когда запускать
- После деплоя — Стрим запускает тесты автоматически после успешного деплоя Dev-агентом
- По запросу — Слава говорит «проверь UI» → Стрим запускает полный прогон
- Регрессия — перед релизом новой фазы прогнать все тесты предыдущих фаз
Кто запускает
Стрим — через sessions_spawn или напрямую (это не код, это тестирование):
Стрим: "Запускаю UI-тесты для enduro-trails после деплоя F-18"
→ browser open → сценарии → скриншоты → анализ → отчёт
→ "✅ 18/20 тестов пройдено. 2 минорных бага на мобильном — описание в отчёте"
Проекты-потребители
| Проект | URL | Что тестировать |
|---|---|---|
| enduro-trails | openclaw.mva154.duckdns.org/enduro/ | Карта, маршруты, terrain, тема, мобильный |
| noisemap | localhost:5555 | Карта шума, слои, легенда |
| snowbike-rag | localhost:5557 | Поиск, результаты, пагинация |
Ограничения и риски
| Риск | Митигация |
|---|---|
| Vision-модель галлюцинирует «баги» | Порог severity: только critical/major блокируют. Minor — в отчёт, не алерт |
| Браузер не стартует (headless issues) | Fallback: только curl + DOM проверки |
| Скриншоты тяжёлые (диск) | Ротация: хранить последние 5 прогонов, старые удалять |
| Нестабильные тесты (flaky) | Retry 1 раз перед fail. Если 2/3 pass — pass |
| Стоимость vision-вызовов | Batch: один вызов на 2-4 скриншота, не по одному |
MVP — что нужно реализовать
- Парсер тест-кейсов — читает TEST_CASES_*.md, извлекает UI-тесты
- Runner — оркестрирует browser tool: open → шаги → screenshot
- Analyzer — отправляет скриншоты в vision-модель, парсит ответ
- Reporter — генерирует markdown-отчёт со скриншотами
- SKILL.md — документация скилла для Стрим
Оценка трудозатрат
| Компонент | Сложность | Время Dev |
|---|---|---|
| Парсер | Низкая | 30 мин |
| Runner (browser integration) | Средняя | 1-2 часа |
| Analyzer (vision prompts) | Средняя | 1 час |
| Reporter | Низкая | 30 мин |
| SKILL.md + интеграция | Низкая | 30 мин |
| Итого | ~4 часа |
Решения (согласовано 12.05.2026)
- Формат тест-кейсов: Markdown (расширение текущего TEST_CASES_*.md)
- Скриншоты:
tasks/{project}/reports/screenshots/ - Порядок тестов: unit/integration → API (curl/grep) → UI/UX (последним)
- Порог алерта: Всегда. Любой fail → отчёт Славе
- Инструменты: Все зависимости предустановлены в контейнере/workspace. SKILL.md содержит полные инструкции по использованию каждого компонента (browser tool, vision analysis, reporter)
Требования к установке
Скилл должен быть self-contained:
- Все скрипты/утилиты установлены и готовы к работе
- SKILL.md содержит пошаговые инструкции: как запустить тесты, как читать отчёт, как добавить новый тест-кейс
- Никаких «сначала установи X» — всё уже на месте
- Проверка готовности: команда
health checkв скилле подтверждает что всё работает
Статус: согласовано, готово к написанию ТЗ для Dev-агента.