Référence API

Ce guide de référence décrit les API fournies par le package (également appelé @axe-core/watcher axe Watcher *ou simplement * Watcher ).

AxeConfiguration Interface

La axe propriété (un paramètre passé aux fonctions de configuration) est le moyen habituel de modifier votre AxeConfiguration pour configurer les tests d'accessibilité avec axe Watcher. Les propriétés suivantes sont contenues dans AxeConfiguration :

apiKey

La apiKey valeur est la seule propriété qui doit être définie dans votre AxeConfiguration. Vous pouvez obtenir sa valeur à partir de la page Projets. Voir Gestion des projets pour plus d'informations.

autoAnalyze

Définissez cette valeur sur false pour empêcher l'analyse automatique des pages. Pour plus d'informations sur le mode manuel, voir Contrôle du moment de l'analyse des pages.

buildID

La propriété facultative buildID , lorsqu'elle n'est pas définie null, permet aux outils d'exécution de tests parallèles de générer des résultats qui apparaissent comme une seule exécution de test dans axe Developer Hub. Dans le cas d'exécutions de tests parallèles, chaque outil d'exécution de tests doit partager la même chaîne non nulle, ce qui oblige chaque exécution de tests à concaténer ses résultats avec les résultats existants pour le même SHA de commit Git. buildID buildID Cependant, lorsque buildID est null, plusieurs exécutions de tests écrasent les résultats existants qui ont le même SHA de commit Git.

Vous pouvez généralement obtenir une valeur utilisable auprès de votre fournisseur d'intégration continue. buildID Par exemple, vous pouvez utiliser ces valeurs :

• github.run_id

  Disponible dans les workflows GitHub. Consultez github context dans la documentation GitHub pour plus d'informations.

• CIRCLE_PIPELINE_ID

  Avec CircleCI, la valeur ci-dessus est disponible à partir de l'environnement de votre processus. Consultez Variables d'environnement intégrées dans la documentation CircleCI pour plus d'informations.

  Autres variables d'environnement d'intégration continue que vous pouvez utiliser pour buildID :

  Fournisseur	Variable d'environnement
  Bitbucket	BITBUCKET_BUILD_NUMBER
  GitLab	CI_PIPELINE_ID
  Jenkins	BUILD_NUMBER

configurationOverrides

(Facultatif) Remplace les valeurs définies dans la configuration globale. Consultez l'Interface ConfigurationOverrides pour plus d'informations.

excludeUrlPatterns

(Facultatif) Empêche toute URL correspondant à l'un des modèles minimatch du tableau excludeUrlPatterns d'être analysée.

axe: {
  excludeUrlPatterns: [ 'https://*.example.com/**', 'https://example.org/**' ]
}

Exemples

runContext

(Facultatif) Vous permet de choisir les éléments à inclure et à exclure de l'analyse d'accessibilité de votre page.

La valeur de runContext peut être :

1. Un sélecteur CSS unique pour les éléments à inclure dans l'analyse :

   axe: {
     runContext: '.main'
   }

2. Un tableau de sélecteurs CSS pour les éléments à inclure dans l'analyse :

   axe: {
     runContext: [ '.main', '.text-block' ]
   }

