Полная профессиональная документация по системе тестирования Battery Wizard API v2

Содержание

1. Введение
2. Часть I: Руководство для обычного пользователя
3. Часть II: Руководство для разработчика
4. Часть III: Руководство для администратора
5. Глоссарий
- Термины и определения

1. Введение

1.1. Назначение системы

Система тестирования Battery Wizard API v2 представляет собой комплексное решение для автоматизированного тестирования REST API с расширенными возможностями отладки, безопасностного тестирования и детальной отчетности. Система предназначена для обеспечения качества работы API и выявления потенциальных уязвимостей.

1.2. Ключевые возможности

✅ Комплексное тестирование всех конечных точек API
🔒 Встроенное безопасностное тестирование (SQL injection, XSS, etc.)
📊 Детальная отчетность с визуализацией результатов
🐛 Расширенная отладка с полным логированием запросов/ответов
🎨 Профессиональный UI с интерактивными элементами
📁 Модульная архитектура для легкого расширения
⚡ Автоматическое обнаружение новых тестов

1.3. Технический стек

Backend: PHP 8.3 с строгой типизацией
Frontend: Bootstrap 5.3, Highlight.js
Архитектура: Модульная с автозагрузкой классов
Безопасность: Валидация входных данных, санитизация
Логирование: Структурированное многоуровневое логирование

2. Часть I: Руководство для обычного пользователя

2.1. Быстрый старт

2.1.1. Первый запуск системы

Откройте браузер и перейдите по адресу системы тестирования
На главной странице вы увидите обзор возможностей системы
Нажмите кнопку «Run All Tests» для запуска полного тестирования
Дождитесь завершения выполнения тестов (обычно 1-3 минуты)
Просмотрите результаты в интерактивном отчете

2.1.2. Интерпретация результатов тестирования

Статусы тестов:

🟢 PASSED — Тест выполнен успешно, функциональность работает корректно
🔴 FAILED — Обнаружена проблема, требуется внимание разработчика
🟡 SKIPPED — Тест пропущен (обычно из-за отсутствия предварительных условий)
🔵 RUNNING — Тест выполняется в данный момент

Метрики качества:

Success Rate — Общий процент успешно пройденных тестов
Duration — Общее время выполнения тестовой сессии
Memory Usage — Потребление памяти системой тестирования

2.2. Основные функции интерфейса

2.2.1. Панель управления

Основные кнопки:

«Run All Tests» — Запуск полного набора тестов
«Security Tests Only» — Запуск только безопасностных тестов
«JSON Output» — Открытие результатов в формате JSON
«Refresh» — Обновление страницы

2.2.2. Навигация по результатам

Фильтрация тестов:

<!-- В интерфейсе доступны фильтры: -->
- Show All (все тесты)
- Passed Only (только успешные)
- Failed Only (только неудачные)
- Skipped Only (только пропущенные)

Группировка тестов:

Environment Tests (тесты окружения)
Authentication Tests (тесты аутентификации)
Battery Operations (операции с батареями)
User Management (управление пользователями)
File Operations (файловые операции)
Security Tests (тесты безопасности)

2.2.3. Просмотр детальной информации

Для неудачных тестов доступно:

Детали HTTP запроса и ответа
Логи выполнения
Информация об окружении
Рекомендации по устранению проблем

2.3. Режимы работы

2.3.1. Стандартный режим тестирования

Включает все основные тесты функциональности API:

Проверка доступности API
Тестирование аутентификации
Операции с данными батарей
Управление пользовательскими профилями
Файловые операции

2.3.2. Режим безопасностного тестирования

Специализированные тесты на уязвимости:

SQL Injection protection
XSS prevention
Input validation
Authentication bypass attempts

⚠️ Внимание: Безопасностные тесты могут вызывать срабатывание систем защиты. Используйте с осторожностью в production-окружении.

2.3.3. JSON режим

Предоставляет результаты в машиночитаемом формате для:

Интеграции с CI/CD системами
Автоматической обработки результатов
Создания custom отчетов

2.4. Понимание отчетов

2.4.1. Структура отчета

Верхний уровень:

Test Results
├── Summary Cards (карточки сводки)
├── Progress Bar (прогресс выполнения)
├── Test Groups (группы тестов)
└── Debug Information (отладочная информация)

2.4.2. Ключевые метрики

Success Rate Calculation:

Success Rate = (Passed Tests / Total Tests) × 100%

Пример интерпретации:

95-100% — Отличное состояние системы
85-94% — Хорошее состояние, требуются minor исправления
70-84% — Требуется внимание, возможны серьезные проблемы
<70% — Критическое состояние, требуется немедленное вмешательство

