Référence API pour la version JavaScript et TypeScript de Watcher

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

AxeConfiguration Interface

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

apiKey

(Requis) La valeur apiKey est l'une des deux propriétés (apiKey et projectId) qui doivent être définies dans votre AxeConfiguration. Vous pouvez obtenir sa valeur depuis la Page de gestion des clés API .

autoAnalyze

(Optionnel) Définissez cette valeur sur false pour empêcher les pages d'être analysées automatiquement. Pour plus d'informations sur le mode manuel, voir Contrôlez vos analyses.

buildID

(Optionnel) La propriété buildID , lorsqu'elle n'est pas null, permet aux exécuteurs de tests parallèles de générer des résultats qui apparaissent comme un seul test dans axe Developer Hub. Dans le cas d'exécutions de tests parallèles, chaque exécuteur de tests doit partager la même chaîne non nulle buildID , ce qui fait que chaque exécution de test concatène ses résultats avec les résultats existants pour le même buildID et le commit SHA de Git. Cependant, lorsque buildID est null, plusieurs exécutions de tests écrasent les résultats existants ayant le même commit SHA de Git.

Voir Exécution des tests en parallèle pour plus d'informations sur la façon d'utiliser buildID avec divers fournisseurs d'intégration continue.

configurationOverrides

(Optionnel) Remplace les valeurs définies dans la configuration globale. Voir l'interface ConfigurationOverrides pour plus d'informations.

excludeUrlPatterns

(Optionnel) Empêche toute URL qui correspond à l'un des motifs minimatch dans le tableau excludeUrlPatterns d'être analysée.

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

Dans Exclure les URL de l'analyse , vous pouvez trouver un tableau d'URLs et des exemples de motifs pour vérifier les correspondances.

git

(Optionnel) Contrôle la façon dont Watcher collecte les métadonnées Git pour l'exécution actuelle du test. Accepte l'une des trois valeurs :

• true (par défaut): Watcher collecte automatiquement les informations Git (branche, SHA du commit, auteur et autres champs) en utilisant le binaire Git local.
• false: Désactive toute collecte de métadonnées Git. Utilisez cela lorsque vous exécutez dans des environnements sans Git ou lorsque la collecte de données Git n'est pas nécessaire.
• Un GitConfig objet: Fournit des métadonnées Git explicites et évite entièrement l'auto-détection. Tous les champs que vous omettez utilisent par défaut null. Utilisez cela lorsque vos tests s'exécutent dans un dépôt séparé du dépôt en cours de test, ou dans des environnements CI où l'auto-détection Git n'est pas fiable.

Voir Fournir des métadonnées Git pour plus d'informations.

L' GitConfig objet a les champs optionnels suivants :

Exemple d'utilisation des variables d'environnement CI pour fournir des métadonnées Git explicites :

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: '<your-project-id>',
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    defaultBranch: 'main'
  }
}

projectId

(Obligatoire) Spécifie l'ID du projet qui recevra les résultats d'accessibilité de Watcher. Votre ID de projet est affiché avec les instructions lorsque vous créez un nouveau projet, et vous pouvez également l'obtenir depuis la page Projets du Hub des développeurs axe .

runContext

(Optionnel) Vous permet de choisir quels éléments sont inclus et exclus 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 montré 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 le Documentation du contexte axe-core.

runOptions

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

