Puppeteer-API-Referenz für axe DevTools for Web

Konstruktoren

Es gibt zwei Konstruktoren für axe DevTools Puppeteer. Dies ist der Standardkonstruktor:

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

Für das erste Argument müssen Sie eine Instanz eines Puppeteer übergeben Frame oder Page. Dies ist das Ziel des Scans. Das zweite Argument ist ein optionales Objekt, das eine der folgenden beiden Eigenschaften enthalten kann:

1. axeSource (optional): eine Zeichenfolge mit Axe-Core-Quellcode
2. rulesetID (optional): eine Standard-Regelsatz-ID

Um eine bestimmte Version von Axe-Core zu verwenden (andere als die, die standardmäßig in Ihrer Version von axe DevTools enthalten ist), können Sie eine Axe-Core-Quelldatei als Argument übergeben. Erstellen Sie zunächst ein Axe-Quellenobjekt, indem Sie die Axe-Core-Datei aus dem Dateisystem lesen. Übergeben Sie dann Ihre Axe-DevTools-Instanz an das Axe-Quellenobjekt:

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

Wenn Sie einen anderen vordefinierten Regelsatz als den Standard verwenden möchten, können Sie die Regelsatz-ID an Ihre axe DevTools-Instanz übergeben:

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

Ein alternativer Konstruktor kann eine Seite öffnen und den CSP-Bypass für Sie durchführen. Anstatt eine vorinstallierte Seite zu übergeben, übergeben Sie ein Browser Objekt und eine URL. Es schließt die Seite automatisch, nachdem analyze aufgerufen wurde. Darüber hinaus führt es automatisch den CSP-Bypass durch. Dies ist sein Konstruktor:

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

Dieser Konstruktor enthält dieselben Optionen für alternative Axe-Core-Quellen oder Regelsets, und diese Argumente werden auf die gleiche Weise wie oben übergeben. Hier ist eine Beispieldatei, die den alternativen Konstruktor verwendet und die Scan-Ergebnisse in der Konsole protokolliert:

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();
})();

analysieren

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

Diese Methode führt eine Analyse durch und übergibt alle aufgetretenen Fehler und/oder das Ergebnisobjekt an die bereitgestellte Callback- oder Promise-Funktion. Beachten Sie, dass keine Aneinanderreihung erfolgt, da der Vorgang asynchron ist.

Das folgende Beispiel verwendet das zurückgegebene Versprechen und protokolliert das Ergebnisobjekt in der Konsole:

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

Dieses Beispiel zeigt die analyse() Methode mit einer Rückruffunktion:

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

Abgrenzung

Zum Festlegen des Geltungsbereichs Ihrer Axe DevTools-Scans stehen Ihnen zwei Optionen zur Verfügung: include und exclude. Sie beschränken die Scans auf die angegebenen CSS-Selektoren und können miteinander verkettet werden. Beide verwenden einzelne CSS-Selektoren oder Arrays von CSS-Selektoren, sodass Sie Ihren Scan vollständig anpassen können.

beinhaltet

.include(selector: string | string[])

Mit der include Kettenmethode werden nur die vom CSS-Selektor oder dem Array von CSS-Selektoren ausgewählten Elemente gescannt. Dies ist nützlich, um einzelne Instanzen von Seiten mit Komponenten zu prüfen oder die Ergebnisse auf die aktuelle Entwicklung zu beschränken.

Das folgende Beispiel zeigt, dass der Gültigkeitsbereich auf Elemente innerhalb der results-panel -Klasse beschränkt ist:

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

ausschließen

.exclude(selector: string | string[])

Die exclude Chain-Methode entfernt von einem CSS-Selektor oder einem Array von CSS-Selektoren ausgewählte Elemente von der zu scannenden Seite. Wie bei der include -Methode können einzelne Selektoren oder ein Array von Selektoren übergeben werden. Diese Methode kann auch mit der include -Methode verkettet werden.

Der folgende Beispielaufruf zeigt den Bereich, der h2 Elemente mit der results-panel Klasse ausschließt:

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