2.4.3. Анализ неудачных тестов

Типичные сценарии:

Authentication Failed — Проблемы с учетными данными
API Unreachable — Сервер недоступен
Database Connection Issues — Проблемы с БД
File Upload Failures — Ошибки загрузки файлов
Security Vulnerabilities — Обнаружены уязвимости

2.5. Рекомендации по использованию

2.5.1. Регулярное тестирование

Ежедневно — Основные функциональные тесты
Еженедельно — Полный набор тестов включая безопасность
После обновлений — Обязательная проверка всех функций

2.5.2. Действия при обнаружении проблем

Зафиксируйте время обнаружения проблемы
Соберите полную информацию из раздела debug
Уведомите команду разработки
Повторите тест после исправления

3. Часть II: Руководство для разработчика

3.1. Архитектура системы

3.1.1. Обзор архитектуры

src/
├── Core/                 # Ядро системы
│   ├── TestCase.php     # Базовый класс теста
│   ├── TestRunner.php   # Оркестратор тестов
│   ├── TemplateEngine.php # Движок шаблонов
│   └── DebugLogger.php  # Система логирования
├── Tests/               # Функциональные тесты
│   ├── EnvironmentTest.php
│   ├── AuthenticationTest.php
│   ├── BatteryTest.php
│   ├── UserTest.php
│   └── FileTest.php
├── Tests/Security/      # Безопасностные тесты
│   ├── SQLInjectionTest.php
│   └── XSSProtectionTest.php
└── Utils/               # Вспомогательные классы
    ├── HttpClient.php
    └── FileManager.php

3.1.2. Принципы проектирования

SOLID принципы:

Single Responsibility — Каждый класс имеет одну ответственность
Open/Closed — Классы открыты для расширения, закрыты для изменений
Liskov Substitution — Наследники могут заменять родительские классы
Interface Segregation — Специализированные интерфейсы
Dependency Inversion — Зависимости от абстракций

3.2. Создание новых тестов

3.2.1. Структура тестового класса

<?php
declare(strict_types=1);

namespace BatteryWizard\Tests;

use BatteryWizard\Core\TestCase;

class NewFeatureTest extends TestCase 
{
    public function __construct() 
    {
        parent::__construct('Descriptive Test Name');
    }

    public function run(): void 
    {
        try {
            // Подготовка тестовых данных
            $this->log("Starting test preparation");

            // Выполнение тестовых действий
            $testData = $this->getTestData();
            $httpClient = $testData['http_client'];

            // Assertions и валидация
            if ($this->validateResponse($response)) {
                $this->setStatus('PASSED', 'Test completed successfully');
            } else {
                $this->setStatus('FAILED', 'Validation failed');
            }

        } catch (\Throwable $e) {
            $this->setStatus('FAILED', 'Test crashed: ' . $e->getMessage());
            $this->addDebugInfo('exception', [
                'message' => $e->getMessage(),
                'trace' => $e->getTraceAsString()
            ]);
        }
    }

    private function validateResponse(array $response): bool 
    {
        // Логика валидации
        return $response['success'] === true;
    }
}

3.2.2. Доступные методы базового класса

Управление статусом:

$this->setStatus('PASSED', 'Success message');
$this->setStatus('FAILED', 'Error description');

Логирование:

$this->log("Informational message");
$this->log("Warning message", 'WARNING');
$this->log("Error message", 'ERROR');

Отладка:

$this->addDebugInfo('context_name', $debugData);

Assertions:

$this->assertTrue($condition, "Condition should be true");
$this->assertFalse($condition, "Condition should be false");
$this->assertEquals($expected, $actual, "Values should be equal");
$this->validateResponse($response, $expectedStructure);

3.2.3. Работа с HTTP клиентом

Базовые запросы:

$response = $httpClient->makeRequest(
    'endpoint.php',    // URL endpoint
    'GET',             // HTTP метод
    ['param' => 'value'], // Данные запроса
    false              // multipart/form-data
);

Аутентифицированные запросы:

// Токен устанавливается автоматически после аутентификации
$httpClient->setAuthToken($token);
$profileResponse = $httpClient->makeRequest('user.php', 'GET');

Загрузка файлов:

$postData = [
    'file' => new \CURLFile($filePath, $mimeType, $fileName),
    'filename' => $fileName
];

$uploadResponse = $httpClient->makeRequest(
    'upload.php', 
    'POST', 
    $postData, 
    true  // multipart = true
);

3.3. Расширение функциональности

3.3.1. Создание безопасностных тестов

Структура security теста:

<?php
declare(strict_types=1);

namespace BatteryWizard\Tests\Security;

