API-referentie voor de JavaScript- en TypeScript-versie van Watcher

Deze referentiegids beschrijft de API's die worden geleverd door het @axe-core/watcher pakket (ook wel aangeduid als Axe Watcher of gewoon Watcher) voor JavaScript en TypeScript.

AxeConfiguration Interface

De axe eigenschap (een parameter die wordt doorgegeven aan de configuratiefuncties) is de gebruikelijke manier om je AxeConfiguration voor Axe Watcher te configureren voor toegankelijkheidstesten. De volgende eigenschappen zijn opgenomen in AxeConfiguration:

apiKey

(Vereist) De apiKey waarde is een van de twee eigenschappen (apiKey en projectId) die moeten worden ingesteld in uw AxeConfiguration. U kunt de waarde verkrijgen van de Beheer API-sleutels Pagina .

autoAnalyze

(Optioneel) Stel deze waarde in op false om te voorkomen dat pagina's automatisch worden geanalyseerd. Voor meer informatie over de handmatige modus, zie Beheer Je Scans.

buildID

(Optioneel) De buildID eigenschap, wanneer niet null, stelt parallelle testrlopers in staat om resultaten te genereren die worden weergegeven als een enkele testrun in axe Developer Hub. In het geval van parallelle testruns, moet elke testrloper dezelfde niet-nul buildID string delen, waardoor elke testrun zijn resultaten samenvoegt met bestaande resultaten voor dezelfde buildID en Git commit SHA. Echter, wanneer buildID is null, zullen meerdere testruns **overschrijven** bestaande resultaten die dezelfde Git commit SHA hebben.

Zie Tests In Parallel Uitvoeren voor meer informatie over het gebruik van buildID met verschillende continuous integration-providers.

configurationOverrides

(Optioneel) Overschrijft waarden ingesteld in de globale configuratie. Zie de ConfigurationOverrides Interface voor meer informatie.

excludeUrlPatterns

(Optioneel) Voorkomt dat elke URL die overeenkomt met een van de minimatch patronen in de excludeUrlPatterns array wordt geanalyseerd.

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

In URL's Uitsluiten van Analyse kunt u een tabel met URL's en voorbeeldpatronen vinden om overeenkomsten te verifiëren.

git

(Optioneel) Bepaalt hoe Watcher Git-metadata verzamelt voor de huidige testrun. Accepteert een van de drie waarden:

• true (standaard): Watcher verzamelt automatisch Git-informatie (branch, commit SHA, auteur en andere velden) met behulp van de lokale Git-binary.
• false: Schakelt alle verzameling van Git-metadata uit. Gebruik dit wanneer u in omgevingen zonder Git werkt of wanneer het verzamelen van Git-gegevens niet nodig is.
• Een GitConfig object: Biedt expliciete Git-metadata en slaat automatische detectie volledig over. Velden die u weglaat, krijgen standaard de waarde null. Gebruik dit wanneer uw tests worden uitgevoerd in een repository die gescheiden is van de te testen repository, of in CI-omgevingen waar Git-automatische detectie onbetrouwbaar is.

Zie Git-metadata verstrekken voor meer informatie.

Het GitConfig object heeft de volgende optionele velden:

Voorbeeld van het gebruik van CI-omgevingsvariabelen om expliciete Git-metadata te verschaffen:

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

(Verplicht) Geeft het project-ID op dat de Watcher-toegankelijkheidsresultaten zal ontvangen. Uw project-ID wordt weergegeven met de instructies wanneer u een nieuw project aanmaakt en kan ook worden verkregen via de axe Developer Hub Projects Page .

runContext

(Optioneel) Hiermee kunt u kiezen welke elementen wel of niet worden opgenomen in de toegankelijkheidsanalyse van uw pagina.

De waarde van runContext kan zijn:

1. Een enkele CSS-selector voor elementen die in de analyse worden opgenomen:

   axe: {
     runContext: '.main'
   }

2. Een array van CSS-selectors voor elementen die in de analyse worden opgenomen:

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

3. Een contextobject met daarin include en exclude eigenschappen (zoals weergegeven in het bovenstaande voorbeeld). U kunt include of exclude of beide specificeren. Elke include of exclude kan een enkele CSS-selector of een array van CSS-selectors zijn:

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

Meer details zijn beschikbaar in de axe-core Context documentatie.

runOptions

