Référence API Puppeteer pour Axe DevTools pour le Web

Constructeurs

Il existe deux constructeurs pour Axe DevTools Puppeteer. Voici le constructeur standard :

AxeDevToolsPuppeteer(page: Frame | Page, options?: IOptions)

Pour le premier argument, vous devez passer une instance d'un Puppeteer Frame ou Page. C'est la cible de l'analyse. Le deuxième argument est un objet optionnel qui peut contenir l'une des deux propriétés suivantes :

1. axeSource (optionnel) : une chaîne de code source axe-core
2. rulesetID (optionnel) : un identifiant de jeux de règles standard

Pour utiliser une version spécifique d'axe-core (autre que celle incluse par défaut avec votre version d'Axe DevTools pour le Web), vous pouvez passer un fichier source axe-core en tant qu'argument. Tout d'abord, créez un objet source axe en lisant le fichier axe-core depuis le système de fichiers. Ensuite, passez votre instance Axe DevTools à l'objet source axe :

const axeSource = fs.readFileSync('./axe-3.0.js', 'utf8');
const builder = new AxeDevToolsPuppeteer(page, { axeSource });

Si vous souhaitez utiliser un jeu de règles prédéfini autre que celui par défaut, vous pouvez passer l'ID du jeu de règles à votre instance Axe DevTools :

const builder = new AxeDevToolsPuppeteer(page, { rulesetID: 'wcag2' });

Un constructeur alternatif peut ouvrir une page et réaliser le contournement CSP pour vous. Au lieu de lui passer une page préchargée, vous passez un objet Browser et une URL. Il ferme automatiquement la page après l'appel de analyze. De plus, il effectue automatiquement le contournement CSP. Voici son constructeur :

loadPage(browser: Browser, url: string, options?: IOptions)

Ce constructeur inclut les mêmes options pour les sources axe-core alternatives ou les jeux de règles, et ces arguments sont passés de la même manière que précédemment. Voici un exemple de fichier utilisant le constructeur alternatif, qui enregistre les résultats du scan dans la console :

const puppeteer = require('puppeteer');
const { AxeDevToolsPuppeteer } = require('@axe-devtools/puppeteer');

(async () => {
    //launch puppeteer web driver
    const browser = await puppeteer.launch();
    const page = await browser.newPage();

    //launch page for testing
    await page.goto('https://broken-workshop.dequelabs.com');

    //analyze page
    const results = await new AxeDevToolsPuppeteer(page).analyze();
    //log results to console
    console.log(results);

    //close browser
    browser.close();
})();

analyze

.analyze([callback: (Error | null[, Object]) => void])

Cette méthode effectue une analyse et transmet toute erreur rencontrée et/ou l'objet résultat à la fonction de rappel ou de promesse fournie. Notez qu'elle ne peut pas être enchaînée car son opération est asynchrone.

L'exemple suivant utilise la promesse retournée et enregistre l'objet résultats dans la console :

new AxeDevToolsPuppeteer(page)
  .analyze()
  .then(function(results) {
    console.log(results);
  })
  .catch(err => {
    // Handle error somehow
  });

Cet exemple montre la méthode analyse() avec une fonction de rappel :

new AxeDevToolsPuppeteer(page).analyze(function(err, results) {
  if (err) {
    // Handle error somehow
  }
  console.log(results);
});

analyzeUniversal

.analyzeUniversal(): Promise<UniversalExport>

Effectue une analyse et renvoie les résultats dans le Axe Universal. La méthode existante analyze() reste inchangée.

new AxeDevToolsPuppeteer(page)
  .analyzeUniversal()
  .then(function(results) {
    console.log(results);
  })
  .catch(err => {
    // Handle error somehow
  });

Définition de la portée

Deux options existent pour définir la portée de vos analyses Axe DevTools : include et exclude. Elles définissent la portée des analyses aux sélecteurs CSS spécifiés et peuvent être enchaînées. Elles utilisent toutes deux des sélecteurs CSS uniques ou des tableaux de sélecteurs CSS, vous permettant de personnaliser entièrement votre analyse.

include

.include(selector: string | string[])

Avec la méthode de chaînage include, seuls les éléments sélectionnés par le sélecteur CSS ou le tableau de sélecteurs CSS seront analysés. Cela est utile pour vérifier des instances uniques de pages composantes ou limiter les résultats au développement en cours.

L'exemple ci-dessous montre que la portée est limitée aux éléments de la classe results-panel :

new AxeDevToolsPuppeteer(page).include('.results-panel');

exclude

.exclude(selector: string | string[])

