Riferimento API Puppeteer per axe DevTools per Web

Costruttori

Ci sono due constructori per axe DevTools Puppeteer. Questo è il costruttore standard:

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

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

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

Per utilizzare una versione specifica di axe-core (diversa da quella inclusa di serie nella tua versione di axe DevTools per Web), puoi passare un file sorgente di axe-core come argomento. Per prima cosa, crea un oggetto sorgente axe leggendo il file axe-core dal file system. Quindi, passa l'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 precaricata, si passa un Browser oggetto e un URL. Chiude automaticamente la pagina dopo analyze la chiamata. Inoltre, esegue automaticamente il bypass CSP. Questo è il suo costruttore:

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

Questo costruttore include le stesse opzioni per sorgenti o rulesets axe-core alternativi e questi argomenti vengono passati nello stesso modo di cui 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 risultato alla funzione di callback o promessa fornita. Tieni presente che non è in catena perché il suo funzionamento è asincrono.

L'esempio seguente 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);
});

Ambito di applicazione

Esistono due opzioni per definire l'ambito delle scansioni di axe DevTools: include e exclude. Definiscono l'ambito delle scansioni ai selettori CSS specificati e possono essere concatenati tra loro. Entrambi utilizzano singoli selettori CSS o array di selettori CSS, così puoi personalizzare completamente la tua scansione.

include

.include(selector: string | string[])

Con il metodo chain, verranno scansionati solo gli elementi selezionati dal selettore CSS o dall'array di selettori CSS. include Ciò è utile per controllare singole istanze di pagine componentizzate o per limitare i risultati allo sviluppo corrente.

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 exclude chain rimuove gli elementi selezionati da un selettore CSS o da una matrice di selettori CSS dalla pagina da scansionare. Come il metodo include , è possibile passare singoli selettori o un array di selettori. Questo metodo può anche essere concatenato con il include metodo.

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

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

Configurazione delle regole

conRegole

.withRules(rules: string | string[])

Questo metodo limita l'analisi all'ID o agli ID delle regole specificati. Per un elenco completo delle regole e delle relative descrizioni, visita la documentazione delle regole axe-core.

Nell'esempio seguente, 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 nella documentazione di axe-core.

Il seguente esempio verifica solo le regole WCAG 2.0 di livello A:

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

disableRules

.disableRules(rules: string | string[])

Questo metodo rimuove una regola specifica o una serie di regole dall'elenco corrente di regole da utilizzare. Le regole sono specificate dal loro ID regola. Le chiamate successive a questo metodo sovrascriveranno le chiamate precedenti. Un elenco completo degli ID delle regole e delle relative descrizioni è disponibile nella documentazione delle regole axe-core.

L'esempio seguente 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.

Nell'esempio seguente, il set di regole viene 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à tutte le altre opzioni configurate, comprese le chiamate a withRules e withTags. Per informazioni, consultare la documentazione API axe-core .

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

configura

.configure(config: Axe.Spec)

Il metodo configure inietta un oggetto di configurazione 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. Per la struttura dell'oggetto, consultare la documentazione API axe-core .

L'esempio seguente crea una nuova configurazione axe-core e la passa ad axe DevTools per utilizzarla per la 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

Questo metodo consente agli utenti di modificare valori specifici del servizio di utilizzo tramite variabili di ambiente.

enableTracking

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

.enableTracking(state: boolean)

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

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

setTrackingUrl

setTrackingUrl() Il metodo consente agli utenti di modificare la destinazione dei dati delle metriche di utilizzo.

.setTrackingUrl(url: string)

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

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

setDistinctId

Questo metodo consente agli utenti di modificare l'ID univoco 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)
  })