264 lines
12 KiB
Markdown
264 lines
12 KiB
Markdown
# 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 тестирования без участия Славы:
|
||
|
||
1. Открыть страницу в реальном браузере (desktop + mobile viewport)
|
||
2. Выполнить сценарий (клики, скролл, зум, переключение темы)
|
||
3. Сделать скриншоты на ключевых шагах
|
||
4. Проанализировать скриншоты через vision-модель (визуальные артефакты, layout, читаемость)
|
||
5. Сравнить с baseline (опционально — pixel diff)
|
||
6. Сформировать отчёт: ✅/❌ по каждому тест-кейсу + скриншоты
|
||
|
||
---
|
||
|
||
## 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-шагов:
|
||
|
||
```markdown
|
||
### 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`
|
||
|
||
```markdown
|
||
# 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)
|
||
```
|
||
|
||
---
|
||
|
||
## Интеграция с текущим процессом
|
||
|
||
### Когда запускать
|
||
|
||
1. **После деплоя** — Стрим запускает тесты автоматически после успешного деплоя Dev-агентом
|
||
2. **По запросу** — Слава говорит «проверь UI» → Стрим запускает полный прогон
|
||
3. **Регрессия** — перед релизом новой фазы прогнать все тесты предыдущих фаз
|
||
|
||
### Кто запускает
|
||
|
||
Стрим — через `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 — что нужно реализовать
|
||
|
||
1. **Парсер тест-кейсов** — читает TEST_CASES_*.md, извлекает UI-тесты
|
||
2. **Runner** — оркестрирует browser tool: open → шаги → screenshot
|
||
3. **Analyzer** — отправляет скриншоты в vision-модель, парсит ответ
|
||
4. **Reporter** — генерирует markdown-отчёт со скриншотами
|
||
5. **SKILL.md** — документация скилла для Стрим
|
||
|
||
### Оценка трудозатрат
|
||
|
||
| Компонент | Сложность | Время Dev |
|
||
|-----------|-----------|-----------|
|
||
| Парсер | Низкая | 30 мин |
|
||
| Runner (browser integration) | Средняя | 1-2 часа |
|
||
| Analyzer (vision prompts) | Средняя | 1 час |
|
||
| Reporter | Низкая | 30 мин |
|
||
| SKILL.md + интеграция | Низкая | 30 мин |
|
||
| **Итого** | | **~4 часа** |
|
||
|
||
---
|
||
|
||
## Решения (согласовано 12.05.2026)
|
||
|
||
1. **Формат тест-кейсов:** Markdown (расширение текущего TEST_CASES_*.md)
|
||
2. **Скриншоты:** `tasks/{project}/reports/screenshots/`
|
||
3. **Порядок тестов:** unit/integration → API (curl/grep) → UI/UX (последним)
|
||
4. **Порог алерта:** Всегда. Любой fail → отчёт Славе
|
||
5. **Инструменты:** Все зависимости предустановлены в контейнере/workspace. SKILL.md содержит полные инструкции по использованию каждого компонента (browser tool, vision analysis, reporter)
|
||
|
||
---
|
||
|
||
## Требования к установке
|
||
|
||
Скилл должен быть self-contained:
|
||
- Все скрипты/утилиты установлены и готовы к работе
|
||
- SKILL.md содержит пошаговые инструкции: как запустить тесты, как читать отчёт, как добавить новый тест-кейс
|
||
- Никаких «сначала установи X» — всё уже на месте
|
||
- Проверка готовности: команда `health check` в скилле подтверждает что всё работает
|
||
|
||
---
|
||
|
||
*Статус: согласовано, готово к написанию ТЗ для Dev-агента.*
|