La méthode de chaînage exclude supprime de la page à analyser les éléments sélectionnés par un sélecteur CSS ou un tableau de sélecteurs CSS. Comme la méthode include, des sélecteurs uniques ou un tableau de sélecteurs peuvent être passés. Cette méthode peut également être enchaînée avec la méthode include.

L'appel d'exemple ci-dessous montre que la portée exclut les éléments h2 avec la classe results-panel :

new AxeDevToolsPuppeteer(page).include('.results-panel h2');

Configuration des règles

withRules

.withRules(rules: string | string[])

Cette méthode limite l'analyse à l'ID ou aux IDs de règles spécifiés. Pour une liste complète des règles et de leurs descriptions, visitez le documentation des règles axe-core.

Dans l'exemple suivant, seules les règles html-lang et image-alt seront testées :

new AxeDevToolsPuppeteer(page).withRules(['html-lang', 'image-alt']);

withTags

.withTags(tags: string | string[])

La méthode withTags limite l'analyse aux règles associées au tag ou aux tags spécifiés. Une liste complète des tags de jeux de règles peut être trouvée dans le documentation axe-core.

L'exemple suivant teste uniquement les règles WCAG 2.0 Niveau A :

new AxeDevToolsPuppeteer(page).withTags('wcag2a');

disableRules

.disableRules(rules: string | string[])

Cette méthode supprime une règle spécifique ou un tableau de règles de la liste actuelle des règles à utiliser. Les règles sont spécifiées par leur ID de règle. Les appels ultérieurs à cette méthode remplaceront les appels précédents. Une liste complète des IDs de règles et de leurs descriptions peut être trouvée dans le documentation des règles axe-core.

L'exemple suivant désactive la vérification du contraste des couleurs.

new AxeDevToolsPuppeteer(page).disableRules('color-contrast');

De plus, disableRules peut être enchaîné avec d'autres méthodes de configuration de règles pour modifier des jeux de règles configurés par l'utilisateur.

Dans l'exemple suivant, l'ensemble de règles est modifié pour n'utiliser que les règles WCAG 2.0 A et AA, puis supprime la règle de vérification du contraste des couleurs :

new AxeDevToolsPuppeteer(page)
  .withTags(['wcag2a', 'wcag2aa'])
  .disableRules('color-contrast');

options axe-core

options

.options(options: Axe.RunOptions)

La méthode options spécifie les options à utiliser par axe.run. Elle remplacera toutes les autres options configurées, y compris les appels à withRules et withTags. Voir le documentation de l'API axe-core pour plus d'informations.

new AxeDevToolsPuppeteer(page).options({
  checks: { 'valid-lang': ['orcish'] }
});

configure

.configure(config: Axe.Spec)

La méthode configure injecte un objet de configuration axe pour modifier le jeux de règles avant une analyse. Les appels ultérieurs à cette méthode invalideront les précédents en appelant axe.configure() et en remplaçant l'objet de configuration. Voir documentation de l'API axe-core pour la structure de l'objet.

L'exemple suivant crée une nouvelle configuration axe-core et la passe à Axe DevTools pour être utilisée lors de l'analyse :

const config = {
  checks: [Object],
  rules: [Object]
};
const results = await new AxeDevToolsPuppeteer(page).configure(config).analyze();

Service d'utilisation

Par défaut, le service d'utilisation est activé, et l'URL par défaut est https://usage.deque.com. Définissez la variable d'environnement AXE_TRACK_USAGE sur false pour le désactiver.

Variables d'environnement

Ces variables d'environnement vous permettent de configurer le service d'utilisation et de changer les propriétés des événements signalés.

enableTracking

La méthode enableTracking() permet aux utilisateurs de choisir d'envoyer ou non des données au service d'utilisation. L'envoi est activé par défaut.

.enableTracking(state: boolean)

Cet exemple montre la méthode enableTracking associée à la méthode analyze, qui journalise l'objet results dans la console :

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .analyze()
  .then(function(results) {
    console.log(results)
  })

setTrackingUrl

La méthode setTrackingUrl() permet aux utilisateurs de changer l'endroit où les données des métriques d'utilisation sont envoyées.

.setTrackingUrl(url: string)

Cet exemple montre la méthode setTrackingUrl() avec la méthode analyze() et journalise l'objet results dans la console :

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setTrackingUrl('https://foobar.biz')
  .analyze()
  .then(function(results) {
    console.log(results)
  })

setDistinctId

Cette méthode permet aux utilisateurs de changer l'identifiant distinct stocké ou utilisé.

.setDistinctId(distinctId: string)

Cet exemple montre la méthode setDistinctId avec la méthode analyse et journalise l'objet des résultats dans la console :

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setDistinctId('foobar')
  .analyze()
  .then(function(results) {
    console.log(results)
  })