• ancestry: Par défaut, c'est false. Si true, les sélecteurs CSS retournés incluent les éléments ancêtres des éléments retournés.

  important

  Si votre page utilise des identifiants ou des classes dynamiques (identifiants ou classes d'élément qui changent à chaque rechargement de la page), vous devez spécifier ancestry comme true pour que le Hub Développeur Axe puisse détecter et suivre correctement si les problèmes d'accessibilité sont des doublons car, par défaut, le Hub Développeur Axe s'attend à ce que les identifiants et les classes d'élément restent identiques entre les sessions de test.

  Quand ancestry est true, le Hub Développeur Axe utilise à la place la position de l'élément dans l'arborescence DOM pour localiser le même élément entre les sessions de test.

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

  iframe#main-iframe

  Si ancestry est true, le sélecteur inclurait tout le chemin depuis l'élément racine, et il n'y a aucun identifiant ou classe spécifiés :

  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 étiquettes. Voir runOnly ci-dessous pour plus d'informations.

• rules: Activez ou désactivez les règles en utilisant la propriété enabled . Voir rules ci-dessous pour plus d'informations.

Voici un exemple de runOptions:

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

runOnly

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

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 IDs des règles que vous souhaitez utiliser :

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

3. Un objet avec type et values propriétés. La type valeur est une chaîne qui peut être rule, rules, tagou tags. La values propriété doit être un tableau de chaînes représentant le(s) règle(s) ou étiquette(s) que vous souhaitez utiliser pour l'analyse d'accessibilité. L'exemple suivant montre l'utilisation de l'objet runOnly pour limiter les tests d'accessibilité aux règles étiquetées comme wcag2a:

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

• Pour plus d'exemples d'utilisation de runOnly (avec axe-core), voir Exemples de Paramètres d'Options
• Pour plus d'informations sur les valeurs d'étiquette disponibles, voir Étiquettes axe-core.
• Pour des informations sur les règles, les IDs de règles et les étiquettes, voir Descriptions des Règles

rules

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

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

sessionId

(Facultatif) La sessionId propriété a été dépréciée et ne doit pas être utilisée. Voir buildID ci-dessus.

testingTypes

(Facultatif) La testingTypes propriété est un tableau de chaînes pour une utilisation avec Cypress pour spécifier des tests de composants ou de bout en bout (ou les deux).

axe: {
  testingTypes: ['e2e', 'component']
}

timeout

(Facultatif) L'objet timeout (de type Timeouts) dans AxeConfiguration définit les valeurs de temporisation en millisecondes pour les méthodes de contrôleur respectives (ou les commandes personnalisées pour Cypress). (Voir les Classes de Contrôleur pour les informations sur les classes de contrôleur et les Commentaires Personnalisés Cypress pour les informations sur les commandes personnalisées de Cypress.) Lorsqu'un délai de temporisation est dépassé, le test échoue avec un message indiquant que le délai a été dépassé. Vous pouvez augmenter le délai pour éviter l'erreur.

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

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

Fonctions de Configuration

Les fonctions de configuration fournies par Watcher vous permettent de modifier votre configuration pour le cadre de test spécifié, ainsi que d'adapter le fonctionnement de Watcher selon 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 pour WebdriverIO.

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

wdioConfig Paramètres

• arg: Options

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

**Renvoie**: RemoteOptions

wdioTestRunner

Crée une configuration pour WebdriverIO Testrunner.

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

wdioTestRunner Paramètres

• params: unknown[]

  La params valeur 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 est un AxeConfiguration et la deuxième valeur est un Options.Testrunner.

Résultats: Options.Testrunner

webdriverConfig

Crée une configuration Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Paramètres

• arg: WebDriverArgs

  Un Configuration étendu pour inclure un membre Selenium WebDriver Options .

Résultats: Options

Configuration Interface

L' Configuration 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 définir votre test d'accessibilité. Voir la section suivante, Interface AxeConfiguration, pour plus d'informations.

ConfigurationOverrides Interface

L' ConfigurationOverrides interface vous permet de remplacer les paramètres de configuration globaux de votre organisation pour des exécutions de test individuelles. 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 :

• « Toutes » - Teste contre 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 »
• « RGAAv4 » - Version 4 du RGAA (norme d'accessibilité française ; nécessite axe-core 4.11.0 ou plus)

Votre organisation doit permettre le remplacement de ce paramètre dans la configuration globale, et la norme sélectionnée doit être 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 supportée actuellement intégrée à Axe Watcher
• Versions spécifiques à partir de 4.4.0 et plus (par exemple, « 4.10.2 », « 4.9.1 », etc.)

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

bestPractices

Active ou désactive les règles de bonnes pratiques pour l'exécution du test. Les bonnes pratiques améliorent l'accessibilité mais ne font pas partie des normes formelles. Votre organisation doit permettre 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 développement et peuvent produire des faux positifs. Votre organisation doit permettre le remplacement de ce paramètre dans la configuration globale pour qu'il prenne effet.

Controller Classes

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

Controller

abstract class Controller

La Controller classe abstraite contient les méthodes pour contrôler l'analyse de page. 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 (par exemple, en ayant saisi des valeurs dans un formulaire) et après avoir désactivé l'analyse automatique en utilisant la méthode stop ou en définissant autoAnalyze à false.

analyze Renvoie

Promise<void>

analyze Commande Cypress équivalente

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Envoie tous les résultats de l'analyse d'accessibilité au Axe Developer Hub. Devrait être appelé à la fin de l'exécution du test pour s'assurer que les résultats ont été envoyés aux serveurs du Axe Developer Hub de Deque.

flush Renvoie

Promise<void>

flush Commande Cypress équivalente

cy.axeWatcherFlush()

start

start(): Promise<void>

Relance l'analyse automatique 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 Renvoie

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 méthode stop , vous pouvez effectuer toute autre configuration dont votre page web pourrait avoir besoin, puis appeler la méthode analyze pour vérifier la page à la recherche d'erreurs d'accessibilité.

stop Renvoie

Promise<void>

stop Commande Cypress équivalente

cy.axeWatcherStop()

PlaywrightController

La classe PlaywrightController vous permet de contrôler manuellement l'analyse d'accessibilité lors des tests effectués avec Playwright et Playwright Test. Vous pouvez démarrer et arrêter l'analyse automatique de l'accessibilité et analyser les pages nécessitant 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 valeur driver est un objet Playwright. Page

Renvoie PlaywrightController

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

PuppeteerController

La classe PuppeteerController vous permet de contrôler manuellement vos tests avec Puppeteer. Le contrôle manuel vous permet de fournir des configurations supplémentaires requises par les pages web plus complexes.

Pour plus d'informations sur Puppeteer, consultez Puppeteer.

Constructeur

new PuppeteerController(driver: Page): PuppeteerController

Paramètres

• driver: Page

La valeur driver 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 avec WebdriverIO et WebdriverIO Testrunner. Pour les pages nécessitant des configurations ou des paramétrages supplémentaires, vous pouvez arrêter les tests automatiques et analyser manuellement chaque page nécessitant un tel paramétrage.

Constructeur

new WdioController(driver: Browser): WdioController

Paramètres

• driver: Browser

Retours 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 valeur driver est un objet Selenium WebDriver .

Retours WebdriverController

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

Commandes personnalisées Cypress

Dans la plateforme d'automatisation de navigateurs Cypress, les méthodes des classes *Controller sont implémentées en tant que commandes personnalisées. Voir Commandes personnalisées sur le site de documentation de 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 retourne Chainable<void> pour permettre l'enchaînement avec d'autres commandes Cypress.

Exemple de commande Cypress

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

// Import the axe-watcher commands.
require('@axe-core/watcher/cypress/support')

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

Interface de délais d'attente

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
}