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 genoemd 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 hierin opgenomen AxeConfiguration:

apiKey

(Verplicht) De apiKey waarde is een van de twee eigenschappen (apiKey en projectId) die moeten worden ingesteld in je AxeConfiguration. Je 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 handmatige modus, zie Pagina-analyse beheren.

buildID

(Optioneel) De buildID eigenschap, wanneer niet null, stelt parallelle testrunners in staat om resultaten te genereren die als een enkele testuitvoering in het axe Developer Hub verschijnen. In het geval van parallelle testuitvoeringen zou elke testrunner dezelfde niet-nul buildID string moeten delen, waardoor elke testuitvoering zijn resultaten samenvoegt met bestaande resultaten voor dezelfde buildID en Git commit SHA. Echter, wanneer buildID is null, zullen meerdere testuitvoeringen overschrijven bestaande resultaten die dezelfde Git commit SHA hebben.

Je kunt meestal een bruikbare buildID waarde verkrijgen van je continuous integration-provider. Bijvoorbeeld, je kunt deze waarden gebruiken:

• github.run_id

  Beschikbaar binnen GitHub-workflows. Zie github context in de GitHub-documentatie voor meer informatie.

• CIRCLE_PIPELINE_ID

  Met CircleCI is de bovenstaande waarde beschikbaar vanuit de omgeving van je proces. Zie Ingebouwde omgevingsvariabelen in de CircleCI-documentatie voor meer informatie.

  Andere continuous integration-omgevingsvariabelen die je kunt gebruiken voor buildID:

  Provider	Omgevingsvariabele
  Bitbucket	BITBUCKET_BUILD_NUMBER
  GitLab	CI_PIPELINE_ID
  Jenkins	BUILD_NUMBER

configurationOverrides

(Optioneel) Overschrijft de waarden die zijn 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", "context": "link text patronen in de ", "context": "paragraph excludeUrlPatterns array te voorkomen dat deze geanalyseerd worden.", "context": "paragraph

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

Voorbeelden", "context": "heading level 4

git

(Optioneel) Stel in op ", "context": "paragraph false om te voorkomen dat Watcher Git-informatie verzamelt voor de huidige testrun. Standaard is ", "context": "paragraph true. Dit is nuttig voor projecten die niet in een Git-repository staan of waarbij Git-gegevensverzameling fouten veroorzaakt.", "context": "paragraph

projectId

(Vereist) Geeft de project-ID op die de toegankelijkheidsresultaten van Watcher zal ontvangen. Je project-ID wordt weergegeven met de instructies wanneer je een nieuw project aanmaakt, en je kunt deze ook verkrijgen van de ", "context": "paragraph axe Developer Hub Projectenpagina ", "context": "paragraph .", "context": "paragraph

runContext

(Optioneel) Hiermee kun je kiezen welke elementen zijn inbegrepen en uitgesloten van de toegankelijkheidsanalyse van je pagina.", "context": "paragraph

De waarde van ", "context": "paragraph runContext kan zijn:", "context": "paragraph

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

   axe: {
     runContext: '.main'
   }

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

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

3. Een contextobject dat ", "context": "paragraph include en ", "context": "paragraph exclude eigenschappen bevat (zoals getoond in het bovenstaande voorbeeld). Je kunt ", "context": "paragraph include of ", "context": "paragraph exclude of beide specificeren. Elke ", "context": "paragraph include of exclude kan een enkele CSS-selector zijn of een reeks CSS-selectors:

   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 toe van het axe-core Options type:

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

  important

  Als uw pagina dynamische ID's of klassen gebruikt (element-ID's of klassen die veranderen wanneer de pagina opnieuw wordt geladen), moet u ancestry specificeren als true zodat de axe Developer Hub correct kan detecteren en volgen of toegankelijkheidsproblemen duplicaten zijn omdat de axe Developer Hub standaard verwacht dat element-ID's en klassen hetzelfde blijven tussen testruns.

  Wanneer ancestry trueis, gebruikt de 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 false is voor een iframe-element met een ID van main-iframe (<iframe id="main-iframe" ...>):

  iframe#main-iframe

  Als ancestry truewordt, zou de selector het volledige pad van het rootelement bevatten, en er zijn geen ID's of klassen gespecificeerd:

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