(Optioneel) Het runOptions object staat de volgende subset van eigenschappen van het axe-core Options type toe:

• ancestry: Standaard is false. Als true, de geretourneerde CSS-selectoren bevatten de voorouderelementen van de geretourneerde elementen.

  important

  Als uw pagina dynamische IDs of klassen gebruikt (element IDs of klassen die wijzigen wanneer de pagina opnieuw wordt geladen), moet u ancestry specificeren als true zodat Axe Developer Hub correct kan detecteren en bijhouden of toegankelijkheidsproblemen duplicaten zijn, omdat Axe Developer Hub standaard verwacht dat element IDs en klassen hetzelfde blijven tussen testruns.

  Wanneer ancestry is true, gebruikt Axe Developer Hub in plaats daarvan de positie van het element binnen de DOM-boom om hetzelfde element tussen testruns te lokaliseren.

  Het volgende toont een voorbeeld van een selector wanneer ancestry is false voor een iframe-element met een ID van *main-iframe* (<iframe id="main-iframe" ...>):

  iframe#main-iframe

  Als ancestry is true, zou de selector het volledige pad vanaf het rootelement bevatten en zijn er geen IDs of klassen opgegeven:

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

• runOnly: Hiermee kunt u beperken welke regels worden uitgevoerd door namen of tags op te geven. Zie runOnly hieronder voor meer informatie.

• rules: Schakel regels in of uit met behulp van de enabled eigenschap. Zie rules hieronder voor meer informatie.

Het volgende geeft een voorbeeld van runOptions:

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

runOnly

De runOnly waarde (onderdeel van het runOptions object) kan een van de volgende zijn:

1. Een tekenreeks die de regel-ID vertegenwoordigt van de regel die u wilt gebruiken voor toegankelijkheidsanalyse:

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

2. Een array van tekenreeksen die de regel-IDs vertegenwoordigen van de regels die u wilt gebruiken:

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

3. Een object met type en values eigenschappen. De type waarde is een tekenreeks die kan zijn rule, rules, tag, of tags. De values eigenschap moet een array van tekenreeksen zijn die de regel(s) of tag(s) vertegenwoordigen die u wilt gebruiken voor toegankelijkheidsanalyse. Het volgende voorbeeld toont het gebruik van het runOnly object om toegankelijkheidstests te beperken tot regels getagd als wcag2a:

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

• Voor meer voorbeelden van runOnly gebruik (met axe-core), zie Optieparameter Voorbeelden
• Voor meer informatie over beschikbare tagwaarden, zie axe-core Tags.
• Voor informatie over de regels, regel-ID's en tags, zie Regelbeschrijvingen

rules

De rules waarde (op het runOptions object) stelt u in staat om specifieke regels in te schakelen (enabled: true) of uit te schakelen (enabled: false) tijdens de analyse, zoals hieronder getoond:

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

sessionId

(Optioneel) De sessionId eigenschap is verouderd en moet niet worden gebruikt. Zie buildID hierboven.

testingTypes

(Optioneel) De testingTypes eigenschap is een array van tekenreeksen voor gebruik met Cypress om component- of e2e- (end-to-end) testen te specificeren (of beide).

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

timeout

(Optioneel) De timeout object (van het type Timeouts) in AxeConfiguration stelt de time-outwaarden in milliseconden in voor de respectievelijke controller-methoden (of aangepaste commando's voor Cypress). (Zie de Controller Klassen voor informatie over de controllerklassen en de Cypress Aangepaste Commentaren voor informatie over de aangepaste commando's van Cypress.) Wanneer een time-out verstrijkt, faalt de test met een bericht dat aangeeft dat de time-out is overschreden. U kunt de time-out verhogen om de fout te voorkomen.

Dit voorbeeld stelt de analyze time-out in op 8 seconden, flush op 15 seconden, start op 10 seconden, en stop op 10 seconden. (De standaardwaarden worden weergegeven in de tabel onder Timeouts Interface.)

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

Configuratiefuncties

De configuratiefuncties die door Watcher worden geleverd, stellen u in staat uw setup voor het opgegeven testframework aan te passen en te bepalen hoe u Watcher wilt uitvoeren, zodat deze aan uw behoeften voldoet. Zie AxeConfiguratie Interface voor meer informatie.

cypressConfig

Maakt een configuratie voor Cypress.

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

cypressConfig Parameters

• config: Cypress.ConfigOptions & Configuration

  Kruisverwijzingstype van Cypress.ConfigOptions en Configuration.