3. Un objet de contexte contenant include et exclude propriétés (comme indiqué dans l'exemple ci-dessus). Vous pouvez spécifier include ou exclude ou les deux. Chaque include ou exclude peut être un sélecteur CSS unique ou un tableau de sélecteurs CSS :

   axe: {
     runContext: {
       include: '.main',
       exclude: '.ad-section'
     }
   }

Plus de détails sont disponibles dans la documentation de contexte d'axe-core.

runOptions

(Facultatif) L'objet autorise le sous-ensemble suivant de propriétés du type axe-core : runOptions Options

• ancestry : La valeur par défaut est false. Si true, les sélecteurs CSS renvoyés incluent les éléments ancêtres des éléments renvoyés.

  important

  Si votre page utilise des ID ou des classes dynamiques (ID d'élément ou classes qui changent à chaque rechargement de la page), vous devez spécifier ancestry comme true afin qu'axe Developer Hub puisse détecter et suivre correctement si les problèmes d'accessibilité sont des doublons car, par défaut, axe Developer Hub s'attend à ce que les ID et les classes d'élément restent les mêmes entre les exécutions de test.

  Lorsque ancestry est true, axe Developer Hub utilise à la place la position de l'élément dans l'arborescence DOM pour localiser le même élément entre les exécutions de test.

  Voici un exemple de sélecteur pour un élément iframe avec un ID de ancestry main-iframe false ( ) : <iframe id="main-iframe" ...>

  iframe#main-iframe

  Si ancestry est true, le sélecteur inclurait le chemin complet à partir de l'élément racine, et aucun ID ni classe n'est spécifié :

  html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

• runOnly : Cela vous permet de limiter les règles exécutées en spécifiant des noms ou des balises. Voir runOnly ci-dessous pour plus d'informations.

• rules : Activer ou désactiver les règles à l'aide de la propriété enabled . Voir rules ci-dessous pour plus d'informations.

Ce qui suit montre un exemple de runOptions :

axe: {
  runOptions: {
    ancestry: true,
    runOnly: {
      type: 'tag',
      values: 'wcag2a'
    },
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

runOnly

La valeur (partie de l'objet [runOptions] runOnly ) peut être l'une des suivantes :(#runoptions)

1. Une chaîne représentant l'ID de la règle que vous souhaitez utiliser pour l'analyse d'accessibilité :

   axe: {
     runOptions: {
       runOnly: 'ruleId'
     }
   }

2. Un tableau de chaînes représentant les identifiants des règles que vous souhaitez utiliser :

   axe: {
     runOptions: {
       runOnly: [ 'ruleId1', 'ruleId2' ]
     }
   }

3. Un objet avec type et les values propriétés. La type valeur est une chaîne qui peut être des règles, une règle, une balise ou des balises. La propriété peut être une chaîne ou un tableau de chaînes représentant la règle ou les balises que vous souhaitez utiliser pour l'analyse d'accessibilité. values L'exemple suivant montre l'utilisation de runOnly l'objet pour limiter les tests d'accessibilité aux règles * marquées comme wcag2a :*

   axe: {
     runOptions: {
       runOnly: {
         type: 'tag',
         values: 'wcag2a'
       }
     }  
   }

• Pour plus d'exemples d'utilisation (avec axe-core), voir [Exemples de paramètres d'options] runOnly (https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter-examples)
• Pour plus d'informations sur les valeurs de balises disponibles, voir axe-core Balises.
• Pour plus d'informations sur les règles, les identifiants de règle et les balises, voir Descriptions des règles

rules

La valeur (sur l'objet) vous permet d' rules activer ou d' runOptions désactiver des règles spécifiques pendant l'analyse, comme indiqué ci-dessous :enabled: true``enabled: false

axe: {
  runOptions: {
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

sessionId

La propriété est obsolète et ne doit pas être utilisée. sessionId Voir buildID ci-dessus.

timeout

L'objet (de type [Timeouts] timeout ) dans(#timeouts-interface)définit les valeurs de délai d'attente en millisecondes pour les méthodes de contrôleur respectives (ou les commandes personnalisées pour Cypress). AxeConfiguration (Voir les Classes de contrôleur pour plus d'informations sur les classes de contrôleur et les Commandes personnalisées Cypress pour plus d'informations sur les commandes personnalisées Cypress.) Lorsqu'un délai d'attente expire, le test échoue avec un message indiquant que le délai d'attente a été dépassé. Vous pouvez augmenter le délai d'attente pour éviter l'erreur.

Cet exemple définit le délai d'expiration à 8 secondes, à 15 secondes, à 10 secondes et à 10 secondes. analyze flush start stop (Les valeurs par défaut sont indiquées dans le tableau sous Interface Timeouts.)

axe: {
  timeout: {
    analyze: 8000
    flush: 15000,
    start: 10000,
    stop: 10000,
  }
}

Classes de contrôleur

Fonctions de configuration

Les fonctions de configuration fournies par Watcher vous permettent de modifier votre configuration pour le framework de test spécifié ainsi que d'adapter la manière dont vous souhaitez exécuter Watcher en fonction de vos besoins. Voir Interface AxeConfiguration pour plus d'informations.

cypressConfig

Crée une configuration pour Cypress.

cypressConfig(config: Cypress.ConfigOptions & Configuration): Cypress.ConfigOptions

cypressConfig Paramètres

• config: Cypress.ConfigOptions & Configuration

  Type d'intersection de Cypress.ConfigOptions et Configuration.

Renvoie: Cypress.ConfigOptions

playwrightConfig

Crée une configuration pour Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Paramètres

• opts: Configuration & LaunchOptions

  Type d'intersection de LaunchOptions et Configuration.

Renvoie: LaunchOptions

playwrightTest

Crée une configuration pour Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Paramètres

• options: Options

  Options est un type d'intersection de Configuration et LaunchOptions.

Renvoie: ReturnValue

puppeteerConfig

Crée une configuration pour Puppeteer.

puppeteerConfig(opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions): Options

puppeteerConfig Paramètres

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  Type d'intersection de LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions et Configuration.

Renvoie: Options

wdioConfig

Crée une configuration WebdriverIO.

wdioConfig({ axe, ...options}: Options): RemoteOptions

wdioConfig Paramètres

• arg: Options

  Options est un type d'intersection de RemoteOptions et Configuration.

Retours: RemoteOptions

wdioTestRunner

Crée une configuration WebdriverIO Testrunner.

wdioTestRunner(...params: unknown[]): Options.Testrunner

wdioTestRunner Paramètres

• params : inconnu[]

  La valeur « params » est l’une des suivantes :

  1. Un tableau contenant une valeur, qui est un type d'intersection de Options.Testrunner et Configuration.
  2. Un tableau où la première valeur du tableau est un AxeConfiguration et la deuxième valeur est un Options.Testrunner.

Retours: Options.Testrunner

webdriverConfig

Crée une configuration Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Paramètres

• arg: WebDriverArgs

  Une Configuration étendue pour inclure un membre Selenium WebDriver Options .

Retours: Options

Configuration Interface

Configuration L'interface est utilisée avec les fonctions de configuration et contient une propriété :

Toutes les fonctions de configuration utilisent cette axe propriété pour vous permettre de configurer Watcher et de paramétrer vos tests d'accessibilité. Consultez la section suivante, AxeConfiguration Interface, pour plus d'informations.

ConfigurationOverrides Interface

L'interface vous permet de remplacer les paramètres de configuration globaux de votre organisation pour les exécutions de tests individuelles. ConfigurationOverrides Cette propriété doit être utilisée conformément aux autorisations définies dans la configuration globale de votre entreprise.

accessibilityStandard

Définit la norme d'accessibilité à tester. Options disponibles :

• « Tous » - Tests par rapport à toutes les normes disponibles
• « WCAG 2.2 AAA »
• « WCAG 2.2 AA »
• « WCAG 2.2 A »
• « WCAG 2.1 AAA »
• « WCAG 2.1 AA »
• « WCAG 2.1 A »
• « WCAG 2.0 AAA »
• « WCAG 2.0 AA »
• « WCAG 2.0 A »
• « Trusted Tester v5 »
• 'EN 301 549'

Votre organisation doit autoriser le remplacement de ce paramètre dans la configuration globale et la norme sélectionnée doit figurer parmi les options autorisées.

axeCoreVersion

Spécifie quelle version d'axe-core utiliser pour les tests. Les options disponibles incluent :

• 'latest' - Dernière version prise en charge actuellement fournie avec axe Watcher
• Versions spécifiques à partir de 4.4.0 et versions ultérieures (par exemple, « 4.10.2 », « 4.9.1 », etc.)

Votre organisation doit autoriser le remplacement de ce paramètre dans la configuration globale et la version sélectionnée doit figurer parmi les options autorisées.

bestPractices

Active ou désactive les règles de bonnes pratiques pour l'exécution du test. Les meilleures pratiques améliorent l’accessibilité mais ne font pas partie des normes formelles. Votre organisation doit autoriser le remplacement de ce paramètre pour qu'il prenne effet.

experimentalRules

Active ou désactive les règles expérimentales pour l'exécution du test. Les règles expérimentales sont encore en cours de développement et peuvent produire de faux positifs. Votre organisation doit autoriser le remplacement de ce paramètre dans la configuration globale pour qu'il prenne effet.

Controller Classes

Les classes suivantes étendent la classe abstraite Controller pour vous permettre de contrôler manuellement l'analyse d'accessibilité des pages de votre site Web.

Controller

abstract class Controller

La classe Controller abstraite contient les méthodes permettant de contrôler l'analyse des pages. Chacune des classes concrètes étend cette classe, donc les méthodes suivantes sont disponibles dans toutes les classes concrètes.

analyze

analyze(): Promise<void>

Analyse la page actuelle pour détecter les erreurs d'accessibilité. Vous appelez cette méthode après avoir configuré une page Web pour l'analyse (comme des valeurs saisies dans un formulaire) et avoir désactivé l'analyse automatique à l'aide de la méthode stop ou en définissant autoAnalyze sur false.

analyze Retourne

Promise<void>

analyze Commande Cypress équivalente

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Envoie tous les résultats de l'analyse d'accessibilité à axe Developer Hub. Doit être appelé à la fin du test pour garantir que les résultats ont été envoyés aux serveurs axe Developer Hub de Deque.

flush Retours

Promise<void>

flush Commande Cypress équivalente

cy.axeWatcherFlush()

start

start(): Promise<void>

Reprend l'auto-analyse des pages Web. Vous appelez cette méthode lorsque vous souhaitez reprendre l’analyse automatique des pages Web pour détecter les erreurs d’accessibilité.

start Retours

Promise<void>

start Commande Cypress équivalente

cy.axeWatcherStart()

stop

stop(): Promise<void>

Arrête l'analyse automatique des pages Web. Après avoir appelé la stop méthode, vous pouvez effectuer toute configuration supplémentaire dont votre page Web peut avoir besoin, puis appeler la analyze méthode pour vérifier la page à la recherche d'erreurs d'accessibilité.

stop Résultats

Promise<void>

stop Commande Cypress équivalente

cy.axeWatcherStop()

PlaywrightController

La classe vous permet de contrôler manuellement l'analyse d'accessibilité pour les tests avec Playwright et Playwright Test. PlaywrightController Vous pouvez démarrer et arrêter l'analyse automatique de l'accessibilité et analyser les pages qui nécessitent une configuration supplémentaire.

Pour plus d'informations sur Playwright, consultez la Documentation Playwright.

Constructeur

new PlaywrightController(driver: Page): PlaywrightController

Paramètres

• driver : Page

La driver valeur est un objet Playwright Page .

Retours PlaywrightController

Voir Controller pour les méthodes implémentées dans la classe de base abstraite.

PuppeteerController

La classe permet le contrôle manuel de vos exécutions de tests avec Puppeteer. PuppeteerController Le contrôle manuel vous permet de fournir une configuration supplémentaire requise par des pages Web plus complexes.

Pour plus d'informations sur Puppeteer, voir Puppeteer.

Constructeur

new PuppeteerController(driver: Page): PuppeteerController

Paramètres

• driver : Page

La driver valeur est un objet Puppeteer Page .

Renvoie PuppeteerController

Voir Controller pour les méthodes implémentées dans la classe de base abstraite.

WdioController

Le WdioController vous permet de contrôler manuellement les exécutions de tests WebdriverIO et WebdriverIO Testrunner. Pour les pages qui nécessitent une configuration supplémentaire, vous pouvez arrêter les tests automatiques et analyser manuellement chaque page qui nécessite une telle configuration.

Constructeur

new WdioController(driver: Browser): WdioController

Paramètres

• driver: Browser

Renvoie WdioController

Voir Controller pour les méthodes implémentées dans la classe de base abstraite.

WebdriverController

Constructeur

new WebdriverController(driver: WebDriver): WebdriverController

Paramètres

• driver : WebDriver

La driver valeur est un objet Selenium WebDriver .

Renvoie WebdriverController

Voir Controller pour les méthodes implémentées dans la classe de base abstraite.

Commandes Cypress personnalisées

Dans la plate-forme d'automatisation du navigateur Cypress, les méthodes des classes *Controller sont implémentées sous forme de commandes personnalisées. Consultez Commandes personnalisées sur le site de documentation Cypress pour plus d'informations sur l'implémentation et l'utilisation des commandes personnalisées.

Les commandes personnalisées suivantes sont implémentées. Chaque commande personnalisée renvoie Chainable<void> pour permettre le chaînage avec d'autres commandes Cypress.

Exemple de commande Cypress

L'exemple suivant montre comment importer les commandes Cypress du package @axe-core/watcher du Developer Hub axe, puis appeler la commande axeWatcherFlush à la fin de chaque test (en la plaçant à l'intérieur de afterEach()) :

// Import the axe-watcher commands.
require('@axe-core/watcher/dist/cypressCommands')

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

Interface de temporisation

L'objet timeout (de type Timeouts) dans l'interface AxeConfiguration permet aux utilisateurs de modifier les valeurs de délai d'attente (en millisecondes) pour les fonctions de contrôleur respectives ou les commandes personnalisées Cypress.

interface Timeouts {
  start?: number
  stop?: number
  flush?: number
  analyze?: number
}