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

Библиотека Axe-core — это мощный инструмент для автоматизированного тестирования доступности веб-приложений. Одним из ключевых аспектов работы с библиотекой является правильная генерация и интерпретация отчетов о проверках. Форматы отчетов определяют, как структурируются данные о нарушениях, предупреждениях и рекомендациях, и напрямую влияют на интеграцию с другими инструментами разработки и CI/CD.

JSON

JSON является основным форматом отчетов в Axe-core. Он предоставляет структурированную информацию, удобную для программной обработки и интеграции с внешними системами. Основные элементы JSON-отчета:

  • violations – массив объектов с обнаруженными нарушениями доступности. Каждый объект содержит:

    • id – уникальный идентификатор правила (например, color-contrast);

    • impact – степень важности нарушения (minor, moderate, serious, critical);

    • description – текстовое описание проблемы;

    • help – краткая подсказка по исправлению;

    • nodes – массив элементов DOM, на которых обнаружено нарушение, с подробной информацией:

      • html – фрагмент кода элемента;
      • target – CSS-селектор или XPath к элементу;
      • failureSummary – детальное объяснение, почему элемент не соответствует правилу.

  • passes – массив проверок, которые пройдены успешно, с аналогичной структурой.

  • incomplete – проверки, результат которых не может быть определен автоматически.

  • testEngine – сведения о версии Axe-core и среде выполнения.

JSON-формат идеально подходит для интеграции с инструментами CI/CD, генерации визуальных отчетов и аналитики.

HTML

HTML-отчеты представляют данные в визуально удобном виде для веб-браузеров. Основные особенности:

  • Содержат таблицы с группировкой по нарушениям, где каждая строка описывает элемент и тип проблемы.
  • Возможна цветовая маркировка по уровню серьёзности (critical – красный, serious – оранжевый, moderate – жёлтый, minor – синий).
  • Часто используют интерактивные элементы, такие как раскрывающиеся списки для подробной информации по каждому DOM-узлу.
  • HTML-отчёты создаются через сторонние обёртки над Axe-core (например, axe-reports) или через скриптовую генерацию с использованием данных JSON.

HTML-формат удобен для презентации результатов заказчику или команде без необходимости углубляться в JSON.

CSV

Формат CSV предназначен для экспорта нарушений в табличные редакторы или системы аналитики. Особенности:

  • Каждая строка соответствует конкретному нарушению или элементу, на котором оно обнаружено.

  • Основные колонки:

    • Rule ID
    • Impact
    • Description
    • HTML snippet
    • Selector

  • CSV-отчеты удобны для массового анализа и последующего объединения с другими метриками проекта.

SARIF

SARIF (Static Analysis Results Interchange Format) — стандартный формат для интеграции с системами анализа кода и CI/CD. Особенности применения в Axe-core:

  • Позволяет интегрировать результаты проверок доступности в существующие пайплайны анализа кода, например, GitHub Actions или Azure DevOps.
  • SARIF поддерживает структурированные уведомления об ошибках, с указанием местоположения в коде, уровня серьёзности и уникального идентификатора правила.
  • Позволяет автоматически генерировать встроенные отчеты и предупреждения в IDE, облегчая исправление нарушений разработчиками.

Конфигурация формата

Для генерации различных форматов отчётов Axe-core предоставляет возможность настройки через API:

const { AxePuppeteer } = require('axe-puppeteer');
const fs = require('fs');

const results = await new AxePuppeteer(page).analyze();

fs.writeFileSync('report.json', JSON.stringify(results, null, 2));
  • Для HTML и CSV чаще используют конвертацию из JSON через сторонние библиотеки.
  • При использовании SARIF применяется специализированный конвертер, который преобразует объекты violations в структуру SARIF с указанием locations, ruleId и level.

Ключевые рекомендации по выбору формата

  • JSON — универсальный и основной для интеграций и программной обработки.
  • HTML — для визуального представления результатов и отчётности.
  • CSV — для аналитики и экспорта в таблицы.
  • SARIF — для интеграции с системами статического анализа и CI/CD.

Использование правильного формата отчёта позволяет не только фиксировать нарушения доступности, но и выстраивать процессы автоматической проверки и исправления проблем, повышая качество веб-приложений.

Оглавление