Retourneert: Cypress.ConfigOptions

playwrightConfig

Maakt een configuratie voor Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parameters

• opts: Configuration & LaunchOptions

  Kruisverwijzingstype van LaunchOptions en Configuration.

Retourneert: LaunchOptions

playwrightTest

Maakt een configuratie voor Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parameters

• options: Options

  Options is een kruisverwijzingstype van Configuration en LaunchOptions.

Retourneert: ReturnValue

puppeteerConfig

Maakt een configuratie voor Puppeteer.

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

puppeteerConfig Parameters

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  Kruisverwijzingstype van LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions, en Configuration.

Retourneert: Options

wdioConfig

Maakt een WebdriverIO-configuratie.

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

wdioConfig Parameters

• arg: Options

  Options is een kruisverwijzingstype van RemoteOptions en Configuration.

Retourneert: RemoteOptions

wdioTestRunner

Maakt een WebdriverIO Testrunner-configuratie.

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

wdioTestRunner Parameters

• params: unknown[]

  De params waarde is een van:

  1. Een array met één waarde, die een doorsnede-type is van Options.Testrunner en Configuration.
  2. Een array waarbij de eerste waarde een AxeConfiguration is en de tweede waarde een Options.Testrunner.

Retourneert: Options.Testrunner

webdriverConfig

Creëert een Selenium WebDriver-configuratie.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parameters

• arg: WebDriverArgs

  Een Configuration uitgebreid om een Selenium WebDriver Options lid op te nemen.

Retourneert: Options

Configuration Interface

De Configuration interface wordt gebruikt met de configuratiefuncties en bevat één eigenschap:

Alle configuratiefuncties gebruiken deze axe eigenschap om je in staat te stellen Watcher in te stellen en je toegankelijkheidstests te configureren. Zie de volgende sectie, AxeConfiguration-interface, voor meer informatie.

ConfigurationOverrides Interface

De ConfigurationOverrides interface stelt je in staat om de globale configuratie-instellingen van je organisatie te overschrijven voor individuele testruns. Deze eigenschap moet worden gebruikt in overeenstemming met de toestemming die is ingesteld in de globale configuratie van je organisatie.

accessibilityStandard

Stelt de toegankelijkheidsstandaard vast waartegen moet worden getest. Beschikbare opties:

• ‘Alles’ - Test tegen alle beschikbare standaarden
• ‘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 versie 4 (Franse toegankelijkheidsstandaard; vereist axe-core 4.11.0 of later)

Uw organisatie moet toestaan dat deze instelling in de globale configuratie kan worden overschreven, en de gekozen standaard moet behoren tot de toegestane opties.

axeCoreVersion

Specificeert welke versie van axe-core gebruikt moet worden voor testen. Beschikbare opties zijn onder andere:

• ‘latest’ - Laatst ondersteunde versie die momenteel is gebundeld met Axe Watcher
• Specifieke versies vanaf 4.4.0 en later (bijv. ‘4.10.2’, ‘4.9.1’, enz.)

Uw organisatie moet toestaan dat deze instelling in de globale configuratie kan worden overschreven, en de gekozen versie moet behoren tot de toegestane opties.

bestPractices

Schakelt in of uit best practice-richtlijnen voor de test. Best practices verbeteren de toegankelijkheid, maar maken geen deel uit van formele standaarden. Uw organisatie moet toestaan dat deze instelling kan worden overschreven om in werking te treden.

experimentalRules

Schakelt in of uit experimentele regels voor de test. Experimentele regels zijn nog in ontwikkeling en kunnen valse positieven opleveren. Uw organisatie moet toestaan dat deze instelling in de globale configuratie kan worden overschreven om in werking te treden.

Controller Klassen

De volgende klassen breiden de Controller abstracte klasse uit om u in staat te stellen de toegankelijkheidsanalyse van de pagina's van uw website handmatig te beheren.

Controller

abstract class Controller

De Controller abstracte klasse bevat de methoden voor het beheren van de paginabeoordeling. Elk van de concrete klassen breidt deze klasse uit, zodat de volgende methoden beschikbaar zijn in alle concrete klassen.

analyze

analyze(): Promise<void>

Analyseert de huidige pagina op toegankelijkheidsfouten. U roept deze methode aan nadat u een webpagina heeft klaargemaakt voor analyse (zoals het invoeren van waarden in een formulier) en de automatische analyse heeft uitgeschakeld met de stop methode of door autoAnalyze in te stellen op false.

