API-Referenz

Dieses Referenzhandbuch beschreibt die vom @axe-core/watcher Paket bereitgestellten APIs (auch als axe Watcher oder einfach Watcher bezeichnet).

AxeConfiguration Schnittstelle

Die axe Eigenschaft (ein Parameter, der an die Konfigurationsfunktionen übergeben wird) ist die übliche Möglichkeit, Ihren AxeConfiguration für axe Watcher zu ändern, um Barrierefreiheitstests zu konfigurieren. Die folgenden Eigenschaften sind in AxeConfiguration enthalten:

apiKey

Der apiKey Wert ist die einzige Eigenschaft, die in Ihrem AxeConfiguration festgelegt werden muss. Den Wert können Sie der Projektseite entnehmen. Weitere Informationen finden Sie unter Projekte verwalten .

autoAnalyze

Setzen Sie diesen Wert auf false , um die automatische Analyse von Seiten zu verhindern. Weitere Informationen zum manuellen Modus finden Sie unter Steuern, wann die Seitenanalyse erfolgt.

buildID

Die optionale buildID Eigenschaft ermöglicht es, wenn sie nicht gesetzt ist, parallelen Testläufern, Ergebnisse zu generieren, die als einzelner Testlauf im axe Developer Hub angezeigt werden. null Bei parallelen Testläufen sollte jeder Testläufer dieselbe nicht-null Zeichenfolge verwenden, wodurch jeder Testlauf seine Ergebnisse mit vorhandenen Ergebnissen für denselben Git-Commit-SHA verknüpft. buildID buildID Wenn jedoch buildID gesetzt ist null, überschreiben ** mehrere Testläufe vorhandene Ergebnisse, die denselben Git-Commit-SHA haben.**

Normalerweise können Sie von Ihrem Anbieter für kontinuierliche Integration einen verwendbaren buildID Wert erhalten. Sie können beispielsweise diese Werte verwenden:

• github.run_id

  Verfügbar in GitHub-Workflows. Weitere Informationen finden Sie unter github context in der GitHub-Dokumentation.

• CIRCLE_PIPELINE_ID

  Mit CircleCI ist der obige Wert in der Umgebung Ihres Prozesses verfügbar. Weitere Informationen finden Sie unter Integrierte Umgebungsvariablen in der CircleCI-Dokumentation.

  Andere Umgebungsvariablen für die kontinuierliche Integration, die Sie für buildID verwenden können:

  Anbieter	Umgebungsvariable
  Bitbucket	BITBUCKET_BUILD_NUMBER
  GitLab	CI_PIPELINE_ID
  Jenkins	BUILD_NUMBER

configurationOverrides

(Optional) Überschreibt die in der [globalen Konfiguration] festgelegten Werte(dh-global-configuration). Weitere Informationen finden Sie in der ConfigurationOverrides-Schnittstelle .

excludeUrlPatterns

(Optional) Verhindert die Analyse von URLs, die mit einem der minimatch Muster im excludeUrlPatterns Array übereinstimmen.

axe: {
  excludeUrlPatterns: [ 'https://*.example.com/**', 'https://example.org/**' ]
}

Beispiele

runContext

(Optional) Ermöglicht Ihnen die Auswahl, welche Elemente in die Zugänglichkeitsanalyse Ihrer Seite einbezogen und davon ausgeschlossen werden sollen.

Der Wert von runContext kann sein:

1. Ein einzelner CSS-Selektor für Elemente, die in die Analyse einbezogen werden sollen:

   axe: {
     runContext: '.main'
   }

2. Ein Array von CSS-Selektoren für Elemente, die in die Analyse einbezogen werden sollen:

   axe: {
     runContext: [ '.main', '.text-block' ]
   }

3. Ein Kontextobjekt, das include und exclude Eigenschaften enthält (wie im obigen Beispiel gezeigt). Sie können include oder exclude oder beides angeben. Jedes include oder exclude kann ein einzelner CSS-Selektor oder ein Array von CSS-Selektoren sein:

   axe: {
     runContext: {
       include: '.main',
       exclude: '.ad-section'
     }
   }