use BatteryWizard\Core\TestCase;

class NewVulnerabilityTest extends TestCase 
{
    public function __construct() 
    {
        parent::__construct('Security: New Vulnerability Check');
    }

    public function run(): void 
    {
        $payloads = $this->generateMaliciousPayloads();
        $vulnerabilities = [];

        foreach ($payloads as $payload) {
            if ($this->testVulnerability($payload)) {
                $vulnerabilities[] = $payload;
            }
        }

        if (empty($vulnerabilities)) {
            $this->setStatus('PASSED', 'No vulnerabilities detected');
        } else {
            $this->setStatus('FAILED', 
                'Vulnerabilities found: ' . count($vulnerabilities)
            );
        }
    }

    private function generateMaliciousPayloads(): array 
    {
        return [
            // Специфичные payloads для тестируемой уязвимости
        ];
    }
}

3.3.2. Интеграция с TemplateEngine

Добавление пользовательских фильтров:

$templateEngine->addFilter('custom_format', function($value, $param) {
    return "Formatted: {$value} with {$param}";
});

$templateEngine->addFunction('get_config', function($key) {
    return Config::get($key);
});

Использование в шаблонах:

<!-- Базовые переменные -->
%{variable_name}

<!-- С фильтрами -->
%{variable_name.upper}
%{variable_name.round:2}
%{variable_name.date:Y-m-d H:i:s}

<!-- Вычисления -->
%{Calculate: (test_count / total_count) * 100. Round: 1}%

<!-- Пользовательские фильтры -->
%{value.custom_format:param}

3.4. Best Practices разработки

3.4.1. Code Style и стандарты

PHP Code Standards:

PSR-12 coding style
Strict types declaration
Type hints для всех методов
DocBlock комментарии для публичных методов

Пример документации:

/**
 * Выполняет тестирование конкретной функциональности API
 * 
 * @param array $testData Данные для тестирования
 * @return bool Результат выполнения теста
 * @throws TestException В случае критической ошибки
 */
private function executeFeatureTest(array $testData): bool 
{
    // Реализация
}

3.4.2. Обработка ошибок и исключений

Структурированная обработка:

public function run(): void 
{
    try {
        // Основная логика теста

    } catch (NetworkException $e) {
        $this->setStatus('FAILED', 'Network error: ' . $e->getMessage());
        $this->addDebugInfo('network_error', [
            'exception' => $e->getMessage(),
            'connection_details' => $this->getConnectionInfo()
        ]);

    } catch (ValidationException $e) {
        $this->setStatus('FAILED', 'Validation failed');
        $this->addDebugInfo('validation_error', $e->getDetails());

    } catch (\Throwable $e) {
        $this->setStatus('FAILED', 'Unexpected error: ' . $e->getMessage());
        $this->log("Unexpected exception: " . $e->getTraceAsString(), 'ERROR');
    }
}

3.4.3. Тестирование производительности

Методы измерения:

$startTime = microtime(true);
// Выполнение операции
$duration = microtime(true) - $startTime;

if ($duration > $maxAllowedTime) {
    $this->log("Performance warning: Operation took {$duration}s", 'WARNING');
}

Мониторинг памяти:

$memoryBefore = memory_get_usage(true);
// Операция
$memoryAfter = memory_get_usage(true);
$memoryUsed = $memoryAfter - $memoryBefore;

$this->addDebugInfo('memory_usage', [
    'before' => $memoryBefore,
    'after' => $memoryAfter,
    'used' => $memoryUsed
]);

3.5. Интеграция с CI/CD

3.5.1. Автоматическое выполнение тестов

Пример GitHub Actions:

name: API Tests
on: [push, pull_request]

jobs:
  api-testing:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Run API Tests
        run: |
          curl -X POST "https://api.batterywizard.ru/api/v2/public/index.php?action=run_tests&output=json"

      - name: Parse Results
        run: |
          # Парсинг JSON результатов
          # Уведомление при неудачных тестах

3.5.2. Кастомизация отчетов

Создание custom форматов:

class CustomReportGenerator 
{
    public function generateJUnitReport(array $testResults): string 
    {
        // Генерация JUnit XML для Jenkins
    }

    public function generateSlackNotification(array $summary): array 
    {
        // Формирование уведомления для Slack
    }
}

4. Часть III: Руководство для администратора

4.1. Установка и развертывание

4.1.1. Системные требования

Минимальные требования:

PHP 8.0 или выше
Расширения: curl, json, mbstring, session
256MB RAM минимум
100MB свободного места на диске

Рекомендуемые требования:

PHP 8.3 с OPcache
512MB RAM
SSD хранилище
Современный веб-сервер (nginx/apache)

