APAW/tests/README.md

# Web Testing README

Автоматическое тестирование веб-приложений для APAW.

## Возможности

| Тест | Описание |
|------|----------|
| **Visual Regression** | Обнаружение визуальных дефектов: наложения элементов, смещения шрифтов, не те цвета |
| **Link Checking** | Проверка всех ссылок на 404/500 ошибки |
| **Form Testing** | Тестирование форм: заполнение, валидация, отправка |
| **Console Errors** | Захват JS ошибок, сетевых ошибок, создание Gitea Issues |

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

### 1. Запуск в Docker (без установки на хост)

```bash
# Запустить Playwright MCP контейнер
docker compose -f docker/docker-compose.web-testing.yml up -d

# Проверить что MCP работает
curl http://localhost:8931/mcp -X POST -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

### 2. Запуск тестов

```bash
# Указать целевой URL
export TARGET_URL=https://your-app.com

# Запустить все тесты
cd tests && npm install && npm test

# Или через скрипт из корня проекта
./scripts/web-test.sh https://your-app.com
```

### 3. Просмотр отчёта

```bash
# Открыть HTML отчёт
npm run report

# Или вручную
open tests/reports/web-test-report.html
```

## Использование с Kilo Code

### Команда /web-test

```
/web-test https://my-app.com
```

Запускает все тесты и генерирует отчёт.

### Команда /web-test-fix

```
/web-test-fix https://my-app.com
```

Запускает тесты + автоматически исправляет найденные ошибки через агентов.

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

```
tests/
├── scripts/
│   ├── compare-screenshots.js   # Visual regression
│   ├── link-checker.js          # Link checking
│   ├── console-error-monitor.js # Console errors
│   └── aggregate-errors.js      # Error aggregation
├── visual/
│   ├── baseline/                # Эталонные скриншоты
│   ├── current/                 # Текущие скриншоты
│   └── diff/                    # Разница (красное)
├── reports/
│   ├── web-test-report.html    # HTML отчёт
│   ├── web-test-report.json    # JSON отчёт
│   └── screenshots/            # Скриншоты
├── console/
├── links/
├── forms/
├── run-all-tests.js            # Главный runner
└── package.json
```

## Переменные окружения

| Переменная | По умолчанию | Описание |
|------------|--------------|----------|
| `TARGET_URL` | `http://localhost:3000` | URL для тестирования |
| `MCP_PORT` | `8931` | Порт Playwright MCP |
| `REPORTS_DIR` | `./reports` | Папка для отчётов |
| `PIXELMATCH_THRESHOLD` | `0.05` | Допустимый % отличий (5%) |
| `AUTO_CREATE_ISSUES` | `false` | Авто-создание Gitea Issues |
| `GITEA_TOKEN` | - | Токен Gitea API |
| `GITEA_REPO` | `UniqueSoft/APAW` | Репозиторий |

## Visual Regression Testing

### Как работает

1. Делает скриншот каждой страницы в 3 разрешениях (mobile, tablet, desktop)
2. Сравнивает с baseline (эталоном) через pixelmatch
3. Генерирует diff изображение (красные пиксели = отличия)
4. Создаёт отчёт с процентом изменившихся пикселей

### Эталонные скриншоты

```bash
# Создать эталон для новой страницы
node tests/scripts/compare-screenshots.js --baseline

# Обновить эталон после изменений
cp tests/visual/current/*.png tests/visual/baseline/
```

### Обнаруживаемые проблемы

- ✅ Наложение элементов (кнопка на кнопку)
- ✅ Сдвиг шрифтов (текст поехал)
- ✅ Неверные цвета (фон не тот)
- ✅ Отсутствующие элементы (кнопка пропала)
- ✅ Лишние элементы (появился артефакт)

## Console Error Detection

### Что ловит

| Тип | Пример |
|-----|--------|
| JavaScript Error | `TypeError: Cannot read property 'x' of undefined` |
| Syntax Error | `Unexpected token '<'` |
| Network Error | `Failed to fetch /api/users` |
| 404 Error | `GET /script.js 404 (Not Found)` |
| 500 Error | `POST /api/submit 500 (Internal Server Error)` |

### Авто-исправление

При `AUTO_CREATE_ISSUES=true`:

```
[Console Error Detected]
       ↓
[Gitea Issue Created]
       ↓
[@the-fixer Agent]
       ↓
[PR with Fix Created]
       ↓
[Issue Closed]
```

## Docker Compose

### Основной контейнер

```yaml
services:
  playwright-mcp:
    image: mcr.microsoft.com/playwright/mcp:latest
    ports:
      - "8931:8931"
    command: node cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0
    shm_size: '2gb'
```

### Профили

```bash
# Только visual testing
docker compose -f docker-compose.web-testing.yml --profile visual up

# Все тесты
docker compose -f docker-compose.web-testing.yml --profile full up
```

## CI/CD Integration

### GitHub Actions

```yaml
name: Web Testing
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Start Playwright MCP
        run: docker compose -f docker-compose.web-testing.yml up -d
      
      - name: Run Tests
        run: cd tests && npm install && npm test
        env:
          TARGET_URL: ${{ secrets.APP_URL }}
          AUTO_CREATE_ISSUES: true
          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
      
      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: web-test-report
          path: tests/reports/
```

## Troubleshooting

### MCP не отвечает

```bash
# Проверить контейнер
docker ps | grep playwright

# Перезапустить
docker compose -f docker-compose.web-testing.yml restart

# Логи
docker compose -f docker-compose.web-testing.yml logs -f
```

### Скриншоты пустые

```bash
# Увеличить timeout
export TIMEOUT=10000

# Проверить что headless включён
# (для Docker обязателен)
docker compose -f docker-compose.web-testing.yml config | grep headless
```

### Высокий процент ложных срабатываний

```bash
# Увеличить порог до 10%
export PIXELMATCH_THRESHOLD=0.10

# Или отключить для конкретного теста
node tests/scripts/compare-screenshots.js --no-compare --create-baseline
```

## See Also

- `.kilo/skills/web-testing/SKILL.md` - Полная документация
- `.kilo/commands/web-test.md` - Команда тестирования
- `.kilo/commands/web-test-fix.md` - Тестирование с авто-исправлением
- `docker-compose.web-testing.yml` - Docker конфигурация