CSV reporter

Библиотека Axe-core — это инструмент для автоматизированного тестирования доступности веб-приложений. Для работы с ней в JavaScript проекте используется пакет axe-core, который устанавливается через npm:

npm install axe-core

После установки библиотеку можно подключить как через require, так и через import:

const axe = require('axe-core');
// или
import axe from 'axe-core';

Для интеграции с браузером часто используется подключение скрипта напрямую:

<script src="node_modules/axe-core/axe.min.js"></script>

Основы работы с Axe-core

Основная функция библиотеки — анализ DOM на предмет нарушений доступности. Стандартный сценарий включает:

  1. Инициализацию Axe.
  2. Запуск сканирования на конкретной странице или элементе.
  3. Получение отчета с описанием нарушений.

Пример базового использования:

axe.run(document, {}, (err, results) => {
    if (err) throw err;
    console.log(results.violations);
});
  • document — объект DOM, на котором проводится проверка.
  • results.violations — массив с обнаруженными нарушениями.

Форматы отчетов

Axe-core поддерживает несколько форматов отчетов:

  • JSON — основной структурированный формат.
  • HTML — визуальный отчет для анализа.
  • CSV — удобный формат для интеграции с другими инструментами и аналитики.

Для генерации CSV отчета используется отдельный модуль или кастомная функция конвертации JSON в CSV. Каждое нарушение включает следующие поля:

  • id — уникальный идентификатор правила.
  • impact — уровень влияния (critical, serious, moderate, minor).
  • description — описание правила.
  • help — рекомендации по исправлению.
  • nodes — список элементов DOM, где выявлено нарушение.
  • html — фрагмент HTML с проблемным элементом.

CSV Reporter

CSV Reporter — это компонент, преобразующий результаты Axe-core в CSV-формат для дальнейшей аналитики. Обычно он используется для:

  • Массовой отчетности о тестировании доступности.
  • Интеграции с системами CI/CD.
  • Автоматического отслеживания динамических изменений интерфейса.

Принципы работы

  1. Получение данных: Axe-core возвращает объект JSON с полями violations, passes, incomplete, inapplicable.
  2. Фильтрация: Обычно CSV содержит только нарушения (violations), исключая пройденные проверки.
  3. Структурирование: Каждое нарушение превращается в строку CSV с набором стандартных колонок.
  4. Экранирование: Для корректной работы с CSV все поля, содержащие запятые или переносы строк, заключаются в кавычки.
  5. Сохранение: Генерация CSV файла происходит через стандартные Node.js модули fs или через браузерные функции сохранения файлов.

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

function convertViolationsToCSV(violations) {
    const headers = ['id', 'impact', 'description', 'help', 'html'];
    const rows = violations.map(v => {
        const nodesHtml = v.nodes.map(n => n.html).join('; ');
        return [
            v.id,
            v.impact,
            v.description.replace(/[\n\r]/g, ' '),
            v.help.replace(/[\n\r]/g, ' '),
            nodesHtml.replace(/[\n\r]/g, ' ')
        ].map(field => `"${field}"`).join(',');
    });
    return [headers.join(','), ...rows].join('\n');
}
  • Каждое поле заключено в кавычки для избежания ошибок при наличии запятых.
  • Фрагменты HTML всех проблемных элементов объединяются через точку с запятой.

Интеграция с Node.js

Сохранение CSV в файл:

const fs = require('fs');

axe.run(document, {}, (err, results) => {
    if (err) throw err;
    const csvContent = convertViolationsToCSV(results.violations);
    fs.writeFileSync('axe-report.csv', csvContent);
});

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

CSV Reporter удобен для систем автоматического тестирования:

  • Jenkins, GitLab CI, GitHub Actions — CSV файл можно хранить как артефакт сборки.
  • Анализ трендов — с помощью CSV легко строить отчеты об улучшении доступности во времени.
  • Автоматическое уведомление — при обнаружении критических нарушений можно триггерить уведомления.

Пример скрипта для CI:

{
  "scripts": {
    "axe-ci": "node axe-csv.js"
  }
}

Где axe-csv.js содержит полный цикл: запуск Axe, генерация CSV, сохранение файла.

Продвинутые возможности

  • Фильтрация по уровню важности: можно сохранять только critical и serious нарушения.
  • Построение агрегированных отчетов: объединение нескольких CSV в один для большого проекта.
  • Сортировка по элементам DOM: упрощает поиск повторяющихся проблем.

Пример фильтрации:

const criticalViolations = results.violations.filter(v => v.impact === 'critical');
const csvCritical = convertViolationsToCSV(criticalViolations);

Особенности работы с динамическими страницами

Для SPA (Single Page Application) рекомендуется:

  • Запуск Axe после полной отрисовки контента.
  • Повторный запуск при изменении DOM.
  • Использование селекторов для конкретных компонентов, чтобы не генерировать чрезмерно большой CSV.
const container = document.querySelector('#app');
axe.run(container, {}, (err, results) => {
    if (err) throw err;
    const csv = convertViolationsToCSV(results.violations);
    console.log(csv);
});

Поддержка больших проектов

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

  • Разделять сканирование по страницам или модулям.
  • Генерировать отдельные CSV для каждого модуля.
  • Использовать скрипты объединения CSV в финальный отчет с аналитикой по всем компонентам.

Такой подход позволяет поддерживать отчеты актуальными и легко интегрировать их в процессы тестирования и улучшения доступности.

Оглавление