Regelkonfiguration

mitRegeln

.withRules(rules: string | string[])

Diese Methode beschränkt die Analyse auf die angegebene(n) Regel-ID(s). Eine vollständige Liste der Regeln und ihrer Beschreibungen finden Sie in der axe-core-Regeldokumentation.

Im folgenden Beispiel werden nur die Regeln html-lang und image-alt getestet:

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

mitTags

.withTags(tags: string | string[])

Die withTags Methode beschränkt den Scan auf die Regeln, die mit dem bzw. den angegebenen Tags verknüpft sind. Eine vollständige Liste der Regelsatz-Tags finden Sie in der axe-core-Dokumentation.

Das folgende Beispiel testet nur die WCAG 2.0 Level A-Regeln:

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

Regeln deaktivieren

.disableRules(rules: string | string[])

Diese Methode entfernt eine bestimmte Regel oder ein Array von Regeln aus der aktuellen Liste der zu verwendenden Regeln. Regeln werden durch ihre Regel-ID angegeben. Nachfolgende Aufrufe dieser Methode überschreiben vorherige Aufrufe. Eine vollständige Liste der Regel-IDs und ihrer Beschreibungen finden Sie in der axe-core-Regeldokumentation.

Das folgende Beispiel deaktiviert die Farbkontrastüberprüfung.

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

Darüber hinaus kann diese Methode disableRules mit anderen Regelkonfigurationsmethoden verkettet werden, um benutzerkonfigurierte Regelsätze zu ändern.

Im folgenden Beispiel wird der Regelsatz so geändert, dass nur die WCAG 2.0 A- und AA-Regeln verwendet werden. Anschließend wird die Regel zur Überprüfung des Farbkontrasts entfernt:

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

axe-core-Optionen

Optionen

.options(options: Axe.RunOptions)

Die Methode options gibt die von axe.run zu verwendenden Optionen an. Dadurch werden alle anderen konfigurierten Optionen überschrieben, einschließlich Aufrufe von withRules und withTags. Weitere Informationen finden Sie in der axe-core API-Dokumentation .

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

konfigurieren

.configure(config: Axe.Spec)

Die configure Methode fügt ein Axe-Konfigurationsobjekt ein, um den Regelsatz vor einer Analyse zu ändern. Nachfolgende Aufrufe dieser Methode machen vorherige Aufrufe ungültig, indem sie axe.configure() aufrufen und das Konfigurationsobjekt ersetzen. Informationen zur Struktur des Objekts finden Sie in der axe-core API-Dokumentation .

Das folgende Beispiel erstellt eine neue Axe-Core-Konfiguration und übergibt sie zur Verwendung beim Scannen an die axe DevTools:

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

Usage Service

Standardmäßig ist der Nutzungsdienst deaktiviert und die Standard-URL lautet https://usage.deque.com.

Umgebungsvariablen

Mit dieser Methode können Benutzer bestimmte Werte des Nutzungsdienstes über Umgebungsvariablen ändern.

Tracking aktivieren

Die enableTracking() Methode ermöglicht es Benutzern, der Übermittlung von Daten an den Nutzungsdienst zuzustimmen.

.enableTracking(state: boolean)

Dieses Beispiel zeigt die enableTracking Methode gepaart mit der analyze Methode, die das results Objekt in der Konsole protokolliert:

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

setTrackingUrl

Die setTrackingUrl() Methode ermöglicht es Benutzern, zu ändern, wohin die Nutzungsmetrikdaten gesendet werden.

.setTrackingUrl(url: string)

Dieses Beispiel zeigt die setTrackingUrl() Methode mit der analyze() Methode und protokolliert das results Objekt in der Konsole:

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

setDistinctId

Mit dieser Methode können Benutzer die gespeicherte oder verwendete distinct id ändern.

.setDistinctId(distinctId: string)

Dieses Beispiel zeigt die setDistinctId -Methode mit der analyse -Methode und protokolliert das Ergebnisobjekt in der Konsole:

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