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 de Puppeteer Frame ou Page. Cela représente la cible du scan. Le deuxième argument est un objet optionnel qui peut contenir une des deux propriétés suivantes :

1. axeSource (optionnel) : une chaîne de code source axe-core
2. rulesetID (optionnel) : un ID de jeu 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 autre constructeur peut ouvrir une page et effectuer le contournement du CSP pour vous. Au lieu de lui passer une page préchargée, vous passez un Browser objet et une URL. Il ferme automatiquement la page après que analyze est appelé. 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 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 au format 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 scans Axe DevTools : include et exclude. Elles définissent la portée des scans aux sélecteurs CSS spécifiés et peuvent être enchaînées ensemble. Elles utilisent toutes les deux des sélecteurs CSS uniques ou des tableaux de sélecteurs CSS, vous permettant de personnaliser complètement votre scan.

include

.include(selector: string | string[])

Avec la méthode en chaîne 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 les instances uniques de pages composantes ou pour limiter les résultats au développement en cours.

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

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

exclude

.exclude(selector: string | string[])

La méthode en chaîne exclude 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 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 avec la classe h2 : 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 de règle spécifié ou aux ID de règles spécifiés. Pour obtenir la 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']);

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 des ensembles de règles peut être trouvée dans la 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 identifiant de règle. Les appels suivants à cette méthode remplaceront les appels précédents. Une liste complète des identifiants de règles et 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 enchaînée avec d'autres méthodes de configuration des 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 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 toute autre option configurée, y compris les appels à withRules et withTags. Voir la 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 l'ensemble de règles avant une analyse. Les appels suivants à cette méthode invalideront les précédents en appelant axe.configure() et remplacent 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 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 désactivé, et l'URL par défaut est https://usage.deque.com.

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 des données au service d'utilisation.

.enableTracking(state: boolean)

Cet exemple montre la méthode enableTracking associée à la méthode analyze , qui enregistre 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 enregistre 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 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)
  })