Puppeteer-API-Referenz für Axe DevTools für 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 Frame oder Page übergeben. Dies ist das Ziel des Scans. Das zweite Argument ist ein optionales Objekt, das eine der folgenden zwei Eigenschaften enthalten kann:

1. axeSource (optional): ein String des axe-core-Quellcodes
2. rulesetID (optional): eine Standard-Regelsatz-ID

Um eine spezielle Version von axe-core zu verwenden (anders als die standardmäßig mit Ihrer Version von Axe DevTools für Web enthaltene), können Sie eine axe-core-Quelldatei als Argument übergeben. Erstellen Sie zuerst ein Axe-Quellobjekt, indem Sie die axe-core-Datei vom Dateisystem lesen. Dann übergeben Sie Ihre Axe DevTools-Instanz an das Axe-Quellobjekt:

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

Wenn Sie ein vorkonfiguriertes Regelset verwenden möchten, das anders als das Standardregelset ist, können Sie die rulesetID 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 ihm eine vorab geladene Seite zu übergeben, übergeben Sie ein Browser-Objekt und eine URL. Er schließt die Seite automatisch, nachdem analyze aufgerufen wurde. Außerdem führt er automatisch den CSP-Bypass aus. Dies ist sein Konstruktor:

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

Dieser Konstruktor beinhaltet die gleichen 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 Scanergebnisse 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();
})();

analyze

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

Diese Methode führt eine Analyse durch und übergibt jeden aufgetretenen Fehler und/oder das Ergebnisobjekt an die bereitgestellte Callback- oder Promise-Funktion. Beachten Sie, dass sie nicht verkettbar ist, da ihr Ablauf asynchron ist.

Das folgende Beispiel verwendet das zurückgegebene Promise 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 Callback-Funktion:

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

analyzeUniversal

.analyzeUniversal(): Promise<UniversalExport>

Führt eine Analyse durch und gibt die Ergebnisse im Axe Universal Format zurück. Die bestehende analyze()-Methode bleibt unverändert.

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

Scoping

Es gibt zwei Optionen für die Eingrenzung Ihrer Axe DevTools-Scans: 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.

include

.include(selector: string | string[])

Mit der include-Verkettungsmethode werden nur die Elemente gescannt, die durch den CSS-Selektor oder das Array von CSS-Selektoren ausgewählt wurden. Dies ist nützlich, um einzelne Instanzen von komponentisierten Seiten zu überprüfen oder Ergebnisse auf die aktuelle Entwicklung zu beschränken.

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

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

exclude

.exclude(selector: string | string[])

Die exclude-Verkettungsmethode entfernt Elemente, die durch einen CSS-Selektor oder ein Array von CSS-Selektoren ausgewählt wurden, 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 Umfang, der h2-Elemente mit der results-panel-Klasse ausschließt:

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

Regelkonfiguration

withRules

.withRules(rules: string | string[])

Diese Methode beschränkt die Analyse auf die angegebene Regel-ID oder Regel-IDs. Eine vollständige Liste der Regeln und deren Beschreibungen finden Sie auf der axe-core Regel-Dokumentation.

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

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

withTags

.withTags(tags: string | string[])

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

Das folgende Beispiel testet nur auf WCAG 2.0 Level A Regeln:

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

disableRules

.disableRules(rules: string | string[])

Diese Methode entfernt eine spezifische 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. Eine vollständige Liste der Regel-IDs und deren Beschreibungen finden Sie in der axe-core Regel-Dokumentation.

Das folgende Beispiel deaktiviert die Prüfung des Farbkontrasts.

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

Zusätzlich kann disableRules mit anderen Regelkonfigurationsmethoden verkettet werden, um benutzerdefinierte Regelsätze zu modifizieren.

Im folgenden Beispiel wird das Regel-Set so modifiziert, dass nur WCAG 2.0 A und AA-Regeln verwendet werden, dann wird die Farbkontrastprüfung deaktiviert:

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

axe-core-Optionen

Optionen

.options(options: Axe.RunOptions)

Die options-Methode gibt Optionen an, die von axe.run verwendet werden sollen. Sie überschreibt alle anderen konfigurierten Optionen, einschließlich Aufrufen von withRules und withTags. Siehe die axe-core-API-Dokumentation für Informationen.

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

configure

.configure(config: Axe.Spec)

Die configure-Methode injiziert ein Axt-Konfigurationsobjekt, um den Regelsatz vor einer Analyse zu modifizieren. Nachfolgende Aufrufe dieser Methode werden die vorherigen ungültig machen, indem axe.configure() aufgerufen und das Konfigurationsobjekt ersetzt wird. Siehe axe-core-API-Dokumentation für die Struktur des Objekts.

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

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

Nutzungsdienst

Standardmäßig ist der Nutzungsdienst aktiviert, und die Standard-URL ist https://usage.deque.com. Setzen Sie die Umgebungsvariable AXE_TRACK_USAGE auf false, um ihn zu deaktivieren.

Umgebungsvariablen

Diese Umgebungsvariablen ermöglichen es Ihnen, den Nutzungsdienst zu konfigurieren und die Eigenschaften der gemeldeten Ereignisse zu ändern.

enableTracking

Die Methode enableTracking() ermöglicht es Benutzern, dem Senden von Daten an den Nutzungsdienst zuzustimmen oder es abzulehnen. Das Senden ist standardmäßig aktiviert.

.enableTracking(state: boolean)

Dieses Beispiel zeigt die enableTracking-Methode in Kombination mit der analyze-Methode, die das results-Objekt in die Konsole loggt:

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

setTrackingUrl

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

.setTrackingUrl(url: string)

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

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

setDistinctId

Diese Methode ermöglicht es Benutzern, die gespeicherte oder verwendete eindeutige ID zu ändern.

.setDistinctId(distinctId: string)

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

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