API-Referenz für die JavaScript- und TypeScript-Version von Watcher

Dieser Referenzleitfaden beschreibt die von der @axe-core/watcher bereitgestellten APIs (auch bekannt als Axe Watcher oder einfach Watcher) für JavaScript und TypeScript.

AxeConfiguration Schnittstelle

Die axe -Eigenschaft (ein Parameter, der an die Konfigurationsfunktionenübergeben wird) ist das übliche Mittel, um Ihre AxeConfiguration für Axe Watcher zur Konfiguration von Accessibility-Tests zu ändern. Die folgenden Eigenschaften sind in AxeConfigurationenthalten:

apiKey

(Erforderlich) Der apiKey -Wert ist eine von zwei Eigenschaften (apiKey und projectId), die in Ihrer AxeConfigurationfestgelegt werden müssen. Sie können seinen Wert von der API-Schlüsselverwaltungsseite erhalten.

autoAnalyze

(Optional) Setzen Sie diesen Wert auf false , um zu verhindern, dass Seiten automatisch analysiert werden. Weitere Informationen zum manuellen Modus finden Sie unter Controlling Ihrer Scans.

buildID

(Optional) Die buildID Eigenschaft, wenn nicht null, ermöglicht es parallelen Testrunnern, Ergebnisse zu generieren, die als ein einziger Testlauf im axe Developer Hub erscheinen. Im Fall paralleler Testläufe sollte jeder Testrunner dieselbe nicht-null buildID -Zeichenfolge teilen, wodurch jeder Testlauf seine Ergebnisse mit vorhandenen Ergebnissen für denselben buildID und Git-Commit-SHA verkettet. Wenn jedoch buildID ist null, überschreiben mehrere Testläufe bestehende Ergebnisse, die denselben Git-Commit-SHA haben.

Siehe Tests parallel ausführen , um mehr darüber zu erfahren, wie Sie buildID mit verschiedenen Anbietern für kontinuierliche Integration nutzen können.

configurationOverrides

(Optional) Überschreibt Werte, die in der globalen Konfigurationgesetzt sind. Siehe die ConfigurationOverrides-Schnittstelle für weitere Informationen.

excludeUrlPatterns

(Optional) Verhindert, dass eine URL, die einem der minimatch -Muster in der excludeUrlPatterns Liste entspricht, analysiert wird.

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

In URLs von der Analyse ausschließen finden Sie eine Tabelle mit URLs und Beispielmustern, um Übereinstimmungen zu überprüfen.

git

(Optional) Steuert, wie Watcher Git-Metadaten für den aktuellen Testlauf sammelt. Akzeptiert einen von drei Werten:

• true (Standard): Watcher sammelt automatisch Git-Informationen (Branch, Commit-SHA, Autor und andere Felder) mit dem lokalen Git-Binary.
• false: Deaktiviert die Sammlung aller Git-Metadaten. Verwenden Sie dies in Umgebungen ohne Git oder wenn die Sammlung von Git-Daten nicht benötigt wird.
• Ein GitConfig -Objekt: Liefert explizite Git-Metadaten und überspringt die automatische Erkennung vollständig. Alle Felder, die Sie auslassen, werden standardmäßig auf nullgesetzt. Verwenden Sie dies, wenn Ihre Tests in einem Repository laufen, das von dem zu testenden Repository getrennt ist, oder in CI-Umgebungen, in denen die automatische Git-Erkennung unzuverlässig ist.

Siehe Bereitstellen von Git-Metadaten für weitere Informationen.

Das GitConfig -Objekt hat die folgenden optionalen Felder:

Beispiel zur Verwendung von CI-Umgebungsvariablen zur Angabe expliziter Git-Metadaten:

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: '<your-project-id>',
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    defaultBranch: 'main'
  }
}

projectId

(Erforderlich) Gibt die Projekt-ID an, die die Watcher-Zugänglichkeitsberichte erhalten wird. Ihre Projekt-ID wird zusammen mit den Anweisungen angezeigt, wenn Sie ein neues Projekt erstellen, und Sie können sie auch von der axe Developer Hub-Projektseite abrufen.

