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 je een instantie van een Puppeteer Frame of Page doorgeven. 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 je uitvoeren. In plaats van een vooringeladen pagina door te geven, geef je een Browser object en URL door. 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 de Axe Universeel Formaat. De bestaande analyze() methode is ongewijzigd.

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

Afbakening

Er zijn twee opties om je Axe DevTools-scans af te bakenen: include en exclude. Ze beperken de scans tot de gespecificeerde CSS-selectors en kunnen gecombineerd worden. Ze maken beide gebruik van enkele CSS-selectors of arrays van CSS-selectors, zodat je je scan volledig kunt aanpassen.

include

.include(selector: string | string[])

Met de include chain-methode worden alleen elementen gescand die zijn geselecteerd door de CSS-selector of array van CSS-selectors. Dit is nuttig voor het controleren van enkele instances van gecomponentiseerde pagina's of om resultaten te beperken tot huidige ontwikkeling.

Het onderstaande voorbeeld toont dat de scope is beperkt tot elementen binnen de results-panel klasse:

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

exclude

.exclude(selector: string | string[])

De exclude chain-methode verwijdert elementen geselecteerd door een CSS-selector of een array van CSS-selectors van de pagina die gescand moet worden. Net als de include methode kunnen enkele selectors of een array van selectors worden doorgegeven. Deze methode kan ook gecombineerd worden met de include methode.

De voorbeeldaanroep hieronder toont de scope die h2 elementen uitsluit 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-IDs. Voor een volledige lijst van regels en hun beschrijvingen, bezoek de axe-core regel documentatie.

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

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

metTags

.withTags(tags: string | string[])

De withTags methode beperkt de scan tot de regels die geassocieerd zijn met het opgegeven tag of tags. Een complete lijst van regels die gelabeld zijn met tags kan gevonden worden 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. Opvolgende aanroepen van deze methode zullen eerdere aanroepen overschrijven. Een volledige lijst van regel-IDs en hun beschrijvingen kan gevonden worden in de axe-core regel documentatie.

Het volgende voorbeeld schakelt kleurcontrastverificatie uit.

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

Daarnaast kan disableRules gecombineerd worden met andere regelconfiguratiemethoden om door de gebruiker geconfigureerde regels sets aan te passen.

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 gebruikt moeten worden. Het zal alle andere geconfigureerde opties overschrijven, inclusief aanroepen naar 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 regels set te wijzigen vóór een analyse. Opvolgende aanroepen van deze methode zullen eerdere ongeldig maken 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 de standaard URL is 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 stelt gebruikers in staat om in te stemmen met het verzenden van gegevens naar de gebruiksservice.

.enableTracking(state: boolean)

Dit voorbeeld toont de enableTracking methode in combinatie 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 stelt gebruikers in staat om te veranderen waar de gebruiksstatistiekgegevens worden verzonden.

.setTrackingUrl(url: string)

Dit voorbeeld toont de setTrackingUrl() methode in combinatie 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 toont de setDistinctId methode in combinatie met de analyse methode en logt het resultatenobject naar de console:

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