---
name: ui-test
description: "Автономное 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. Проверить готовность

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

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

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

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

Пример для enduro-trails:
```bash
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`:

```markdown
# 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`)

```markdown
### 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
```bash
npx --yes playwright install chromium
```
Устанавливается в `~/.cache/ms-playwright/`

### Системные библиотеки (без root)
Библиотеки уже извлечены в `~/chromium-libs/libs/`. Если нет:
```bash
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 зависимости
```bash
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
```