runContext

(Optional) Ermöglicht Ihnen die Wahl, welche Elemente in die Barrierefreiheitsanalyse Ihrer Seite ein- und ausgeschlossen werden.

Der Wert von runContext kann sein:

1. Ein einzelner CSS-Selektor für die einzuschließenden Elemente in der Analyse:

   axe: {
     runContext: '.main'
   }

2. Ein Array von CSS-Selektoren für die einzuschließenden Elemente in der Analyse:

   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 Details finden Sie im axe-core-Kontextdokumentation.

runOptions

(Optional) Das runOptions Objekt erlaubt den folgenden Teilbereich von Eigenschaften aus dem axe-core- Options -Typ:

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

  important

  Wenn Ihre Seite dynamische IDs oder Klassen (Element-IDs oder -Klassen, die sich bei jedem Neuladen der Seite ändern) verwendet, müssen Sie ancestry als true angeben, damit Axe Developer Hub ordnungsgemäß erkennen und verfolgen kann, ob Barrierefreiheitsprobleme Duplikate sind, da Axe Developer Hub standardmäßig erwartet, dass sich Element-IDs und -Klassen zwischen den Testläufen nicht ändern.

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

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

  iframe#main-iframe

  Wenn ancestry ist true, würde der Selektor den gesamten Pfad vom Wurzelelement aus 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: Dies ermöglicht es Ihnen, durch Angabe von Namen oder Tags einzuschränken, welche Regeln ausgeführt werden. Siehe runOnly unten für weitere Informationen.

• rules: Regeln aktivieren oder deaktivieren mit der enabled Eigenschaft. Siehe rules unten für weitere Informationen.

Das folgende zeigt ein Beispiel von runOptions:

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

runOnly

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

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

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

2. Ein Array von Strings, das die Regel-IDs der Regeln darstellt, die Sie verwenden möchten:

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

3. Ein Objekt mit type und values Eigenschaften. Der type Wert ist ein String, der rulesein kann, rules, tag, oder tags. Die values Eigenschaft muss ein Array von Strings sein, das die Regel(n) oder Tag(s) repräsentiert, die Sie für die Barrierefreiheitsanalyse verwenden möchten. Das folgende Beispiel zeigt, wie Sie das runOnly Objekt verwenden, um die Barrierefreiheitsprüfung auf Regeln einzuschränken, die als wcag2agekennzeichnet sind:

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

• Für weitere Beispiele der runOnly Nutzung (mit axe-core) siehe Beispiele für Optionsparameter
• Für weitere Informationen zu verfügbaren Tag-Werten siehe axe-core Tags.
• Für Informationen zu den Regeln, Regel-IDs und Tags siehe Regelbeschreibungen

rules

Der rules Wert (am runOptions Objekt) ermöglicht es Ihnen, spezifische Regeln während der Analyse zu aktivieren (enabled: true) oder zu deaktivieren (enabled: false), wie unten gezeigt:

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

sessionId

(Optional) Die sessionId Eigenschaft ist veraltet und sollte nicht mehr verwendet werden. Siehe buildID oben.

testingTypes

(Optional) Die testingTypes Eigenschaft ist ein Array von Strings zur Verwendung mit Cypress, um Komponenten- oder End-to-End-Tests (oder beides) zu spezifizieren.

axe: {
  testingTypes: ['e2e', 'component']
}

timeout

(Optional) Das timeout Objekt (vom Typ Timeouts) in AxeConfiguration legt die Zeitlimitwerte in Millisekunden für die jeweiligen Controllermethoden (oder benutzerdefinierten Befehle für Cypress) fest. (Siehe die Controller-Klassen für Informationen zu den Controller-Klassen und die Cypress Benutzerdefinierte Kommentare für Informationen zu benutzerdefinierten Befehlen in Cypress.) Wenn ein Zeitlimit abläuft, schlägt der Test mit einer Nachricht fehl, die darauf hinweist, dass das Zeitlimit überschritten wurde. Sie können das Zeitlimit erhöhen, um den Fehler zu vermeiden.