analyze Retourneert

Promise<void>

analyze Equivalent Cypress-commando

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Stuurt alle resultaten van de toegankelijkheidsscan naar Axe Developer Hub. Moet aan het einde van de testrun worden aangeroepen om te zorgen dat de resultaten naar de servers van Deque's Axe Developer Hub zijn verzonden.

flush Retourneert

Promise<void>

flush Equivalent Cypress-commando

cy.axeWatcherFlush()

start

start(): Promise<void>

Hervat de automatische analyse van webpagina's. U roept deze methode aan wanneer u wilt doorgaan met het automatisch analyseren van webpagina's op toegankelijkheidsfouten.

start Retourneert

Promise<void>

start Equivalent Cypress-commando

cy.axeWatcherStart()

stop

stop(): Promise<void>

Stopt de automatische analyse van webpagina's. Nadat u de stop methode hebt aangeroepen, kunt u eventuele extra configuraties uitvoeren die uw webpagina nodig heeft en vervolgens de analyze methode aanroepen om de pagina op toegankelijkheidsfouten te controleren.

stop Retourneert

Promise<void>

stop Equivalent Cypress-commando

cy.axeWatcherStop()

PlaywrightController

De PlaywrightController klasse stelt u in staat om handmatig de toegankelijkheidsanalyse te regelen voor testruns met Playwright en Playwright Test. U kunt de automatische toegankelijkheidsanalyse starten en stoppen en pagina's analyseren die verdere instelling vereisen.

Voor meer informatie over Playwright, zie de Playwright-documentatie.

Constructor

new PlaywrightController(driver: Page): PlaywrightController

Parameters

• driver: Page

De driver waarde is een Playwright Page object.

Retourneert PlaywrightController

Zie Controller voor de methoden die zijn geïmplementeerd in de abstracte basisklasse.

PuppeteerController

De PuppeteerController klasse stelt u in staat om handmatige controle over uw testruns met Puppeteer uit te oefenen. Handmatige controle stelt u in staat om extra configuraties aan te brengen die door complexere webpagina's vereist zijn.

Voor meer informatie over Puppeteer, zie Puppeteer.

Constructor

new PuppeteerController(driver: Page): PuppeteerController

Parameters

• driver: Page

De driver waarde is een Puppeteer Page object.

Retourneert PuppeteerController

Zie Controller voor de methoden die zijn geïmplementeerd in de abstracte basisklasse.

WdioController

De WdioController stelt u in staat om handmatig de WebdriverIO- en WebdriverIO Testrunner testruns te regelen. Voor pagina's die extra configuratie of instelling vereisen, kunt u automatische tests stoppen en elke pagina die dergelijke instelling vereist handmatig analyseren.

Constructor

new WdioController(driver: Browser): WdioController

Parameters

• driver: Browser

Retourneert WdioController

Zie Controller voor de methoden die zijn geïmplementeerd in de abstracte basisklasse.

WebdriverController

Constructor

new WebdriverController(driver: WebDriver): WebdriverController

Parameters

• driver: WebDriver

De driver waarde is een Selenium WebDriver object.

Retourneert WebdriverController

Zie Controller voor de methoden die zijn geïmplementeerd in de abstracte basisklasse.

Cypress Aangepaste Commando's

In het Cypress browserautomatiseringsplatform worden de methoden in de *Controller klassen geïmplementeerd als aangepaste commando's. Zie Aangepaste Commando's op de Cypress documentatiesite voor meer informatie over het implementeren en gebruiken van aangepaste commando's.

De volgende aangepaste commando's zijn geïmplementeerd. Elk aangepast commando retourneert Chainable<void> om ketening met andere Cypress commando's mogelijk te maken.

Cypress Commando Voorbeeld

Het volgende voorbeeld laat zien hoe je de Cypress commando's van de Axe Developer Hub importeert uit het @axe-core/watcher pakket en vervolgens het axeWatcherFlush commando aan het einde van elke test aanroept (door het binnen afterEach()te plaatsen):

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

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

Time-out Interface

Het timeout object (van het type Timeouts) in de AxeConfiguration-interface stelt gebruikers in staat om de time-outwaarden (in milliseconden) te wijzigen voor de respectieve controllerfuncties of de Cypress aangepaste commando's.

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