• runOnly: Dit stelt je in staat om te 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 toont 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 string die de regel-ID vertegenwoordigt van de regel die u wilt gebruiken voor toegankelijkheidsanalyse:

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

2. Een reeks strings die de regel-ID's 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 string die kan ruleworden, rules, tag, of tags. De values eigenschap moet een array van strings zijn die de regel(s) of tag(s) vertegenwoordigen die je wilt gebruiken voor toegankelijkheidsanalyse. Het volgende voorbeeld laat zien hoe het runOnly object gebruikt kan worden om toegankelijkheidstesten te beperken tot regels die getagd zijn als wcag2a:

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

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

rules

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

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

sessionId

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

testingTypes

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

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

timeout

(Optioneel) De timeout object (van type Timeouts) in AxeConfiguration stelt de timeout-waarden in milliseconden in voor de respectievelijke controller-methoden (of aangepaste commando's voor Cypress). (Zie de Controller Klassen voor informatie over de controller-klassen en de Cypress Aangepaste Commando's voor informatie over Cypress-aangepaste commando's.) Wanneer een timeout verloopt, mislukt de test met een melding die aangeeft dat de timeout is overschreden. Je kunt de timeout verhogen om de fout te vermijden.

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

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

Configuratiefuncties

De configuratiefuncties die door Watcher worden aangeboden, stellen je in staat om je opstelling aan te passen voor het specifieke testframework en om te bepalen hoe je Watcher wilt inzetten om aan je behoeften te voldoen. Zie AxeConfiguration Interface voor meer informatie.

cypressConfig

Maakt een configuratie voor Cypress.

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

cypressConfig Parameters

• config: Cypress.ConfigOptions & Configuration

  Kruistype van Cypress.ConfigOptions en Configuration.

**Retourneert**: Cypress.ConfigOptions

playwrightConfig

Maakt een configuratie voor Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parameters

• opts: Configuration & LaunchOptions

  Kruistype van LaunchOptions en Configuration.

**Retourneert**: LaunchOptions

playwrightTest

Maakt een configuratie voor Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parameters

• options: Options

  Options is een kruistype 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

  Kruistype van LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions, en Configuration.

**Retourneert**: Options

wdioConfig

Maakt een configuratie voor WebdriverIO.

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

wdioConfig Parameters

• arg: Options

  Options is een kruistype van RemoteOptions en Configuration.

**Retourneert**: RemoteOptions

wdioTestRunner

Maakt een WebdriverIO Testrunner-configuratie aan.

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

wdioTestRunner Parameters

• params: unknown[]

  De params waarde is een van de volgende:

  1. Een array die één waarde bevat, die een intersectietype is van Options.Testrunner en Configuration.
  2. Een array waarbij de eerste arraywaarde een AxeConfiguration is en de tweede waarde een Options.Testrunner.

Retourneert: Options.Testrunner

webdriverConfig

Maakt een Selenium WebDriver-configuratie aan.

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 u in staat te stellen Watcher in te stellen en uw toegankelijkheidstesten te configureren. Zie de volgende sectie, AxeConfiguration Interface, voor meer informatie.

ConfigurationOverrides Interface

De ConfigurationOverrides interface stelt u in staat om de globale configuratie-instellingen van uw organisatie voor individuele testuitvoeringen te overschrijven. Deze eigenschap moet worden gebruikt in overeenstemming met de machtigingen ingesteld in de globale configuratie van uw onderneming.

accessibilityStandard

Stelt de toegankelijksheidsnorm in waartegen getest moet worden. Beschikbare opties:

• ‘Alles’ - Test tegen alle beschikbare normen
• ‘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 toegankelijkheidsnorm; vereist axe-core 4.11.0 of later)

Uw organisatie moet toestaan dat deze instelling in de globale configuratie kan worden overschreven, en de geselecteerde norm moet een van de toegestane opties zijn.

axeCoreVersion

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