Dieses Beispiel setzt das analyze Zeitlimit auf 8 Sekunden, flush auf 15 Sekunden, start auf 10 Sekunden und stop auf 10 Sekunden. (Die Standardwerte sind in der Tabelle unter Timeouts Schnittstelledargestellt.)

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

Konfigurationsfunktionen

Die von Watcher bereitgestellten Konfigurationsfunktionen ermöglichen es Ihnen, Ihr Setup für das angegebene Testframework zu modifizieren und anzupassen, wie Sie Watcher ausführen möchten, um Ihren Anforderungen gerecht zu werden. Siehe Axe-Konfigurationsschnittstelle für weitere Informationen.

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 Configuration.

**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 Configuration.

**Gibt zurück**: LaunchOptions

playwrightTest

Erstellt eine Konfiguration für Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parameter

• options: Options

  Options ist ein Schnittmengentyp von Configuration 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

  Schnittmengentyp von LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions, und Configuration.

**Gibt zurück**: Options

wdioConfig

Erstellt eine WebdriverIO-Konfiguration.

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

wdioConfig Parameter

• arg: Options

  Options ist ein Schnittmengentyp von RemoteOptions und Configuration.

**Gibt zurück**: RemoteOptions

wdioTestRunner

Erstellt eine WebdriverIO Testrunner-Konfiguration.

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

wdioTestRunner Parameter

• params: unknown[]

  Der params -Wert ist einer der folgenden:

  1. Ein Array, das einen Wert enthält, der ein Schnittmengentyp von Options.Testrunner und Configurationist.
  2. Ein Array, bei dem der erste Arraywert ein AxeConfiguration und der zweite Wert ein Options.Testrunnerist.

**Rückgaben**: Options.Testrunner

webdriverConfig

Erstellt eine Selenium WebDriver-Konfiguration.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parameter

• arg: WebDriverArgs

  Ein Configuration , das um einen Selenium WebDriver- Options -Mitglied erweitert ist.

**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. Siehe den nächsten Abschnitt, AxeConfiguration Interface, für weitere Informationen.

ConfigurationOverrides Schnittstelle

Die ConfigurationOverrides -Schnittstelle ermöglicht es Ihnen, die globalen Konfigurationseinstellungen Ihrer Organisation für einzelne Testrunden zu überschreiben. Diese Eigenschaft muss in Übereinstimmung mit den Berechtigungen verwendet werden, die in der globalen Konfiguration Ihres Unternehmens festgelegt sind.

accessibilityStandard

Legt den Barrierefreiheitsstandard fest, gegen den getestet werden soll. Verfügbare Optionen:

• „Alle“ - Testet 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“
• „RGAAv4“ - RGAA Version 4 (Französischer Barrierefreiheitsstandard; erfordert axe-core 4.11.0 oder neuer)

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

axeCoreVersion

Gibt an, welche Version von axe-core für das Testen verwendet werden soll. Verfügbare Optionen umfassen:

• „neueste“ - Neueste unterstützte Version, die derzeit mit Axe Watcher gebündelt ist
• Spezifische Versionen ab 4.4.0 und später (z.B. „4.10.2“, „4.9.1“, etc.)

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

bestPractices

Aktiviert oder deaktiviert Best-Practice-Regeln für den Testdurchlauf. Best Practices verbessern die Barrierefreiheit, sind aber kein Teil formaler Standards. Ihre Organisation muss das Überschreiben dieser Einstellung erlauben, damit sie wirksam wird.

experimentalRules

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

Controller Klassen

