# UI Testing Infrastructure 🧪

> Инфраструктура для автоматизированного UI-тестирования веб-приложений с визуальной проверкой скриншотов

**Статус:** planning  
**Старт:** 2026-05-04  
**Автор:** Стрим 🌊

---

## Проблема

При тестировании Enduro Trails Фаза 3 столкнулись с тем, что:
- Playwright/Puppeteer не запускаются в OpenClaw-контейнере (нет системных библиотек: libglib, libnss, libatk и др.)
- SSH-бинарник в контейнере требует glibc 2.38+, а в контейнере 2.36
- Внешние screenshot-сервисы требуют API-ключи
- Без скриншотов невозможно проверить визуальные тест-кейсы: hover, drag, цвета, layout

Из 56 тест-кейсов Фазы 3 только ~20 можно проверить через API. Остальные 36 требуют браузера.

---

## Цель

Создать **переиспользуемую инфраструктуру** для UI-тестирования любых веб-приложений проекта:
- Запуск браузера (headless Chromium)
- Скриншоты на каждом шаге
- Анализ скриншотов через vision-модель (Qwen 3.6 Plus)
- Структурированный отчёт с результатами

---

## Варианты реализации

### Вариант A: Chromium на сервере mva154 (рекомендуемый)

**Идея:** установить Chromium на mva154, запускать тесты там через SSH, скриншоты копировать обратно.

**Плюсы:**
- Полный контроль над окружением
- Нет ограничений контейнера
- Один раз настроил — работает всегда
- Тесты гоняются рядом с приложением (нет сетевых задержек)

**Минусы:**
- Нужна установка на сервере (apt install chromium-browser)
- Зависит от доступности mva154

**Реализация:**
```bash
# На mva154:
sudo apt-get install -y chromium-browser nodejs npm
npm install -g puppeteer-core

# Скрипт теста запускается через ssh_exec.sh:
ssh_exec.sh --host mva154 --cmd "node /home/slin/ui-tests/test.js" --timeout 120
# Скриншоты копируются обратно через scp
```

---

### Вариант B: Docker-контейнер с Chromium на mva154

**Идея:** отдельный Docker-контейнер `ui-tester` с предустановленным Playwright.

**Плюсы:**
- Изолированное окружение
- Воспроизводимо
- Можно запускать по требованию

**Минусы:**
- Нужно место на диске (~1.5 GB для Playwright + Chromium)
- Дополнительный контейнер

**Dockerfile:**
```dockerfile
FROM mcr.microsoft.com/playwright:v1.44.0-jammy
WORKDIR /tests
COPY package.json .
RUN npm install
```

**Запуск:**
```bash
docker run --rm -v /home/slin/ui-tests:/tests ui-tester node test.js
```

---

### Вариант C: GitHub Actions / CI (для будущего)

**Идея:** тесты запускаются в CI при каждом деплое.

**Плюсы:** автоматически, не требует ручного запуска  
**Минусы:** нужен GitHub repo, сложнее настроить

---

## Требования к инфраструктуре

### R-01: Запуск браузера
- Headless Chromium (без GUI)
- Поддержка viewport: desktop (1280×800) и mobile (375×667)
- Поддержка JavaScript (SPA-приложения)
- Ожидание `networkidle` перед скриншотом

### R-02: Управление тестами
- Тесты описываются как JS-скрипты (Playwright API)
- Каждый тест: precondition → steps → assertions → screenshot
- Поддержка `waitForSelector`, `waitForFunction`, `click`, `hover`, `drag`
- Debounce-действия (ждать N мс после клика)

### R-03: Скриншоты
- PNG, полная страница или viewport
- Именование: `TC-ID-step-description.png`
- Хранение: `/home/node/.openclaw/workspace/tasks/<project>/screenshots/`
- Автоматическое создание директории

### R-04: Анализ скриншотов через vision
- После каждого скриншота — опциональный вызов image-tool с Qwen 3.6 Plus
- Промпт для анализа: что видно на скрине, соответствует ли ожиданиям
- Результат анализа включается в отчёт

### R-05: Отчёт
- Markdown-файл с результатами
- Структура: PASSED / FAILED / BLOCKED
- Для каждого FAILED: скриншот + описание бага
- Итоговая статистика

### R-06: Интеграция с OpenClaw
- Запуск через `sessions_spawn` (dev-агент)
- Скриншоты доступны в workspace для анализа через `image` tool
- Отчёт сохраняется в `tasks/<project>/reports/`

---

## Архитектура

```
OpenClaw (Стрим)
    │
    ├── sessions_spawn(dev) → запуск тестов
    │       │
    │       └── ssh_exec.sh --host mva154
    │               │
    │               └── node test.js (Playwright на mva154)
    │                       │
    │                       ├── Chromium headless
    │                       ├── Скриншоты → /tmp/screenshots/
    │                       └── Результаты → /tmp/test_results.json
    │
    ├── scp скриншоты → workspace/screenshots/
    │
    └── image(screenshot, model=qwen3.6) → визуальный анализ
            │
            └── Финальный отчёт TEST_REPORT.md
```

---

## Структура проекта

```
tasks/ui-testing/
├── PROJECT.md              ← этот файл
├── README.md               ← как запустить
├── scripts/
│   ├── setup-mva154.sh     ← установка Chromium на mva154
│   ├── run-tests.sh        ← запуск тестов (wrapper)
│   └── analyze-screenshots.js  ← анализ через vision API
├── tests/
│   ├── enduro-phase3.js    ← тесты Enduro Trails Фаза 3
│   └── template.js         ← шаблон для новых тестов
└── reports/
    └── .gitkeep
```

---

## План реализации

### Этап 1: Установка окружения на mva154
- [ ] Установить chromium-browser через apt
- [ ] Установить Node.js 20+ (если нет)
- [ ] Установить puppeteer-core глобально
- [ ] Проверить: `chromium-browser --version`

### Этап 2: Базовый тест-раннер
- [ ] Написать `scripts/run-tests.sh` — wrapper для запуска через ssh_exec.sh
- [ ] Написать `tests/template.js` — шаблон теста с Puppeteer
- [ ] Проверить: скриншот главной страницы Enduro Trails

### Этап 3: Тесты Enduro Trails Фаза 3
- [ ] Перенести все 56 тест-кейсов из TEST_CASES_PHASE3.md в `tests/enduro-phase3.js`
- [ ] Запустить полный прогон
- [ ] Скопировать скриншоты в workspace

### Этап 4: Визуальный анализ
- [ ] Для каждого скриншота — вызов `image` tool с Qwen 3.6 Plus
- [ ] Промпты для каждого типа проверки (карточки, полоска, hover и т.д.)
- [ ] Итоговый отчёт

### Этап 5: Переиспользование
- [ ] Документировать как добавить тесты для нового проекта
- [ ] Шаблон тест-скрипта

---

## Приоритет

**Первый запуск:** Enduro Trails Фаза 3 — 36 непроверенных UI тест-кейсов ждут.

---

*Проект создан после того как Playwright не запустился в OpenClaw-контейнере при тестировании Enduro Trails Фаза 3 (2026-05-04).*