• ‘laatste’ - Laatst ondersteunde versie die momenteel gebundeld is 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 geselecteerde versie moet een van de toegestane opties zijn.

bestPractices

Schakelt in of uit beste praktijkenregels voor de test. Beste praktijken verbeteren toegankelijkheid, maar maken geen deel uit van formele normen. Uw organisatie moet toestaan dat deze instelling kan worden overschreven voordat deze effectief wordt.

experimentalRules

Schakelt in of uit experimentele regels voor de test. Experimentele regels zijn nog in ontwikkeling en kunnen vals-positieven genereren. Uw organisatie moet toestaan dat deze instelling in de globale configuratie kan worden overschreven voordat deze effectief wordt.

Controller Klassen

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

Controller

abstract class Controller

De Controller abstracte klasse bevat de methodes voor het beheren van de pagina-analyse. Elk van de concrete klassen breidt deze klasse uit, zodat de volgende methodes 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 voor analyse hebt ingesteld (zoals het invoeren van waarden in een formulier) en de automatische analyse hebt uitgeschakeld met behulp van de stop methode of door autoAnalyze in te stellen op false.

analyze Retourneert

Promise<void>

analyze Equivalent Cypress-opdracht

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Stuurt alle resultaten van de toegankelijkheidsscan naar axe Developer Hub. Dit moet aan het einde van de testuitvoering worden aangeroepen om ervoor te zorgen dat de resultaten naar de servers van Deque's axe Developer Hub zijn verzonden.

flush Retourneert

Promise<void>

flush Equivalent Cypress-opdracht

cy.axeWatcherFlush()

start

start(): Promise<void>

Hervat de automatische analyse van webpagina's. Roep deze methode aan wanneer u de automatische analyse van webpagina's op toegankelijkheidsfouten wilt hervatten.

start Retourneert

Promise<void>

start Equivalent Cypress-opdracht

cy.axeWatcherStart()

stop

stop(): Promise<void>

Stopt de automatische analyse van webpagina's. Nadat u de stop methode hebt aangeroepen, kunt u eventuele aanvullende instellingen voor uw webpagina uitvoeren en vervolgens de analyze methode aanroepen om de pagina op toegankelijkheidsfouten te controleren.

stop Retourneert

Promise<void>

stop Equivalent Cypress-opdracht

cy.axeWatcherStop()

PlaywrightController

De PlaywrightController klasse stelt u in staat de toegankelijkheidsanalyse handmatig te beheren voor testuitvoeringen met Playwright en Playwright Test. U kunt automatische toegankelijkheidsanalyse starten en stoppen en pagina's analyseren die aanvullende installatie 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 in de abstracte basisklasse zijn geïmplementeerd.

PuppeteerController

De PuppeteerController klasse stelt u in staat de testuitvoeringen met Puppeteer handmatig te beheren. Handmatige controle stelt u in staat om extra configuraties te bieden 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 in de abstracte basisklasse zijn geïmplementeerd.

WdioController

De WdioController stelt u in staat om WebdriverIO en WebdriverIO Testrunner testuitvoeringen handmatig te beheren. Voor pagina's die extra configuratie of instellingen vereisen, kunt u automatische tests stoppen en elke pagina handmatig analyseren die dergelijke instellingen vereist.

Constructor

new WdioController(driver: Browser): WdioController

Parameters

• driver: Browser

Retourneert WdioController

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

WebdriverController

Constructor

new WebdriverController(driver: WebDriver): WebdriverController

Parameters

• driver: WebDriver

De driver waarde is een Selenium WebDriver object.

Geeft terug WebdriverController

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

Cypress Aangepaste Commando's

In het Cypress browser-automatiseringsplatform 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 geeft terug Chainable<void> om ketens met andere Cypress commando's mogelijk te maken.

Cypress Commando Voorbeeld

Het volgende voorbeeld toont hoe de axe Developer Hub's Cypress commando's te importeren vanaf het @axe-core/watcher pakket en vervolgens het axeWatcherFlush commando aan het einde van elke test aan te roepen (door het binnenin te plaatsen afterEach()):

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

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

Timeouts Interface

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

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