Breaking changes

Axe-core — это мощная библиотека для автоматического тестирования доступности веб-приложений. С каждым крупным релизом появляются изменения, которые могут нарушить существующую интеграцию и поведение тестов. Раздел breaking changes посвящён анализу таких изменений, их причинам и методам адаптации.

1. Изменения API

Старые методы и свойства могут быть удалены или изменены. Например, методы для конфигурации проверок могут быть переименованы или иметь другую сигнатуру:

// Старый способ
axe.run(document, { runOnly: ['color-contrast'] });

// Новый способ (после v4.0)
axe.run(document, {
  rules: {
    'color-contrast': { enabled: true }
  }
});

Ключевые моменты:

  • runOnly заменён на rules с объектной конфигурацией.
  • Встроенные наборы правил могут быть изменены. Некоторые устаревшие правила удаляются.
  • Рекомендуется внимательно изучать CHANGELOG перед обновлением.

2. Модификация схем данных результатов

Формат возвращаемого объекта results иногда меняется:

// Старый формат
{
  violations: [
    {
      id: "color-contrast",
      impact: "serious",
      nodes: [...]
    }
  ]
}

// Новый формат
{
  violations: [
    {
      ruleId: "color-contrast",
      impact: "serious",
      nodes: [...]
    }
  ]
}

Изменения могут включать:

  • Переименование ключей (id → ruleId).
  • Перестановку или удаление полей (helpUrl может быть перемещён в другой объект).
  • Новый формат объектов nodes, который влияет на парсинг деталей ошибки.

3. Изменения в поведении правил

Правила проверки могут быть уточнены или изменены логикой, что приводит к различным результатам при тех же тестах:

  • Color contrast: пересмотр порогов контрастности.
  • ARIA roles: новые требования к допустимым атрибутам и их вложенности.
  • Form labels: строгая проверка наличия label или aria-label для всех интерактивных элементов.

Это важно, так как обновление библиотеки может привести к появлению новых нарушений в существующем проекте.

4. Изменения способов интеграции

С интеграциями в тестовые фреймворки тоже возможны изменения:

  • В Jest и Mocha часто требуется обновление адаптеров.
  • Методы типа axe.configure() могут изменять конфигурацию глобально или локально, что влияет на существующие тестовые сценарии.
  • Асинхронность методов может быть изменена: старый синхронный код нужно переписать с использованием async/await.

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

import axe from 'axe-core';

(async () => {
  const results = await axe.run(document, {
    rules: {
      'color-contrast': { enabled: true }
    }
  });
  console.log(results.violations);
})();

5. Обновления правил и удаление устаревших

Некоторые правила могут быть полностью удалены из библиотеки. Их использование после обновления приведёт к ошибкам:

  • Необходимо проверять актуальный список правил (axe.getRules()).
  • Старые правила рекомендуется заменять на новые эквиваленты.
  • Обновления могут быть вызваны изменениями в спецификациях WCAG или лучшими практиками доступности.

6. Рекомендации по миграции

  • Всегда читать CHANGELOG перед обновлением.
  • Проверять тесты после апгрейда, чтобы убедиться в корректности результатов.
  • Адаптировать код под новые форматы объектов и сигнатуры методов.
  • Использовать обёртки для старых методов, если требуется плавная миграция.
  • Внимательно отслеживать удалённые правила и переименованные ключи.

7. Влияние на CI/CD и автоматизацию

Breaking changes могут нарушить автоматические проверки доступности в пайплайнах:

  • Сценарии, ожидающие конкретные ключи в объекте results, могут падать.
  • Необходимо обновлять скрипты и отчётность в соответствии с новым форматом.
  • Желательно фиксировать версию библиотеки в package.json, чтобы исключить неожиданное появление новых breaking changes при сборках.

8. Совместимость с браузерами и средами выполнения

Некоторые изменения могут быть связаны с движками браузеров:

  • Новые проверки могут использовать современные API DOM, недоступные в устаревших браузерах.
  • Breaking changes иногда включают удаление поддержки старых версий Node.js или браузеров.
  • Тесты, работающие локально, могут вести себя иначе на CI при обновлении axe-core.

9. Инструменты для управления breaking changes

  • axe-core changelog — основной источник информации о изменениях.
  • axe-core rules documentation — для проверки актуальных правил.
  • linting и адаптеры — позволяют выявить несоответствия до обновления.

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

Оглавление