Riferimento API Puppeteer per Axe DevTools per il Web

Costruttori

Ci sono due costruttori per Axe DevTools Puppeteer. Questo è il costruttore standard:

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

Per il primo argomento, è necessario passare un'istanza di un Puppeteer Frame o Page. Questo è l'obiettivo della scansione. Il secondo argomento è un oggetto opzionale che può contenere una delle seguenti due proprietà:

1. axeSource (opzionale): una stringa di codice sorgente axe-core
2. rulesetID (opzionale): un ID di set di regole standard

Per utilizzare una versione specifica di axe-core (diversa da quella inclusa come standard con la tua versione di Axe DevTools per il Web), puoi passare un file sorgente axe-core come argomento. Innanzitutto, crea un oggetto sorgente axe leggendo il file axe-core dal filesystem. Quindi, passa la tua istanza di Axe DevTools all'oggetto sorgente axe:

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

Se desideri utilizzare un set di regole predefinito diverso da quello standard, puoi passare il rulesetID alla tua istanza di Axe DevTools:

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

Un costruttore alternativo può aprire una pagina ed eseguire il bypass CSP per te. Invece di passarle una pagina precaricata, passi un Browser oggetto e URL. Chiude automaticamente la pagina dopo che analyze viene chiamato. Inoltre, esegue automaticamente il bypass CSP. Questo è il suo costruttore:

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

Questo costruttore include le stesse opzioni per fonti alternative axe-core o set di regole, e questi argomenti vengono passati nello stesso modo descritto sopra. Ecco un file di esempio che utilizza il costruttore alternativo, che registra i risultati della scansione nella 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();
})();

analizzare

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

Questo metodo esegue un'analisi e passa eventuali errori riscontrati e/o l'oggetto dei risultati alla funzione di callback o di promessa fornita. Tieni presente che non si concatena perché la sua operazione è asincrona.

Il seguente esempio utilizza la promessa restituita e registra l'oggetto dei risultati nella console:

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

Questo esempio mostra il metodo analyse() con una funzione di callback:

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

analizzareUniversale

.analyzeUniversal(): Promise<UniversalExport>

Esegue un'analisi e restituisce i risultati nel Formato Universale Axe. Il metodo esistente analyze() rimane invariato.

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

Scoping

Esistono due opzioni per delimitare le scansioni del tuo Axe DevTools: include e exclude. Questi delimitano le scansioni ai selettori CSS specificati e possono essere concatenati insieme. Entrambi utilizzano singoli selettori CSS o array di selettori CSS, in modo da poter personalizzare completamente la tua scansione.

includere

.include(selector: string | string[])

Con il metodo a catena include , verranno scansionati solo gli elementi selezionati dal selettore CSS o dall'array di selettori CSS. Questo è utile per controllare singoli casi di pagine componentizzate o per limitare i risultati allo sviluppo corrente.

L'esempio seguente mostra che il campo è limitato agli elementi all'interno della classe results-panel :

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

escludere

.exclude(selector: string | string[])

Il metodo a catena exclude rimuove gli elementi selezionati da un selettore CSS o un array di selettori CSS dalla pagina da scansionare. Come il metodo include , possono essere passati selettori singoli o un array di selettori. Questo metodo può anche essere concatenato con il metodo include .

La chiamata di esempio seguente mostra l'ambito che esclude gli elementi con la classe h2 : results-panel .

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

Configurazione delle Regole

conRegole

.withRules(rules: string | string[])

Questo metodo limita l'analisi all'ID della regola specificata o agli ID delle regole specificate. Per un elenco completo delle regole e delle loro descrizioni, visita la documentazione delle regole axe-core.

Nel seguente esempio, verranno testate solo le regole html-lang e image-alt :

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

conTags

.withTags(tags: string | string[])

Il withTags metodo limita la scansione alle regole associate al tag o ai tag specificati. Un elenco completo dei tag del set di regole può essere trovato nella documentazione di axe-core.

Il seguente esempio testa solo le regole WCAG 2.0 Livello A:

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

disabilitaRegole

.disableRules(rules: string | string[])

Questo metodo rimuove una regola specifica o un array di regole dall'attuale elenco di regole da utilizzare. Le regole sono specificate tramite il loro ID. Le chiamate successive a questo metodo sovrascriveranno le chiamate precedenti. Un elenco completo degli ID delle regole e le loro descrizioni possono essere trovati nella documentazione delle regole di axe-core.

Il seguente esempio disabilita la verifica del contrasto dei colori.

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

Inoltre, disableRules può essere concatenato con altri metodi di configurazione delle regole per modificare i set di regole configurati dall'utente.

Nel seguente esempio, il set di regole è modificato per utilizzare solo le regole WCAG 2.0 A e AA, quindi rimuove la regola di verifica del contrasto dei colori:

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

opzioni axe-core

opzioni

.options(options: Axe.RunOptions)

Il options metodo specifica le opzioni da utilizzare da axe.run. Sovrascriverà qualsiasi altra opzione configurata, incluse le chiamate a withRules e withTags. Vedi la documentazione API di axe-core per informazioni.

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

configura

.configure(config: Axe.Spec)

Il configure metodo inietta un oggetto di configurazione axe per modificare il set di regole prima di un'analisi. Le chiamate successive a questo metodo invalideranno le precedenti richiamando axe.configure() e sostituendo l'oggetto di configurazione. Vedi documentazione API di axe-core per la struttura dell'oggetto.

Il seguente esempio crea una nuova configurazione di axe-core e la passa a Axe DevTools per essere utilizzata nella scansione:

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

Servizio di utilizzo

Per impostazione predefinita, il servizio di utilizzo è disabilitato e l'URL predefinito è https://usage.deque.com.

Variabili d'ambiente

Queste variabili d'ambiente consentono di configurare il servizio di utilizzo e modificare le proprietà degli eventi segnalati.

abilitaMonitoraggio

Il enableTracking() metodo consente agli utenti di scegliere di inviare dati al servizio di utilizzo.

.enableTracking(state: boolean)

Questo esempio mostra il enableTracking metodo abbinato al analyze metodo, che registra l' results oggetto nella console:

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

impostaUrlMonitoraggio

Il setTrackingUrl() metodo consente agli utenti di modificare dove vengono inviati i dati delle metriche di utilizzo.

.setTrackingUrl(url: string)

Questo esempio mostra il setTrackingUrl() metodo con il analyze() metodo e registra l' results oggetto nella console:

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

impostaIdDistinto

Questo metodo consente agli utenti di modificare l'id distinto che viene memorizzato o utilizzato.

.setDistinctId(distinctId: string)

Questo esempio mostra il setDistinctId metodo con il analyse metodo e registra l'oggetto dei risultati nella console:

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