# 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 ❌
![tc-08-mobile](screenshots/tc-08-mobile.png)
**Проблема:** Попап 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-агента.*