Совместимость API

Библиотека Axe-core представляет собой мощный инструмент для автоматизированного тестирования доступности веб-приложений. При работе с различными версиями браузеров и фреймворков крайне важно понимать принципы совместимости её API и особенности интеграции.

Версионная совместимость

Каждое новое обновление Axe-core может включать изменения в API, что требует внимательного подхода при обновлении зависимостей. Основные моменты:

  • Стабильность основных методов: Методы axe.run, axe.configure и axe.reset сохраняют обратную совместимость в пределах минорных и патч-версий. Это означает, что обновления 4.6.2 → 4.6.5 не должны ломать существующие вызовы API.
  • Изменения в структурах данных: Объекты violations, incomplete, passes могут дополняться новыми полями. Старые поля не удаляются до мажорного обновления. Следует проверять документацию перед обращением к новым свойствам.
  • Поддержка браузеров: Axe-core тестируется на последних версиях Chrome, Firefox, Edge и Safari. Старые версии браузеров могут не поддерживать некоторые функции API, такие как асинхронные правила или современные селекторы CSS.

Интеграция с различными средами

Axe-core доступен для использования в нескольких средах, и каждая имеет свои нюансы совместимости:

  • Node.js: Использование через пакет axe-core позволяет запускать проверки без браузера, с эмуляцией DOM через библиотеки jsdom. Некоторые правила, зависящие от реального рендеринга, могут вести себя иначе.
  • Браузер: Прямое подключение скрипта через <script> поддерживает полное API, включая асинхронный вызов axe.run с кастомными конфигурациями.
  • Системы тестирования: Интеграции с Jest, Cypress и Puppeteer используют адаптеры axe-core или отдельные пакеты axe-core/jest и axe-core/cypress. Совместимость зависит от версии адаптера и основной библиотеки. Важно синхронизировать версии всех компонентов, чтобы избежать ошибок типа run is not a function.

Обновление API и обратная совместимость

При переходе между мажорными версиями библиотеки возможны следующие изменения:

  • Удаление устаревших методов: Некоторые методы конфигурации или API для старых правил могут быть удалены. Например, метод axe.configureRules устарел в пользу более гибкого axe.configure({ rules: [...] }).
  • Изменения формата отчётов: Структура объектов violation.nodes может быть расширена полями all, any, none, что требует корректного парсинга данных в существующих тестах.
  • Новые опции конфигурации: Добавление параметров, таких как runOnly.type и runOnly.values, позволяет выбирать только определённые правила для проверки. При интеграции с старым кодом необходимо проверять, что новые поля не вызывают ошибок при сериализации или передаче в CI/CD.

Особенности работы с асинхронностью

API axe.run работает асинхронно и возвращает Promise. При интеграции с различными фреймворками следует учитывать:

  • Правильное использование await или then для получения результатов.
  • В средах с синхронной обработкой DOM (например, старые тесты на Selenium) необходимо дождаться завершения асинхронного анализа перед проверкой результатов.
  • Параметры конфигурации, переданные в axe.run, не блокируют выполнение скрипта, но влияют на правила и элементы, которые будут проверены.

Совместимость с кастомными правилами

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

  • Добавление правил через axe.configure({ rules: [...] }) сохраняет обратную совместимость при добавлении новых правил, но изменения существующих могут ломать старые тесты.
  • Использование селекторов CSS должно учитывать различия в поддержке браузеров. Например, :focus-visible корректно работает в последних версиях Chrome и Firefox, но старые Edge могут игнорировать правило.
  • Ошибки в правилах могут приводить к исключениям в axe.run, поэтому рекомендуется тестировать кастомные правила отдельно перед массовым применением.

Совместимость с фреймворками

Библиотека активно используется с React, Angular и Vue. Особенности взаимодействия:

  • В React компоненты, созданные через ReactDOM.render, могут не сразу присутствовать в DOM, что требует задержки перед запуском axe.run.
  • В Angular и Vue необходимо запускать проверку после полной отрисовки компонентов (ngAfterViewInit для Angular, nextTick для Vue).
  • Использование серверного рендеринга требует проверки на Node.js с jsdom или axe-core/puppeteer.

Практические рекомендации по поддержанию совместимости

  • Использовать фиксированные версии библиотеки и адаптеров для тестовых сред.
  • Проверять документацию при переходе на новую мажорную версию.
  • Тестировать кастомные правила отдельно на всех целевых браузерах.
  • Обрабатывать новые поля отчётов через проверку существования, чтобы избежать ошибок при обновлении.

Axe-core обеспечивает гибкую и расширяемую платформу для автоматизированного тестирования доступности, но успешная интеграция требует внимательного подхода к версии API, среде исполнения и специфике используемых правил.

Оглавление