wiki/tasks/ui-testing/PROJECT.md

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

Реализация:

# На 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:

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

Запуск:

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).