Référence de l'API Puppeteer pour axe DevTools for 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 facultatif qui peut contenir l'une des deux propriétés suivantes :

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

Pour utiliser une version spécifique d'axe-core (autre que celle incluse en standard avec votre version d'axe DevTools for 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 à partir du système de fichiers. Ensuite, transmettez 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 ensemble de règles prédéfini autre que celui standard, vous pouvez transmettre l'ID de l'ensemble de règles à votre instance axe DevTools :

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

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

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

Ce constructeur inclut les mêmes options pour les sources ou ensembles de règles axe-core alternatifs, et ces arguments sont passés de la même manière que ci-dessus. Voici un exemple de fichier utilisant le constructeur alternatif, qui enregistre les résultats de l'analyse 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();
})();

analyser

.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. Attention, il ne se chaîne pas car son fonctionnement est asynchrone.

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

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

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

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

Portée

Il existe deux options pour définir la portée de vos analyses axe DevTools : include et exclude. Ils délimitent les analyses aux sélecteurs CSS spécifiés et peuvent être enchaînés ensemble. Ils utilisent tous deux des sélecteurs CSS uniques ou des tableaux de sélecteurs CSS, ce qui vous permet de personnaliser entièrement votre analyse.

comprend

.include(selector: string | string[])

Avec la méthode include chain, seuls les éléments sélectionnés par le sélecteur CSS ou le tableau de sélecteurs CSS seront analysés. Ceci est utile pour vérifier des instances uniques de pages composées ou pour limiter les résultats au développement actuel.

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

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

exclure

.exclude(selector: string | string[])

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

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

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

Configuration des règles

avecRègles

.withRules(rules: string | string[])

Cette méthode limite l’analyse à l’ID de règle ou aux ID de règle spécifiés. Pour une liste complète des règles et leurs descriptions, visitez la 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']);

avecBalises

.withTags(tags: string | string[])

withTags La méthode limite l'analyse aux règles associées à la ou aux balises spécifiées. Une liste complète des balises de règles peut être trouvée dans la documentation axe-core.

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

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

Désactiver les règles

.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 identifiants de règles et de leurs descriptions peut être trouvée dans la 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 chaîné avec d'autres méthodes de configuration de règles pour modifier les ensembles de règles configurés par l'utilisateur.

Dans l'exemple suivant, l'ensemble de règles est modifié pour utiliser uniquement 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 d'axe-core

options

.options(options: Axe.RunOptions)

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

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

configurer

.configure(config: Axe.Spec)

La méthode configure injecte un objet de configuration d'axe pour modifier l'ensemble 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 la documentation de l'API axe-core pour la structure de l'objet.

L'exemple suivant crée une nouvelle configuration axe-core et la transmet à axe DevTools pour être utilisée pour 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 désactivé et l'URL par défaut est https://usage.deque.com.

Variables d’environnement

Cette méthode permet aux utilisateurs de modifier des valeurs spécifiques du service d'utilisation via des variables d'environnement.

Activer le suivi

La enableTracking() méthode permet aux utilisateurs de choisir d'envoyer des données au service d'utilisation.

.enableTracking(state: boolean)

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

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

setTrackingUrl

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

.setTrackingUrl(url: string)

Cet exemple montre la setTrackingUrl() méthode avec la analyze() méthode et enregistre l' results objet 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 modifier l’identifiant distinct stocké ou utilisé.

.setDistinctId(distinctId: string)

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

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