From c73cd88c91d34e482470f8e78e4b1869d0451e01 Mon Sep 17 00:00:00 2001 From: Stream Date: Tue, 12 May 2026 23:50:01 +0300 Subject: [PATCH] auto-sync: 2026-05-12 23:50:01 --- tasks/enduro-trails/prototype/static/app.js | 10 + tasks/ui-test-skill/BRD.md | 263 ++++++++++++++++++++ 2 files changed, 273 insertions(+) create mode 100644 tasks/ui-test-skill/BRD.md diff --git a/tasks/enduro-trails/prototype/static/app.js b/tasks/enduro-trails/prototype/static/app.js index 725f28c..c5e0a09 100644 --- a/tasks/enduro-trails/prototype/static/app.js +++ b/tasks/enduro-trails/prototype/static/app.js @@ -90,9 +90,19 @@ function switchMapStyle() { const basePath = window.location.pathname.replace(/\/[^/]*$/, '') || ''; const styleUrl = dark ? basePath + '/style-dark.json' : basePath + '/style.json'; + // Save current position before style change + const center = map.getCenter(); + const zoom = map.getZoom(); + const bearing = map.getBearing(); + const pitch = map.getPitch(); + fetch(styleUrl, { method: 'HEAD' }).then(r => { if (r.ok) { map.setStyle(styleUrl); + // Restore position after style loads + map.once('style.load', () => { + map.jumpTo({ center, zoom, bearing, pitch }); + }); } else { console.log('Map style not available:', styleUrl); } diff --git a/tasks/ui-test-skill/BRD.md b/tasks/ui-test-skill/BRD.md new file mode 100644 index 0000000..5f1894b --- /dev/null +++ b/tasks/ui-test-skill/BRD.md @@ -0,0 +1,263 @@ +# 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-агента.*