Die folgenden Klassen erweitern die Controller abstrakte Klasse, um Ihnen die manuelle Steuerung der Barrierefreiheitsanalyse der Seiten Ihrer Website zu ermöglichen.

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. Diese Methode wird aufgerufen, nachdem Sie eine Webseite für die Analyse vorbereitet haben (z.B. Werte in ein Formular eingegeben haben) und die automatische Analyse mit der stop Methode oder durch Setzen von autoAnalyze auf falsedeaktiviert haben.

analyze Gibt zurück

Promise<void>

analyze Entsprechender Cypress-Befehl

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Sendet alle Ergebnisse des Barrierefreiheits-Scans an 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 Gibt zurück

Promise<void>

flush Entsprechender Cypress-Befehl

cy.axeWatcherFlush()

start

start(): Promise<void>

Setzt die Auto-Analyse von Webseiten fort. Diese Methode wird aufgerufen, wenn Sie die Auto-Analyse von Webseiten auf Barrierefreiheitsfehler fortsetzen möchten.

start Gibt zurück

Promise<void>

start Entsprechender Cypress-Befehl

cy.axeWatcherStart()

stop

stop(): Promise<void>

Stoppt die Auto-Analyse von Webseiten. Nachdem Sie die stop Methode aufgerufen haben, können Sie weitere notwendige Setups für Ihre Webseite durchführen und dann die analyze Methode aufrufen, um die Seite auf Barrierefreiheitsfehler zu überprüfen.

stop Gibt zurück

Promise<void>

stop Entsprechender Cypress-Befehl

cy.axeWatcherStop()

PlaywrightController

Die PlaywrightController Klasse ermöglicht es Ihnen, die Barrierefreiheitsanalyse für Testruns mit Playwright und Playwright Test manuell zu steuern. Sie können die automatische Barrierefreiheitsanalyse starten und stoppen sowie Seiten analysieren, die ein zusätzliches Setup erfordern.

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

Konstruktor

new PlaywrightController(driver: Page): PlaywrightController

Parameter

• driver: Page

Der driver Wert ist ein Playwright Page Objekt.

Gibt zurück PlaywrightController

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

PuppeteerController

Die PuppeteerController Klasse ermöglicht die manuelle Steuerung Ihrer Testruns mit Puppeteer. Manuelle Steuerung ermöglicht es Ihnen, zusätzliche Setups bereitzustellen, die von komplexeren Webseiten benötigt werden.

Weitere Informationen zu Puppeteer finden Sie unter Puppeteer.

Konstruktor

new PuppeteerController(driver: Page): PuppeteerController

Parameter

• driver: Page

Der driver Wert ist ein Puppeteer Page Objekt.

Gibt zurück PuppeteerController

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

WdioController

Der WdioController erlaubt es Ihnen, Testruns mit WebdriverIO und WebdriverIO Testrunner manuell zu steuern. Für Seiten, die zusätzliche Setups oder Konfigurationen erfordern, können Sie den automatischen Test stoppen und jede Seite manuell analysieren, die ein solches Setup benötigt.

Konstruktor

new WdioController(driver: Browser): WdioController

Parameter

• driver: Browser

Rückgaben 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.

Rückgaben WebdriverController

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

Cypress Custom Commands

In der Cypress-Browser-Automatisierungsplattform werden die Methoden in den *Controller Klassen als benutzerdefinierte Befehle implementiert. Siehe Custom Commands auf der Cypress-Dokumentationsseite für weitere Informationen über die Implementierung und Nutzung benutzerdefinierter Befehle.

Die folgenden benutzerdefinierten Befehle werden implementiert. Jeder benutzerdefinierte Befehl gibt Chainable<void> zurück, um das Verketten mit anderen Cypress-Befehlen zu ermöglichen.

Cypress-Befehl Beispiel

Das folgende Beispiel zeigt, wie die Cypress-Befehle des Axe Developer Hub aus dem @axe-core/watcher Paket importiert und dann der axeWatcherFlush Befehl am Ende jedes Tests aufgerufen wird (indem er in afterEach()platziert wird):

// Import the axe-watcher commands.
require('@axe-core/watcher/cypress/support')

// 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 Cypress Custom Commands zu ändern.

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