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, devi passare un'istanza di un Puppeteer Frame o Page. Questo è il target 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 predefinite

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 passargli una pagina pre-caricata, passi un oggetto Browser e un URL. Chiude automaticamente la pagina dopo che analyze è stato 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 analyze() esistente rimane invariato.

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

Scoping

Esistono due opzioni per delimitare le tue scansioni Axe DevTools: include e exclude. Delimitano le scansioni ai selettori CSS specificati e possono essere concatenati. Usano entrambi selettori CSS singoli o array di selettori CSS, quindi puoi 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 verificare singole istanze di pagine componentizzate o limitare i risultati allo sviluppo attuale.

L'esempio seguente mostra che l'ambito è 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 da 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.

L'esempio seguente mostra l'ambito escludendo gli elementi h2 con la classe results-panel:

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

Configurazione delle Regole

conRegole

.withRules(rules: string | string[])

Questo metodo limita l'analisi all'ID di regola specificato o agli ID di regole specificati. Per un elenco completo delle regole e delle loro descrizioni, visita il documentazione delle regole di 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 metodo withTags limita la scansione alle regole associate al tag o ai tag specificati. Un elenco completo dei tag del set di regole può essere trovato nel 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'elenco corrente delle regole da usare. Le regole sono specificate dal loro ID di regola. Le chiamate successive a questo metodo sovrascriveranno le chiamate precedenti. Un elenco completo degli ID di regola e delle loro descrizioni può essere trovato nel 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 metodo options specifica le opzioni da utilizzare da axe.run. Sovrascriverà qualsiasi altra opzione configurata, incluse le chiamate a withRules e withTags. Vedi il documentazione API di axe-core per informazioni.

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

configura

.configure(config: Axe.Spec)

Il metodo configure inietta un oggetto di configurazione di axe per modificare il set di regole prima di un'analisi. Le chiamate successive a questo metodo invalideranno quelle precedenti chiamando 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 è abilitato e l'URL predefinito è https://usage.deque.com. Imposta la variabile d'ambiente AXE_TRACK_USAGE su false per disabilitarlo.

Variabili d'ambiente

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

abilitaMonitoraggio

Il metodo enableTracking() consente agli utenti di scegliere se inviare o meno i dati al servizio di utilizzo. L'invio è abilitato per impostazione predefinita.

.enableTracking(state: boolean)

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

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

impostaUrlMonitoraggio

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

.setTrackingUrl(url: string)

Questo esempio mostra il metodo setTrackingUrl() con il metodo analyze() e registra l'oggetto results 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 metodo setDistinctId con il metodo analyse e registra l'oggetto dei risultati nella console:

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