Puppeteer API-referentie voor Axe DevTools voor Web

Constructors

Er zijn twee constructors voor Axe DevTools Puppeteer. Dit is de standaardconstructor:

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

Voor het eerste argument moet u een instantie van een Puppeteer Frame of Page. Dit is het doel van de scan. Het tweede argument is een optioneel object dat een van de volgende twee eigenschappen kan bevatten:

1. axeSource (optioneel): een string van axe-core broncode
2. rulesetID (optioneel): een standaardregels-ID

Om een specifieke versie van axe-core te gebruiken (anders dan wat standaard bij uw versie van Axe DevTools voor Web wordt geleverd), kunt u een axe-core bronbestand als argument meegeven. Maak eerst een bronobject door het axe-core bestand van het bestandssysteem te lezen. Geef vervolgens uw Axe DevTools-instantie door aan het bronobject:

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

Als u een vooraf gedefinieerd regelsysteem wilt gebruiken, anders dan het standaardregelsysteem, kunt u de regelsetID aan uw Axe DevTools-instantie meegeven:

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

Een alternatieve constructor kan een pagina openen en de CSP-bypass voor u uitvoeren. In plaats van een vooraf geladen pagina mee te geven, geeft u een Browser object en URL. Het sluit de pagina automatisch nadat analyze is aangeroepen. Bovendien voert het automatisch de CSP-bypass uit. Dit is de constructor:

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

Deze constructor bevat dezelfde opties voor alternatieve axe-core bronnen of regelsystemen, en deze argumenten worden op dezelfde manier als hierboven doorgegeven. Hier is een voorbeeldbestand dat de alternatieve constructor gebruikt en de scanresultaten naar de console logt:

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])

Deze methode voert een analyse uit en geeft eventuele fouten en/of het resultatenobject door aan de opgegeven callback of beloftesfunctie. Wees ervan bewust dat het niet kan worden gekoppeld omdat de werking asynchroon is.

Het volgende voorbeeld gebruikt de geretourneerde belofte en logt het resultatenobject naar de console:

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

Dit voorbeeld toont de analyse() methode met een callbackfunctie:

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

analyzeUniversal

.analyzeUniversal(): Promise<UniversalExport>

Voert een analyse uit en retourneert resultaten in het Axe Universeel Formaat. De bestaande analyze() methode blijft ongewijzigd.

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

Afbakening

Er zijn twee opties voor het afbakenen van uw Axe DevTools-scans: include en exclude. Ze beperken de scans tot de opgegeven CSS-selectors en kunnen aan elkaar gekoppeld worden. Ze gebruiken beide enkele CSS-selectors of arrays van CSS-selectors, zodat u uw scan volledig kunt aanpassen.

include

.include(selector: string | string[])

Met de include chainmethode worden alleen elementen geselecteerd door de CSS-selector of array van CSS-selectors die gescand worden. Dit is nuttig voor het controleren van enkele instanties van gecomponentiseerde pagina's of het beperken van resultaten tot huidige ontwikkelingen.

Dit voorbeeld hieronder laat zien dat de scope beperkt is tot elementen binnen de results-panel klasse:

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

exclude

.exclude(selector: string | string[])

De exclude chainmethode verwijdert elementen geselecteerd door een CSS-selector of een array van CSS-selectors van de te scannen pagina. Net als de include methode, kunnen enkele selectors of een array van selectors worden doorgegeven. Deze methode kan ook worden gekoppeld met de include methode.

De voorbeeldaanroep hieronder toont de scope exclusief h2 elementen met de results-panel klasse:

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

Regelconfiguratie

withRules

.withRules(rules: string | string[])

Deze methode beperkt de analyse tot de opgegeven regel-ID of regel-ID's. Voor een complete lijst van regels en hun beschrijvingen, bezoek de axe-core regeldocumentatie.

In het volgende voorbeeld worden alleen de html-lang en image-alt regels getest:

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

metTags

.withTags(tags: string | string[])

De withTags methode beperkt de scan tot de regels die aan de opgegeven tag of tags zijn gekoppeld. Een volledige lijst van regels met tags is te vinden in de axe-core documentatie.

Het volgende voorbeeld test alleen op WCAG 2.0 Niveau A regels:

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

disableRules

.disableRules(rules: string | string[])

Deze methode verwijdert een specifieke regel of een array van regels uit de huidige lijst van te gebruiken regels. Regels worden gespecificeerd door hun regel-ID. Latere aanroepen van deze methode zullen eerdere aanroepen overschrijven. Een volledige lijst van regel-ID's en hun beschrijvingen is te vinden in de axe-core regel documentatie.

Het volgende voorbeeld schakelt kleurcontrastverificatie uit.

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

Bovendien kan disableRules worden gekoppeld met andere regelconfiguratiemethoden om gebruikersgeconfigureerde regelsets te wijzigen.

In het volgende voorbeeld wordt de regelset zo gewijzigd dat alleen WCAG 2.0 A en AA regels worden gebruikt, en vervolgens wordt de kleurcontrastverificatieregel verwijderd:

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

axe-core opties

opties

.options(options: Axe.RunOptions)

De options methode specificeert opties die door axe.run worden gebruikt. Het zal alle andere geconfigureerde opties overschrijven, inclusief aanroepen van withRules en withTags. Zie de axe-core API documentatie voor informatie.

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

configure

.configure(config: Axe.Spec)

De configure methode injecteert een axe configuratieobject om de regelset te wijzigen voordat een analyse plaatsvindt. Latere aanroepen van deze methode maken eerdere ongeldig door axe.configure() aan te roepen en het configuratieobject te vervangen. Zie axe-core API documentatie voor de structuur van het object.

Het volgende voorbeeld maakt een nieuwe axe-core configuratie en geeft deze door aan Axe DevTools om te worden gebruikt voor scanning:

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

Gebruik Service

Standaard is de gebruiksservice uitgeschakeld en is de standaard-URL https://usage.deque.com.

Omgevingsvariabelen

Deze omgevingsvariabelen stellen je in staat de gebruiksservice te configureren en de eigenschappen van gerapporteerde gebeurtenissen te wijzigen.

enableTracking

De enableTracking() methode laat gebruikers toe om in te stemmen gegevens naar de gebruiksservice te sturen.

.enableTracking(state: boolean)

Dit voorbeeld toont de enableTracking methode samen met de analyze methode, die het results object naar de console logt:

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

setTrackingUrl

De setTrackingUrl() methode maakt het voor gebruikers mogelijk om te wijzigen waar de gebruiksstatistieken naartoe worden gestuurd.

.setTrackingUrl(url: string)

Dit voorbeeld toont de setTrackingUrl() methode met de analyze() methode en logt het results object naar de console:

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

setDistinctId

Deze methode laat gebruikers toe om de unieke id die wordt opgeslagen of gebruikt te veranderen.

.setDistinctId(distinctId: string)

Dit voorbeeld laat de setDistinctId methode zien met de analyse methode en logt het resultaatobject naar de console:

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