4.1.2. Процесс установки

Шаг 1: Подготовка окружения

# Проверка версии PHP
php --version

# Проверка необходимых расширений
php -m | grep -E '(curl|json|mbstring)'

Шаг 2: Развертывание кода

# Клонирование или копирование файлов
cp -r battery-wizard-tests /var/www/html/api-tests/

# Настройка прав доступа
chown -R www-data:www-data /var/www/html/api-tests/
chmod -R 755 /var/www/html/api-tests/public/
chmod -R 777 /var/www/html/api-tests/log/

Шаг 3: Конфигурация веб-сервера

nginx конфигурация:

server {
    listen 80;
    server_name api-tests.yourdomain.com;
    root /var/www/html/api-tests/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # Защита от прямого доступа к敏感льным файлам
    location ~ /(src|templates|autoload\.php) {
        deny all;
        return 404;
    }
}

4.1.3. Настройка безопасности

Ограничение доступа:

// В public/index.php добавить:
$allowed_ips = ['192.168.1.0/24', '10.0.0.0/8'];
if (!in_array($_SERVER['REMOTE_ADDR'], $allowed_ips)) {
    http_response_code(403);
    die('Access denied');
}

Настройка HTTPS:

# Получение SSL сертификата
certbot --nginx -d api-tests.yourdomain.com

4.2. Конфигурация системы

4.2.1. Параметры конфигурации

Основные настройки (src/Core/TestRunner.php):

private const CONFIG = [
    'api_base_url' => 'https://api.batterywizard.ru/api/v2/',
    'timeout' => 30,
    'max_memory' => '256M',
    'test_credentials' => [
        'username' => 'test_v2',
        'password' => ''
    ]
];

Настройки логирования (src/Core/DebugLogger.php):

private $logConfig = [
    'max_file_size' => '10M',
    'retention_days' => 30,
    'log_level' => 'DEBUG', // DEBUG, INFO, WARNING, ERROR
    'compress_old_logs' => true
];

4.2.2. Настройка тестовых данных

Тестовые батареи (src/Tests/BatteryTest.php):

private const TEST_BATTERIES = [
    [
        'manufacturer' => 'DELTA',
        'model' => 'FTS',
        'search_queries' => ['DELTA FTS', 'FTS', 'DELTA'],
        'expected_capacity' => 50,
        'expected_voltage' => 12
    ]
    // Добавление новых тестовых батарей
];

4.3. Мониторинг и обслуживание

4.3.1. Мониторинг производительности

Ключевые метрики для мониторинга:

Время выполнения тестовой сессии
Потребление памяти
Количество неудачных тестов
Размер лог-файлов

Настройка alerting:

#!/bin/bash
# check_api_tests.sh - мониторинг состояния тестов

CURRENT_STATUS=$(curl -s "https://api-tests.yourdomain.com/?output=json" | jq '.summary.success_rate')

if [ "$CURRENT_STATUS" -lt 90 ]; then
    echo "ALERT: API Test success rate dropped to ${CURRENT_STATUS}%"
    # Отправка уведомления
fi

4.3.2. Управление лог-файлами

Ротация логов:

# /etc/logrotate.d/api-tests
/var/www/html/api-tests/log/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 644 www-data www-data
}

Очистка старых сессий:

// Скрипт очистки (cleanup_sessions.php)
$sessionDirs = glob('/var/www/html/api-tests/log/test_session_*');
$now = time();

foreach ($sessionDirs as $dir) {
    if ($now - filemtime($dir) > 86400 * 7) { // 7 дней
        removeDirectory($dir);
    }
}

4.4. Безопасность и контроль доступа

4.4.1. Харденинг системы

Защита конфигурационных файлов:

# .htaccess защита
<Files "*.php">
    Order Allow,Deny
    Deny from all
</Files>

<Files "index.php">
    Order Allow,Deny
    Allow from all
</Files>

Настройка PHP security:

; php.ini настройки
expose_php = Off
display_errors = Off
log_errors = On
allow_url_fopen = Off
allow_url_include = Off

4.4.2. Аудит безопасности

Регулярные проверки:

Review логов доступа — Поиск подозрительных активностей
Проверка прав доступа — Валидация файловых permissions
Обновление зависимостей — Регулярное обновление PHP и расширений
Сканирование уязвимостей — Использование security scanners

4.5. Резервное копирование и восстановление

4.5.1. Стратегия бэкапов

Критические данные для бэкапа:

/var/www/html/api-tests/
├── src/                    # Исходный код
├── templates/              # Шаблоны
├── log/                   # Логи (опционально)
└── config/                # Конфигурационные файлы

