Настройка TypeScript

Библиотека axe-core представляет собой мощный инструмент для автоматизированного тестирования доступности веб-приложений. Для корректной работы с TypeScript требуется не только установка основной библиотеки, но и подключение соответствующих типов, чтобы обеспечить строгую типизацию и автодополнение в редакторе.

npm install axe-core --save-dev
npm install @types/axe-core --save-dev

После установки библиотеку можно импортировать стандартным способом:

import axe from 'axe-core';

При использовании TypeScript важно учитывать, что типы позволяют строго определять структуру результатов сканирования, отчётов и конфигураций.

Конфигурация axe-core в TypeScript

Основным объектом для настройки является axe.run(), который принимает два параметра:

  1. target — элемент DOM или массив элементов, которые необходимо проверить.
  2. options — объект с настройками проверки, включая правила и контексты.

Пример типизированной конфигурации:

const options: axe.RunOptions = {
  runOnly: {
    type: 'tag',
    values: ['wcag2aa']
  },
  resultTypes: ['violations', 'incomplete'],
};

const target: HTMLElement = document.getElementById('main-content')!;

Здесь ключевое значение имеет строгая типизация параметров, позволяющая избежать ошибок на этапе компиляции.

Типы данных результатов

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

  • violations: axe.Result[] — список нарушений.
  • passes: axe.Result[] — элементы, которые соответствуют правилам.
  • incomplete: axe.Result[] — элементы с неполной проверкой.
  • inapplicable: axe.Result[] — правила, которые не применимы к текущему DOM.

Каждый объект axe.Result имеет следующие ключевые поля:

  • id: string — уникальный идентификатор правила.
  • impact: 'minor' | 'moderate' | 'serious' | 'critical' — уровень серьёзности нарушения.
  • description: string — описание правила.
  • nodes: axe.NodeResult[] — массив элементов, на которых обнаружено нарушение.

Типизация позволяет безопасно обрабатывать результаты:

axe.run(target, options).then((results: axe.AxeResults) => {
  results.violations.forEach((violation) => {
    console.log(`Нарушение: ${violation.id}, уровень: ${violation.impact}`);
  });
});

Настройка правил и тегов

axe-core поддерживает фильтрацию правил с помощью тегов. В TypeScript это реализуется через поле runOnly:

const options: axe.RunOptions = {
  runOnly: {
    type: 'tag',
    values: ['wcag2aa', 'section508']
  },
};

Также можно отключать отдельные правила:

const options: axe.RunOptions = {
  rules: {
    'color-contrast': { enabled: false },
    'label': { enabled: true },
  },
};

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

Интеграция с фреймворками

Для React, Angular или Vue важно использовать типы компонентов и элементы DOM корректно. В React пример выглядит следующим образом:

import { render } from '@testing-library/react';
import axe from 'axe-core';
import MyComponent from './MyComponent';

const { container } = render(<MyComponent />);
axe.run(container, options).then((results: axe.AxeResults) => {
  console.log(results.violations.length);
});

Использование TypeScript позволяет сразу видеть все поля container, гарантируя, что проверка будет выполнена корректно.

Расширение типов и кастомизация

Можно создавать свои интерфейсы для более строгого контроля данных:

interface CustomAxeResult extends axe.AxeResults {
  customField?: string;
}

const customResults: CustomAxeResult = await axe.run(target, options);
customResults.customField = 'Дополнительная информация';

Это полезно при интеграции с системами отчётности или собственными обработчиками ошибок.

Асинхронная обработка и типизация промисов

axe.run() возвращает промис с типом Promise<axe.AxeResults>. В TypeScript рекомендуется использовать async/await для удобного контроля ошибок и строгой типизации:

async function runAccessibilityTest(target: HTMLElement) {
  try {
    const results: axe.AxeResults = await axe.run(target, options);
    if (results.violations.length > 0) {
      results.violations.forEach(v => console.warn(v));
    }
  } catch (error) {
    console.error('Ошибка при сканировании доступности', error);
  }
}

Это позволяет полностью использовать преимущества TypeScript для предотвращения ошибок на этапе разработки и обеспечивает предсказуемость структуры данных.

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

Типизация и строгие контракты помогают безопасно подключать axe-core к пайплайнам автоматического тестирования. Например, с использованием Jest:

import axe from 'axe-core';
import { render } from '@testing-library/react';
import MyComponent from './MyComponent';

test('Доступность компонента MyComponent', async () => {
  const { container } = render(<MyComponent />);
  const results: axe.AxeResults = await axe.run(container, options);
  expect(results.violations.length).toBe(0);
});

Строгая типизация обеспечивает корректную интеграцию с любыми инструментами CI/CD и предупреждает типовые ошибки до запуска тестов.

Оглавление