playwright-ai-auto-debug

v3.2.4

Published

2 months ago

Automatic Playwright test debugging with AI assistance + UI Test Coverage Analysis

0High
0Medium
0Low

playwright ai debug openai testing automation e2e artificial-intelligence test-automation debugging ui-coverage test-coverage element-tracking

@playwright-ai/auto-debug

🤖 Автоматическая отладка Playwright тестов с помощью ИИ

✨ Основные возможности

🤖 AI-анализ ошибок - автоматическое определение причин падения тестов
📊 UI Test Coverage - реальное покрытие элементов интерфейса тестами (НОВОЕ!)
🎯 Объединенные отчеты - drill-down анализ по тестам, страницам и элементам
📊 Интеграция с отчетами - встраивание решений в HTML и Allure отчеты
🏗️ Clean Architecture - Domain-Driven Design с DI контейнером
🔌 MCP Integration - DOM snapshots для точной диагностики
🎯 Умное сопоставление - ИИ решения прикрепляются к релевантным тестам
🧩 Множественные AI провайдеры - OpenAI, Mistral, LocalAI с единым интерфейсом
🖥️ Современный CLI - команды debug, info, setup, validate
🔧 Простая настройка - конфигурация через ai.conf.js или .ts

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

# 1. Установка
npm install playwright-ai-auto-debug

# 2. Создание конфигурации
echo "export const ai_conf = { api_key: 'your-api-key' };" > ai.conf.js

# 3. Интерактивная настройка (новое в v2.0+)
node src/main.js setup

# 4. Запуск анализа
npx playwright-ai                    # Legacy CLI (обратная совместимость)
node src/main.js debug               # Новая архитектура

# 5. Запуск с MCP (DOM snapshots)
node src/main.js debug --use-mcp     # Рекомендуется для точной диагностики

🎯 UI Test Coverage (НОВОЕ!)

Система реального покрытия элементов интерфейса тестами:

# 1. Установка и настройка в проекте
npm install playwright-ai-auto-debug
npx playwright-ai coverage init

# 2. Использование в тестах

// Импорт из локальной папки (создается автоматически)
import { test, expect } from './coverage-lib/fixture.js';

test.describe('🎯 Мои тесты с покрытием', () => {
  test('✅ Автоматическое отслеживание', async ({ page }) => {
    await page.goto('https://example.com');
    
    // Каждое взаимодействие автоматически отслеживается
    await page.locator('button').click();
    await page.locator('#login').fill('user');
    await page.locator('text=Submit').click();
  });
});

# 3. Запуск тестов с покрытием
npm run test:coverage

# 4. Открытие объединенного отчета
npm run coverage:open
# или
open test-coverage-reports/index.html

🎯 Объединенный отчет показывает:

📊 Общее покрытие - процент элементов покрытых тестами
🌐 По страницам - drill-down анализ каждой страницы
🧪 По тестам - какие элементы покрывает каждый тест
🎯 Непокрытые элементы - с предлагаемыми селекторами
📝 Анализ селекторов - эффективность использования
💡 Интерактивная навигация - клик для детализации

✨ Ключевые особенности:

Один отчет вместо множества файлов
Drill-down интерфейс для проваливания в детали
Автоматическое отслеживание всех взаимодействий с элементами
Приоритизация элементов по важности для тестирования
Умные рекомендации селекторов для непокрытых элементов

🎯 Workflow для пользователя:

# В любом Playwright проекте:
npm install playwright-ai-auto-debug   # Установка
npx playwright-ai coverage init        # Настройка (один раз)

# В ваших тестах просто замените импорт:
# ❌ import { test, expect } from '@playwright/test';
# ✅ import { test, expect } from './coverage-lib/fixture.js';

npm run test:coverage                   # Запуск с покрытием
npm run coverage:open                   # Открытие отчета

📊 Результат: Интерактивный HTML отчет с:

Общей статистикой покрытия по всем тестам
Анализом по каждой странице и тесту
Списком непокрытых элементов с селекторами
Возможностью "провалиться" в детали

📖 Подробные инструкции: docs/QUICK_START.md

🔗 Новое: MCP Integration

Model Context Protocol (MCP) обеспечивает получение структурированной информации о DOM:

📸 DOM snapshots в AI промптах для точной локализации проблем
🧪 Валидация действий через MCP browser automation
🎯 Точные селекторы на основе реальной структуры страницы

📖 Подробное руководство: docs/MCP_INTEGRATION.md

🖥️ CLI Команды (v3.2.0+)

Новая архитектура предоставляет расширенный набор команд:

# 🔍 Основные команды
node src/main.js debug              # Анализ ошибок тестов
node src/main.js debug --use-mcp    # С DOM snapshots через MCP
node src/main.js info               # Информация о системе и конфигурации
node src/main.js setup              # Интерактивная настройка проекта
node src/main.js validate           # Проверка конфигурации

# 🎯 UI Test Coverage (НОВОЕ!)
npx playwright-ai coverage init    # Настройка системы покрытия
npx playwright-ai coverage info    # Информация о покрытии

# 📊 Дополнительные опции
node src/main.js debug --verbose    # Подробный вывод
node src/main.js debug --dry-run    # Тестовый запуск без изменений
node src/main.js --help             # Справка по всем командам

# 🔄 Legacy поддержка
npx playwright-ai                   # Старый CLI через legacy слой

📚 Документация

| Руководство | Описание | |-------------|----------| | 📖 Быстрый старт | Пошаговая установка и настройка за 5 минут | | 🔌 MCP Integration | DOM snapshots и browser automation | | 🏗️ Архитектура | Clean Architecture и расширение системы | | ⚙️ Конфигурация | Все параметры и настройки | | 🆘 Решение проблем | Типичные ошибки и их исправление |