Weitere Einzelheiten finden Sie in der axe-core Context-Dokumentation.

runOptions

(Optional) Das runOptions Objekt erlaubt die folgende Teilmenge von Eigenschaften vom Typ „axe-core“ Options :

• ancestry: Standard ist false. Wenn true, enthalten die zurückgegebenen CSS-Selektoren die übergeordneten Elemente der zurückgegebenen Elemente.

  important

  Wenn Ihre Seite dynamische IDs oder Klassen verwendet (Element-IDs oder Klassen, die sich bei jedem Neuladen der Seite ändern), müssen Sie dies als ancestry angeben, damit axe Developer Hub ordnungsgemäß erkennen und verfolgen kann, ob es sich bei Barrierefreiheitsproblemen um [Duplikate] handelt, da axe Developer Hub standardmäßig erwartet, dass Element-IDs und Klassen zwischen Testläufen gleich bleiben. true (dh-glossary#duplicate)

  Wenn ancestry ist true, verwendet axe Developer Hub stattdessen die Position des Elements innerhalb des DOM-Baums, um dasselbe Element zwischen Testläufen zu lokalisieren.

  Das folgende Beispiel zeigt einen Selektor, wenn ancestry für false ein iframe-Element mit der ID main-iframe (<iframe id="main-iframe" ...>) steht:

  iframe#main-iframe

  Wenn ancestry true ist, würde der Selektor den gesamten Pfad vom Stammelement einschließen und es sind keine IDs oder Klassen angegeben:

  html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

• runOnly: Hiermit können Sie durch die Angabe von Namen oder Tags einschränken, welche Regeln ausgeführt werden. Weitere Informationen finden Sie weiter unten unter runOnly .

• rules: Aktivieren oder deaktivieren Sie Regeln mithilfe der enabled Eigenschaft. Weitere Informationen finden Sie unten bei den Regeln .

Nachfolgend sehen Sie ein Beispiel für runOptions:

axe: {
  runOptions: {
    ancestry: true,
    runOnly: {
      type: 'tag',
      values: 'wcag2a'
    },
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

runOnly

Der runOnly Wert (Teil des Objekts runOptions ) kann einer der folgenden sein:

1. Eine Zeichenfolge, die die Regel-ID der Regel darstellt, die Sie für die Barrierefreiheitsanalyse verwenden möchten:

   axe: {
     runOptions: {
       runOnly: 'ruleId'
     }
   }

2. Ein Array von Zeichenfolgen, die die Regel-IDs der Regeln darstellen, die Sie verwenden möchten:

   axe: {
     runOptions: {
       runOnly: [ 'ruleId1', 'ruleId2' ]
     }
   }

3. Ein Objekt mit type und values Eigenschaften. Der type Wert ist eine Zeichenfolge, die Regeln, Regel, Tag oder Tags sein kann. Die values Eigenschaft kann eine Zeichenfolge oder ein Array von Zeichenfolgen sein, die die Regel oder Tags darstellen, die Sie für die Barrierefreiheitsanalyse verwenden möchten. Das folgende Beispiel zeigt die Verwendung des runOnly -Objekts, um die Barrierefreiheitsprüfungen auf Regeln zu beschränken, die mit wcag2a gekennzeichnet sind:

   axe: {
     runOptions: {
       runOnly: {
         type: 'tag',
         values: 'wcag2a'
       }
     }  
   }

– Weitere Beispiele zur Verwendung (mit axe-core) finden Sie unter [Beispiele für Optionsparameter]. runOnly (https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter-examples) – Weitere Informationen zu verfügbaren Tag-Werten finden Sie unter axe-core Tags.

• Informationen zu den Regeln, Regel-IDs und Tags finden Sie unter [Regelbeschreibungen].(https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)

rules

Mit dem rules Wert (auf dem runOptions Objekt) können Sie während der Analyse bestimmte Regeln aktivieren (enabled: true) oder deaktivieren (enabled: false), wie unten gezeigt:

axe: {
  runOptions: {
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

sessionId

Die sessionId Eigenschaft ist veraltet und sollte nicht verwendet werden. Siehe buildID oben.

timeout

Das timeout Objekt (vom Typ Timeouts) in AxeConfiguration legt die Timeout-Werte in Millisekunden für die jeweiligen Controller-Methoden (oder benutzerdefinierte Befehle für Cypress) fest. (Informationen zu den Controller-Klassen finden Sie in den Controller-Klassen und Informationen zu benutzerdefinierten Cypress-Befehlen in den Cypress-Befehle .) Wenn ein Timeout abläuft, schlägt der Test mit einer Meldung fehl, die angibt, dass das Timeout überschritten wurde. Sie können das Timeout erhöhen, um den Fehler zu vermeiden.

In diesem Beispiel wird das analyze Timeout auf 8 Sekunden, flush auf 15 Sekunden, start auf 10 Sekunden und stop auf 10 Sekunden festgelegt. (Die Standardwerte sind in der Tabelle unter Timeouts Interface aufgeführt.)

axe: {
  timeout: {
    analyze: 8000
    flush: 15000,
    start: 10000,
    stop: 10000,
  }
}

Controller-Klassen

Konfigurationsfunktionen

Mit den von Watcher bereitgestellten Konfigurationsfunktionen können Sie Ihr Setup für das angegebene Testframework ändern und die Ausführung von Watcher Ihren Anforderungen entsprechend anpassen. Weitere Informationen finden Sie unter AxeConfiguration Interface .

cypressConfig

Erstellt eine Konfiguration für Cypress.

cypressConfig(config: Cypress.ConfigOptions & Configuration): Cypress.ConfigOptions

cypressConfig Parameter

• config: Cypress.ConfigOptions & Configuration

  Schnittmengentyp von Cypress.ConfigOptions und Konfiguration.

Gibt zurück: Cypress.ConfigOptions

playwrightConfig

Erstellt eine Konfiguration für Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parameter

• opts: Configuration & LaunchOptions

  Schnittmengentyp von LaunchOptions und Konfiguration.

Gibt zurück: LaunchOptions

playwrightTest

Erstellt eine Konfiguration für den Playwright-Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parameter

• options: Options

  Options ist ein Schnitttyp von Konfiguration und LaunchOptions.

Gibt zurück: ReturnValue

puppeteerConfig

Erstellt eine Konfiguration für Puppeteer.

puppeteerConfig(opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions): Options

puppeteerConfig Parameter

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  Schnitttyp von LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions und Konfiguration.

Gibt zurück: Options

wdioConfig

Erstellt eine WebdriverIO-Konfiguration.

wdioConfig({ axe, ...options}: Options): RemoteOptions

wdioConfig Parameter

• arg: Options

  Options ist ein Schnitttyp von RemoteOptions und Konfiguration.

Gibt zurück: RemoteOptions

wdioTestRunner

Erstellt eine WebdriverIO Testrunner-Konfiguration.

wdioTestRunner(...params: unknown[]): Options.Testrunner

wdioTestRunner Parameter

• params: unbekannt[]

  Der params-Wert ist einer der folgenden:

  1. Ein Array mit einem Wert, der ein Schnitttyp aus „Options.Testrunner“ und „Configuration“ ist.
  2. Ein Array, bei dem der erste Array-Wert eine AxeConfiguration und der zweite Wert ein Options.Testrunner ist.

Rückgaben: Options.Testrunner

webdriverConfig

Erstellt eine Selenium WebDriver-Konfiguration.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parameter

• arg: WebDriverArgs

  Eine um ein Selenium WebDriver-Mitglied erweiterte Konfiguration . Options

Rückgaben: Options

Configuration Schnittstelle

Die Configuration Schnittstelle wird mit den Konfigurationsfunktionen verwendet und enthält eine Eigenschaft:

Alle Konfigurationsfunktionen verwenden diese axe Eigenschaft, damit Sie Watcher einrichten und Ihre Barrierefreiheitstests konfigurieren können. Weitere Informationen finden Sie im nächsten Abschnitt, AxeConfiguration Interface.

ConfigurationOverrides Schnittstelle

Über die ConfigurationOverrides Schnittstelle können Sie die globalen Konfigurationseinstellungen Ihrer Organisation für einzelne Testläufe überschreiben. Diese Eigenschaft muss in Übereinstimmung mit den in der globalen Konfiguration Ihres Unternehmens festgelegten Berechtigungen verwendet werden.

accessibilityStandard

Legt den Zugänglichkeitsstandard fest, anhand dessen getestet werden soll. Verfügbare Optionen:

• „Alle“ – Tests gegen alle verfügbaren Standards
• „WCAG 2.2 AAA“
• „WCAG 2.2 AA“
• „WCAG 2.2 A“
• „WCAG 2.1 AAA“
• „WCAG 2.1 AA“
• „WCAG 2.1 A“
• „WCAG 2.0 AAA“
• „WCAG 2.0 AA“
• „WCAG 2.0 A“
• „Trusted Tester v5“
• „EN 301 549“

Ihre Organisation muss das Überschreiben dieser Einstellung in der globalen Konfiguration zulassen und der ausgewählte Standard muss zu den zulässigen Optionen gehören.

axeCoreVersion

Gibt an, welche Version von axe-core zum Testen verwendet werden soll. Zu den verfügbaren Optionen gehören:

• 'latest' - Neueste unterstützte Version, die derzeit mit axe Watcher gebündelt ist

– Bestimmte Versionen ab 4.4.0 (z. B. „4.10.2“, „4.9.1“ usw.)

Ihre Organisation muss das Überschreiben dieser Einstellung in der globalen Konfiguration zulassen und die ausgewählte Version muss zu den zulässigen Optionen gehören.

bestPractices

Aktiviert oder deaktiviert Best Practice-Regeln für den Testlauf. Best Practices verbessern die Zugänglichkeit, sind jedoch nicht Teil formaler Standards. Ihre Organisation muss das Überschreiben dieser Einstellung zulassen, damit sie wirksam wird.

experimentalRules

Aktiviert oder deaktiviert experimentelle Regeln für den Testlauf. Experimentelle Regeln befinden sich noch in der Entwicklung und können zu Fehlalarmen führen. Ihre Organisation muss das Überschreiben dieser Einstellung in der globalen Konfiguration zulassen, damit sie wirksam wird.

Controller Klassen

Die folgenden Klassen erweitern die abstrakte Klasse Controller , damit Sie die Zugänglichkeitsanalyse der Seiten Ihrer Website manuell steuern können.

Controller

abstract class Controller

Die Controller abstrakte Klasse enthält die Methoden zur Steuerung der Seitenanalyse. Jede der konkreten Klassen erweitert diese Klasse, sodass die folgenden Methoden in allen konkreten Klassen verfügbar sind.

analyze

analyze(): Promise<void>

Analysiert die aktuelle Seite auf Barrierefreiheitsfehler. Sie rufen diese Methode auf, nachdem Sie eine Webseite für die Analyse eingerichtet haben (z. B. Werte in ein Formular eingegeben haben) und die automatische Analyse mit der Methode stop oder durch Setzen von autoAnalyze auf false deaktiviert haben.

analyze Rückgabewert

Promise<void>

analyze Äquivalenter Cypress-Befehl

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Sendet alle Ergebnisse des Barrierefreiheitsscans an den axe Developer Hub. Sollte am Ende des Testlaufs aufgerufen werden, um sicherzustellen, dass die Ergebnisse an die axe Developer Hub-Server von Deque gesendet wurden.

flush Rückgaben

Promise<void>

flush Äquivalenter Cypress-Befehl

cy.axeWatcherFlush()

start

start(): Promise<void>

Setzt die automatische Analyse von Webseiten fort. Sie rufen diese Methode auf, wenn Sie die automatische Analyse von Webseiten auf Barrierefreiheitsprobleme fortsetzen möchten.

start Rückgaben

Promise<void>

start Äquivalenter Cypress-Befehl

cy.axeWatcherStart()

stop

stop(): Promise<void>

Stoppt die automatische Analyse von Webseiten. Nachdem Sie die stop Methode aufgerufen haben, können Sie alle weiteren Einstellungen vornehmen, die für Ihre Webseite erforderlich sind, und dann die analyze Methode aufrufen, um die Seite auf Barrierefreiheitsfehler zu überprüfen.

stop Rückgabewert

Promise<void>

stop Äquivalenter Cypress-Befehl

cy.axeWatcherStop()

PlaywrightController

Mit der PlaywrightController Klasse können Sie die Barrierefreiheitsanalyse für Testläufe mit Playwright und Playwright Test manuell steuern. Sie können die automatische Barrierefreiheitsanalyse starten und stoppen und Seiten analysieren, die zusätzliche Einstellungen erfordern.

Weitere Informationen zu Playwright finden Sie in der Playwright-Dokumentation.

Konstruktor

new PlaywrightController(driver: Page): PlaywrightController

Parameter

• driver: Seite

Der driver Wert ist ein Playwright-Objekt Page .

Rückgaben PlaywrightController

Siehe Controller für die in der abstrakten Basisklasse implementierten Methoden.

PuppeteerController

Die PuppeteerController Klasse ermöglicht die manuelle Steuerung Ihrer Testläufe mit Puppeteer. Mit der manuellen Steuerung können Sie zusätzliche Einstellungen vornehmen, die für komplexere Webseiten erforderlich sind.

Weitere Informationen zu Puppeteer finden Sie unter Puppeteer.

Konstruktor

new PuppeteerController(driver: Page): PuppeteerController

Parameter

• driver: Seite

Der driver Wert ist ein Puppeteer Page Objekt.

Gibt zurück PuppeteerController

Siehe Controller für die in der abstrakten Basisklasse implementierten Methoden.

WdioController

Damit können Sie die Testläufe von WebdriverIO und WebdriverIO Testrunner manuell steuern. WdioController Bei Seiten, die zusätzliche Einrichtungs- oder Konfigurationsschritte erfordern, können Sie den automatischen Test beenden und jede Seite, die eine solche Konfiguration erfordert, manuell analysieren.

Konstruktor

new WdioController(driver: Browser): WdioController

Parameter

• driver: Browser

Gibt zurück WdioController

Siehe Controller für die in der abstrakten Basisklasse implementierten Methoden.

WebdriverController

Konstruktor

new WebdriverController(driver: WebDriver): WebdriverController

Parameter

• driver: WebDriver

Der driver Wert ist ein Selenium WebDriver Objekt.

Gibt zurück WebdriverController

Siehe Controller für die in der abstrakten Basisklasse implementierten Methoden.

Benutzerdefinierte Cypress-Befehle

In der Cypress-Browser-Automatisierungsplattform werden die Methoden in den *Controller-Klassen als benutzerdefinierte Befehle implementiert. Weitere Informationen zum Implementieren und Verwenden benutzerdefinierter Befehle finden Sie unter Benutzerdefinierte Befehle auf der Cypress-Dokumentationswebsite.

Die folgenden benutzerdefinierten Befehle sind implementiert. Jeder benutzerdefinierte Befehl gibt zurück Chainable<void> um die Verkettung mit anderen Cypress-Befehlen zu ermöglichen.

Beispiel für einen Cypress-Befehl

Das folgende Beispiel zeigt, wie Sie die Cypress-Befehle des axe Developer Hub aus dem @axe-core/watcher Paket importieren und dann den axeWatcherFlush Befehl am Ende jedes Tests aufrufen (indem Sie ihn in afterEach() einfügen):

// Import the axe-watcher commands.
require('@axe-core/watcher/dist/cypressCommands')

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

Timeouts-Schnittstelle

Das Timeout Objekt (vom Typ Timeouts) in der AxeConfiguration-Schnittstelle ermöglicht es Benutzern, die Timeout-Werte (in Millisekunden) für die jeweiligen Controller-Funktionen oder die benutzerdefinierten Cypress-Befehle zu ändern.

interface Timeouts {
  start?: number
  stop?: number
  flush?: number
  analyze?: number
}