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 beiden Eigenschaften enthalten kann:

1. axeSource (optional): ein String des axe-core-Quellcodes
2. rulesetID (optional): eine ID für ein Stock-Regelset

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. Es schließt die Seite automatisch, nachdem analyze aufgerufen wurde. Zusätzlich führt es automatisch den CSP-Bypass durch. 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 Formatzurü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, um Ihre Axe DevTools-Scans zu begrenzen: include und exclude. Sie begrenzen 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 komponentenbasierten Seiten zu überprüfen oder Ergebnisse auf aktuelle Entwicklungen 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 die include -Methode können einzelne Selektoren oder ein Array von Selektoren übergeben werden. Diese Methode kann auch mit der include -Methode verkettet werden.

Der nachfolgende 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. Für eine vollständige Liste der Regeln und deren Beschreibungen besuchen Sie die axe-core-Regeldokumentation.

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 dem oder den angegebenen Tags verknüpft sind. Eine vollständige Liste der Regeln-Set-Tags finden Sie in 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 Aufrufe. 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, disableRules kann mit anderen Regelkonfigurationsmethoden verkettet werden, um benutzerdefinierte Regeln-Sets zu ändern.

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 wird alle anderen konfigurierten Optionen überschreiben, 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 Axe-Konfigurationsobjekt, um das Regel-Set vor einer Analyse zu ändern. Nachfolgende Aufrufe dieser Methode werden vorherige ungültig machen, indem sie axe.configure() aufrufen und das Konfigurationsobjekt ersetzen. 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 deaktiviert, und die Standard-URL ist https://usage.deque.com.

Umgebungsvariablen

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

enableTracking

Die enableTracking() Methode ermöglicht es Benutzern, sich dafür zu entscheiden, Daten an den Nutzungsdienst zu senden.

.enableTracking(state: boolean)

Dieses Beispiel zeigt die enableTracking Methode kombiniert mit der analyze Methode, die das results Objekt an die 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 an 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 protokolliert das Ergebnisobjekt in der Konsole:

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