🎭 Демо проект

Для изучения всех возможностей используйте готовый демо проект:

cd DemoProject
npm install
npm run demo:full  # Полная демонстрация с AI анализом

📖 Подробности: DemoProject/README.md

🔍 Как это работает

🤖 AI Debug System:

🔍 Поиск ошибок - FileErrorRepository находит файлы с ошибками тестов
🧠 AI анализ - Strategy Pattern для выбора AI провайдера (OpenAI/Mistral/LocalAI)
🔌 MCP интеграция - получение DOM snapshots для точной диагностики
📊 Обновление отчетов - модульные репортеры встраивают решения в HTML/Allure
🎯 Умное сопоставление - алгоритм скоринга прикрепляет решения к релевантным тестам
🧩 DI управление - Dependency Injection координирует все компоненты

🎯 UI Test Coverage System:

🔧 Автоматическая настройка - npx playwright-ai coverage init копирует файлы
🕵️ Перехват взаимодействий - Playwright fixture отслеживает все page.locator(), click(), fill()
📄 Анализ страниц - извлечение всех интерактивных элементов с DOM
🎯 Сопоставление - сравнение найденных элементов с используемыми в тестах
📊 Объединенный отчет - генерация единого HTML отчета с drill-down навигацией
💡 Умные рекомендации - предложения селекторов для непокрытых элементов

🏗️ Clean Architecture (v3.2.0+)

Версия 3.2.0+ расширена UI Test Coverage System и полностью переработана с Clean Architecture для профессиональной разработки:

🏛️ Domain Layer - Rich domain entities с бизнес-логикой (TestError, AIResponse)
🎯 Application Layer - Use Cases и сервисы (AnalyzeTestErrorsUseCase, TestDebugService)
🔧 Infrastructure Layer - AI провайдеры, репортеры, MCP клиент, UI Coverage System
🖥️ Presentation Layer - CLI с командами debug, coverage, info, setup, validate
🧩 DI Container - Dependency Injection для управления зависимостями

# Новые CLI команды
node src/main.js debug --use-mcp    # Анализ ошибок с MCP
node src/main.js info               # Информация о системе
node src/main.js setup              # Интерактивная настройка
node src/main.js validate           # Проверка конфигурации

# UI Test Coverage
npx playwright-ai coverage init    # Настройка покрытия (НОВОЕ!)
npx playwright-ai coverage info    # Информация о покрытии

# Старый CLI (обратная совместимость)
npx playwright-ai                   # Работает через legacy слой

🤖 AI Провайдеры

🤖 OpenAI

// ai.conf.js
export const ai_conf = {
  api_key: 'sk-...',
  ai_server: 'https://api.openai.com/v1/chat/completions',
  model: 'gpt-4'
};

🔮 Mistral AI

// ai.conf.js
export const ai_conf = {
  api_key: 'your-mistral-key',
  ai_server: 'https://api.mistral.ai/v1/chat/completions',
  model: 'mistral-large'
};

🏠 Local AI (LM Studio, Ollama)

// ai.conf.js
export const ai_conf = {
  api_key: 'not-needed',
  ai_server: 'http://localhost:1234/v1/chat/completions',
  model: 'auto-detect'
};

📖 Подробнее: docs/ARCHITECTURE.md

📋 Пример результата

После выполнения команды в ваших HTML отчетах появится стильный блок с AI решением:

<div class="ai-debug-section">
  <h2 class="ai-debug-header">🤖 AI Debug Assistant</h2>
  <div class="ai-debug-content">
    <div class="ai-error-section">
      <div class="ai-section-title">❌ Обнаруженная ошибка</div>
      <div class="ai-error-details">Error: Timeout waiting for selector...</div>
    </div>
    <div class="ai-solution-section">
      <div class="ai-section-title">💡 Рекомендуемое решение</div>
      <div class="ai-solution-content">
        <p>Попробуйте добавить ожидание перед этим шагом...</p>
      </div>
    </div>
  </div>
</div>

⚙️ Системные требования

Node.js >= 16.0.0
Playwright проект с настроенными тестами
AI провайдер - API ключ или локальный сервер (OpenAI, Mistral, LocalAI)

🔧 Поддерживаемые форматы

Файлы ошибок

copy-prompt.txt - стандартные файлы Playwright
error-context.md - расширенный формат с контекстом
*-error.txt, *-error.md - пользовательские форматы
Автоматическое определение типа - timeout, selector, assertion, network ошибки

Отчеты

HTML отчеты Playwright с встроенными AI блоками
Allure отчеты с AI вложениями для упавших тестов
Markdown файлы с сохраненными AI ответами

🔒 Безопасность

🔐 Локальное хранение API ключей - в ai.conf.js/ai.conf.ts
🛡️ Защита приватных данных - добавьте ai.conf.* в .gitignore
⏱️ Rate limiting - автоматическое ограничение API запросов
🏠 Поддержка локальных AI - полная приватность с LocalAI/Ollama
🔍 Валидация конфигурации - проверка настроек через validate команду

🤝 Участие в разработке

Fork репозитория и клонируйте локально
Изучите архитектуру - ознакомьтесь с docs/ARCHITECTURE.md
Создайте feature branch для новой функциональности
Следуйте принципам - Clean Architecture, SOLID, DDD
Добавьте тесты - для новых Use Cases и Entity
Используйте DI контейнер - регистрируйте зависимости в bindings.js
Создайте Pull Request с описанием изменений

📄 Лицензия

MIT License - см. LICENSE файл для деталей.