wiki/skills/ui-test/SKILL.md

name, description

name	description
ui-test	Автономное UI/UX тестирование веб-приложений через Playwright + vision analysis. Запуск тестов, скриншоты, визуальный анализ, отчёт.

UI/UX Auto-Testing Skill

Когда использовать

• После деплоя новой фичи — проверить что ничего не сломалось
• По запросу Славы — "проверь UI"
• Перед релизом фазы — регрессионный прогон всех тестов

Порядок тестирования

UI/UX тесты запускаются последними, после:

1. Unit/integration тесты (curl/grep, API)
2. Функциональные проверки (DOM, HTTP коды)
3. UI/UX тесты (этот скилл)

Быстрый старт

1. Проверить готовность

cd /home/node/.openclaw/workspace/skills/ui-test/scripts && node health_check.js

Все проверки должны быть ✅. Если нет — см. раздел "Установка".

2. Запустить тесты

cd /home/node/.openclaw/workspace/skills/ui-test/scripts
node run_tests.js <path/to/TEST_CASES.md> <output-dir>

Пример для enduro-trails:

node run_tests.js \
  /home/node/.openclaw/workspace/tasks/enduro-trails/TEST_CASES_UI.md \
  /home/node/.openclaw/workspace/tasks/enduro-trails/reports

Результат:

• <output-dir>/screenshots/ — PNG скриншоты
• <output-dir>/results.json — JSON с результатами

3. Проанализировать скриншоты

После запуска раннера — проанализировать скриншоты через image tool.

Для каждого check-visual из results.json:

1. Скопировать скриншот в workspace (image tool требует путь под ~/.openclaw/workspace/)
2. Вызвать image tool с промптом:

Ты — QA-инженер. Проанализируй скриншот веб-приложения.
Контекст: {check.description}
Визуальные критерии: {test.criteria}

Проверь:
1. Есть ли визуальные артефакты (пустые области, битые изображения, наложения)?
2. Текст читаем? Достаточный контраст?
3. Элементы UI расположены логично? Ничего не обрезано?
4. Для мобильного: нет горизонтального скролла? Кнопки достаточного размера?

Ответь: pass или fail + описание проблем.

3. Записать результат

4. Сформировать отчёт

Создать reports/ui-test-YYYY-MM-DD.md:

# UI Test Report: {project}
**Дата:** {date}
**Тесты:** {total} | ✅ {passed} | ❌ {failed}

| # | Тест | Desktop | Mobile | Проблемы |
|---|------|---------|--------|----------|
| TC-XX | Название | ✅/❌ | ✅/❌ | описание |

## Скриншоты проблемных тестов
### TC-XX ❌
![screenshot](screenshots/filename.png)
**Проблема:** описание

5. Отправить результат Славе

Всегда отправлять результат — даже если всё зелёное.

---

Формат тест-кейсов

Файл: TEST_CASES_UI.md (или секция в общем TEST_CASES файле с **Тип:** ui)

### TC-XX — Название теста
**Тип:** ui
**Viewport:** desktop | mobile | both
**URL:** https://example.com/

**Шаги:**
1. navigate: {url}
2. wait: {ms}
3. click: "{css-selector}"
4. scroll: {pixels}
5. resize: {width}x{height}
6. screenshot: "{name}"
7. check-visual: "{описание что проверяем}"

**Визуальные критерии:**
- Критерий 1
- Критерий 2

Доступные действия

Действие	Формат	Описание
navigate	navigate: {url}	Перейти на URL, ждать networkidle
wait	wait: {ms}	Подождать N миллисекунд
click	click: "{selector}"	Кликнуть по CSS-селектору (timeout 5s)
scroll	scroll: {pixels}	Прокрутить вниз на N пикселей
resize	resize: {w}x{h}	Изменить viewport
screenshot	screenshot: "{name}"	Сделать скриншот (сохраняется как {TC-ID}-{viewport}-{name}.png)
check-visual	check-visual: "{desc}"	Скриншот + пометка для vision-анализа

Viewport

• desktop — 1280×720, deviceScaleFactor 1
• mobile — 375×812, deviceScaleFactor 2, isMobile true, iPhone UA
• both — тест прогоняется дважды (desktop + mobile)

---

Установка (если health_check падает)

Chromium headless shell

npx --yes playwright install chromium

Устанавливается в ~/.cache/ms-playwright/

Системные библиотеки (без root)

Библиотеки уже извлечены в ~/chromium-libs/libs/. Если нет:

mkdir -p ~/chromium-libs && cd ~/chromium-libs
# Скачать deb-пакеты с ftp.us.debian.org (bookworm amd64):
# libglib2.0-0, libnss3, libnspr4, libatk1.0-0, libatk-bridge2.0-0,
# libdbus-1-3, libx11-6, libxcomposite1, libxdamage1, libxext6,
# libxfixes3, libxrandr2, libgbm1, libxcb1, libxkbcommon0, libasound2,
# libatspi2.0-0, libxrender1, libdrm2, libwayland-server0, libxau6,
# libxdmcp6, libxi6, libffi8, libpcre2-8-0, libbsd0
for deb in *.deb; do dpkg-deb -x "$deb" libs/; done

Node.js зависимости

cd /home/node/.openclaw/workspace/skills/ui-test/scripts && npm install

---

Ограничения

• Headless — нет GPU рендеринга. WebGL карты (MapLibre) рендерятся через software, могут выглядеть чуть иначе чем в реальном браузере
• Тайлы по сети — MapLibre грузит тайлы с tile.openstreetmap.org. Нужен wait: 3000-5000 после navigate
• Vision-анализ субъективен — false positives возможны. Severity critical/major — блокируют, minor — в отчёт
• Мобильный viewport — эмулирует размер экрана, но не реальные touch-события
• image tool path — скриншоты должны быть под ~/.openclaw/workspace/ для анализа через image tool. Копировать из /tmp если output-dir был там
• Селекторы — CSS-селекторы должны точно совпадать с реальными ID/классами на странице. Проверять через grep в исходниках перед написанием тестов

---

Проекты

Проект	URL	Тест-кейсы
enduro-trails	openclaw.mva154.duckdns.org/enduro/	tasks/enduro-trails/TEST_CASES_UI.md
noisemap	localhost:5555	tasks/flightradar24/TEST_CASES_UI.md
snowbike-rag	localhost:5557	tasks/snowbike-rag/TEST_CASES_UI.md

---

Файлы скилла

skills/ui-test/
├── SKILL.md                          # Этот файл
├── examples/
│   └── TEST_CASES_EXAMPLE.md         # Пример тест-кейсов
└── scripts/
    ├── health_check.js               # Проверка готовности окружения
    ├── parse_testcases.js            # Парсер markdown → JSON
    ├── run_tests.js                  # Раннер (Playwright + Chromium)
    ├── package.json                  # Зависимости
    └── node_modules/                 # playwright-core