Скрипт резервного копирования:

#!/bin/bash
# backup_api_tests.sh

BACKUP_DIR="/backup/api-tests"
DATE=$(date +%Y%m%d_%H%M%S)

tar -czf "$BACKUP_DIR/api-tests_$DATE.tar.gz" \
  --exclude="log/*" \
  /var/www/html/api-tests/

# Ротация бэкапов (храним 30 дней)
find "$BACKUP_DIR" -name "api-tests_*.tar.gz" -mtime +30 -delete

4.5.2. Процедура восстановления

Восстановление из бэкапа:

# Остановка сервисов
systemctl stop nginx php8.3-fpm

# Восстановление файлов
tar -xzf /backup/api-tests/api-tests_20241201_120000.tar.gz -C /

# Настройка прав
chown -R www-data:www-data /var/www/html/api-tests/

# Запуск сервисов
systemctl start nginx php8.3-fpm

# Проверка работоспособности
curl -I https://api-tests.yourdomain.com/

4.6. Troubleshooting

4.6.1. Распространенные проблемы

Проблема: Тесты не запускаются

# Диагностика:
1. Проверить логи ошибок PHP: tail -f /var/log/php/error.log
2. Проверить доступность API: curl -v https://api.batterywizard.ru/api/v2/config.php
3. Проверить права доступа: ls -la /var/www/html/api-tests/public/

Проблема: Высокое потребление памяти

// В src/Core/TestRunner.php уменьшить:
private const MEMORY_LIMIT = '128M'; // вместо 256M

// Или в php.ini:
memory_limit = 256M

Проблема: Долгое выполнение тестов

// Увеличить таймауты в src/Utils/HttpClient.php:
curl_setopt_array($ch, [
    CURLOPT_TIMEOUT => 60, // вместо 30
    CURLOPT_CONNECTTIMEOUT => 10
]);

4.6.2. Инструменты диагностики

Health check скрипт:

// health_check.php
$checks = [
    'php_version' => version_compare(PHP_VERSION, '8.0.0', '>='),
    'extensions' => [
        'curl' => extension_loaded('curl'),
        'json' => extension_loaded('json'),
        'mbstring' => extension_loaded('mbstring')
    ],
    'write_permissions' => is_writable('/var/www/html/api-tests/log/'),
    'api_connectivity' => checkApiConnectivity()
];

header('Content-Type: application/json');
echo json_encode($checks, JSON_PRETTY_PRINT);

5. Глоссарий

Термины и определения

API (Application Programming Interface)^[1.1]
Набор определений и протоколов для взаимодействия между программными компонентами.

Assertion^[3.2.2]
Проверка условия в тесте, которая определяет успешность или неудачу тестового сценария.

Authentication^[2.3.1]
Процесс проверки подлинности пользователя или системы.

CI/CD (Continuous Integration/Continuous Deployment)^[3.5]
Методология разработки, предполагающая частую интеграцию кода и автоматическое развертывание.

Debugging^[2.4.3]
Процесс выявления и устранения ошибок в программном обеспечении.

Endpoint^[3.2.3]
URL-адрес API, который принимает запросы и возвращает responses.

HTTP Status Code^[2.4.3]
Трехзначный код, указывающий на результат обработки HTTP запроса.

JSON (JavaScript Object Notation)^[2.3.3]
Текстовый формат обмена данными, основанный на синтаксисе JavaScript.

Logging^[4.3.2]
Процесс записи информации о работе системы для последующего анализа.

Multipart Request^[3.2.3]
HTTP запрос, содержащий несколько частей данных, часто используется для загрузки файлов.

Payload^[3.3.1]
Данные, передаваемые в запросе, особенно в контексте безопасностного тестирования.

SQL Injection^[2.3.2]
Тип уязвимости, позволяющий злоумышленнику выполнять произвольные SQL команды.

Template Engine^[3.3.2]
Система для разделения логики приложения и представления данных.

Test Case^[3.2.1]
Отдельный тест, проверяющий конкретную функциональность системы.

Test Runner^[3.1.1]
Программа или фреймворк, который выполняет тесты и собирает результаты.

Validation^[3.2.1]
Процесс проверки данных на соответствие определенным критериям.

XSS (Cross-Site Scripting)^[2.3.2]
Тип уязвимости, позволяющий внедрять malicious скрипты в веб-страницы.

YAML (YAML Ain’t Markup Language)^[3.5.1]
Человеко-читаемый формат данных, часто используемый для конфигурационных файлов.

Документация обновлена: 25 октября 2025
Версия системы: 2.2.0
Поддержка: md@conbat.ru