Riferimento API

Questa guida di riferimento descrive le API fornite dal pacchetto (chiamato anche axe Watcher o semplicemente Watcher). @axe-core/watcher ** **

AxeConfiguration Interfaccia

La proprietà (un parametro passato alle [funzioni di configurazione]) è il mezzo usuale per modificare il tuo axe Watcher per configurare i test di accessibilità. axe (#configuration-functions) AxeConfiguration Le seguenti proprietà sono contenute in AxeConfiguration:

apiKey

Il apiKey valore è l'unica proprietà che deve essere impostata nel tuo AxeConfiguration. Puoi ottenerne il valore dalla pagina Progetti. Per ulteriori informazioni, vedere Gestione progetti .

autoAnalyze

Impostare questo valore su false per impedire l'analisi automatica delle pagine. Per ulteriori informazioni sulla modalità manuale, vedere Controllo del momento in cui si verifica l'analisi della pagina.

buildID

La proprietà opzionale buildID , quando non null, consente ai runner di test paralleli di generare risultati che vengono visualizzati come un'unica esecuzione di test in axe Developer Hub. Nel caso di esecuzioni di test parallele, ogni runner di test dovrebbe condividere la stessa stringa non nulla buildID , il che fa sì che ogni esecuzione di test concateni i suoi risultati con i risultati esistenti per lo stesso buildID e con l'SHA del commit Git. Tuttavia, quando buildID è null, più esecuzioni di test sovrascrivono i risultati esistenti che hanno lo stesso SHA di commit Git.

Di solito è possibile ottenere un valore utilizzabile dal proprio fornitore di integrazione continua. buildID Ad esempio, puoi utilizzare questi valori:

• github.run_id

  Disponibile nei flussi di lavoro di GitHub. Per maggiori informazioni, consultare github context nella documentazione di GitHub.

• CIRCLE_PIPELINE_ID

  Con CircleCI, il valore sopra indicato è disponibile nell'ambiente del processo. Per ulteriori informazioni, vedere Variabili di ambiente integrate nella documentazione di CircleCI.

  Altre variabili d'ambiente di integrazione continua che puoi utilizzare per buildID:

  Fornitore	Variabile d'ambiente
  Bitbucket	BITBUCKET_BUILD_NUMBER
  GitLab	CI_PIPELINE_ID
  Jenkins	BUILD_NUMBER

configurationOverrides

(Facoltativo) Sostituisce i valori impostati nella configurazione globale. Per ulteriori informazioni, consultare l'[interfaccia ConfigurationOverrides].(#configurationoverrides-interface)

excludeUrlPatterns

(Facoltativo) Impedisce l'analisi di qualsiasi URL che corrisponda a uno qualsiasi dei modelli minimatch nell'array excludeUrlPatterns .

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

Esempi

runContext

(Facoltativo) Consente di scegliere quali elementi includere ed escludere dall'analisi di accessibilità della pagina.

Il valore di runContext può essere:

1. Un singolo selettore CSS per gli elementi da includere nell'analisi:

   axe: {
     runContext: '.main'
   }

2. Un array di selettori CSS per gli elementi da includere nell'analisi:

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

3. Un oggetto di contesto contenente include e exclude proprietà (come mostrato nell'esempio precedente). Puoi specificare include o exclude o entrambi. Ciascuno include o exclude può essere un singolo selettore CSS o un array di selettori CSS:

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

Ulteriori dettagli sono disponibili nella documentazione di contesto axe-core.

runOptions

(Facoltativo) L'oggetto runOptions consente il seguente sottoinsieme di proprietà del tipo axe-core Options :

• ancestry: Il valore predefinito è false. Se true, i selettori CSS restituiti includono gli elementi antenati degli elementi restituiti.

  important

  Se la tua pagina utilizza ID o classi dinamiche (ID o classi di elementi che cambiano ogni volta che la pagina viene ricaricata), devi specificare questo ancestry come true in modo che axe Developer Hub possa rilevare e monitorare correttamente se i problemi di accessibilità sono duplicati , poiché per impostazione predefinita axe Developer Hub si aspetta che gli ID e le classi degli elementi rimangano gli stessi tra un'esecuzione e l'altra dei test.

  Quando ancestry è true, axe Developer Hub utilizza invece la posizione dell'elemento all'interno dell'albero DOM per individuare lo stesso elemento tra le esecuzioni dei test.

  Di seguito è mostrato un esempio di un selettore quando ancestry è false per un elemento iframe con ID di main-iframe (<iframe id="main-iframe" ...>):

  iframe#main-iframe

  Se ancestry è true, il selettore includerebbe l'intero percorso dall'elemento radice e non ci sarebbero ID o classi specificati:

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

• runOnly: consente di limitare le regole da eseguire specificando nomi o tag. Per ulteriori informazioni, vedere runOnly di seguito.

• rules: Abilita o disabilita le regole utilizzando la enabled proprietà. Per maggiori informazioni, consultare le regole seguenti.

Di seguito è riportato un esempio di runOptions:

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

runOnly

Il valore (parte dell'oggetto [runOptions] runOnly ) può essere uno dei seguenti:(#runoptions)

1. Una stringa che rappresenta l'ID della regola che desideri utilizzare per l'analisi dell'accessibilità:

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

2. Un array di stringhe che rappresentano gli ID delle regole che desideri utilizzare:

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

3. Un oggetto con type e values proprietà. Il valore type è una stringa che può essere regola, regola, tag o tags. La proprietà values può essere una stringa o un array di stringhe che rappresentano la regola o i tag che desideri utilizzare per l'analisi dell'accessibilità. L'esempio seguente mostra come utilizzare l'oggetto runOnly per limitare i test di accessibilità alle regole contrassegnate come wcag2a:

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

• Per ulteriori esempi di utilizzo (con axe-core), vedere [Esempi di parametri delle opzioni] runOnly (https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter-examples)
• Per maggiori informazioni sui valori dei tag disponibili, vedere Tag axe-core.
• Per informazioni sulle regole, gli ID delle regole e i tag, vedere Descrizioni delle regole

rules

Il rules valore (sull' runOptions oggetto) consente di abilitare (enabled: true) o disabilitare (enabled: false) regole specifiche durante l'analisi, come mostrato di seguito:

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

sessionId

La sessionId proprietà è stata deprecata e non dovrebbe essere utilizzata. Vedere buildID sopra.

timeout

L' timeout oggetto (di tipo Timeouts) in AxeConfiguration imposta i valori di timeout in millisecondi per i rispettivi metodi del controller (o comandi personalizzati per Cypress). (Vedere Classi controller per informazioni sulle classi controller e Comandi personalizzati Cypress per informazioni sui comandi personalizzati Cypress.) Allo scadere del timeout, il test fallisce e viene visualizzato un messaggio che indica che il timeout è stato superato. Per evitare l'errore è possibile aumentare il timeout.

In questo esempio il timeout viene impostato su analyze 8 secondi, flush 15 secondi, start 10 secondi e stop 10 secondi. (I valori predefiniti sono mostrati nella tabella sotto Interfaccia Timeouts.)

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

Classi del controller

Funzioni di configurazione

Le funzioni di configurazione fornite da Watcher consentono di modificare la configurazione per il framework di test specificato e di adattare il modo in cui si desidera eseguire Watcher in base alle proprie esigenze. Per ulteriori informazioni, vedere Interfaccia AxeConfiguration .

cypressConfig

Crea una configurazione per Cypress.

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

cypressConfig Parametri

• config: Cypress.ConfigOptions & Configuration

  Tipo di intersezione di Cypress.ConfigOptions e Configurazione.

Restituisce: Cypress.ConfigOptions

playwrightConfig

Crea una configurazione per Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parametri

• opts: Configuration & LaunchOptions

  Tipo di intersezione di LaunchOptions e Configurazione.

Restituisce: LaunchOptions

playwrightTest

Crea una configurazione per Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parametri

• options: Options

  Options è un tipo di intersezione di Configurazione e LaunchOptions.

Restituisce: ReturnValue

puppeteerConfig

Crea una configurazione per Puppeteer.

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

puppeteerConfig Parametri

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  Tipo di intersezione di LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions e Configurazione.

Restituisce: Options

wdioConfig

Crea una configurazione WebdriverIO.

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

wdioConfig Parametri

• arg: Options

  Options è un tipo di intersezione di RemoteOptions e Configurazione.

Restituisce: RemoteOptions

wdioTestRunner

Crea una configurazione WebdriverIO Testrunner.

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

wdioTestRunner Parametri

• params: sconosciuto[]

  Il valore params è uno dei seguenti:

  1. Un array contenente un valore, che è un tipo di intersezione di Options.Testrunner e Configuration.
  2. Un array in cui il primo valore è un AxeConfiguration e il secondo valore è un Options.Testrunner.

Restituisce: Options.Testrunner

webdriverConfig

Crea una configurazione Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parametri

• arg: WebDriverArgs

  Una Configurazione estesa per includere un membro Selenium WebDriver Options .

Restituisce: Options

Configuration Interfaccia

L' Configuration interfaccia viene utilizzata con le funzioni di configurazione e contiene una proprietà:

Tutte le funzioni di configurazione utilizzano questa axe proprietà per consentirti di impostare Watcher e configurare i test di accessibilità. Per ulteriori informazioni, consultare la sezione successiva, Interfaccia AxeConfiguration.

ConfigurationOverrides Interfaccia

L'interfaccia consente di ignorare le impostazioni di configurazione globali dell'organizzazione per le singole esecuzioni dei test. ConfigurationOverrides Questa proprietà deve essere utilizzata in conformità con le autorizzazioni impostate nella configurazione globale della tua azienda.

accessibilityStandard

Imposta lo standard di accessibilità da utilizzare per il test. Opzioni disponibili:

• 'Tutti' - Esegue test su tutti gli standard disponibili
• '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'
• 'Tester attendibile v5'
• 'EN 301 549'

L'organizzazione deve consentire l'override di questa impostazione nella configurazione globale e lo standard selezionato deve essere tra le opzioni consentite.

axeCoreVersion

Specifica quale versione di axe-core utilizzare per il test. Le opzioni disponibili includono:

• 'latest' - Ultima versione supportata attualmente in bundle con axe Watcher
• Versioni specifiche dalla 4.4.0 in poi (ad esempio, '4.10.2', '4.9.1', ecc.)

L'organizzazione deve consentire l'override di questa impostazione nella configurazione globale e la versione selezionata deve essere tra le opzioni consentite.

bestPractices

Abilita o disabilita le regole delle best practice per l'esecuzione del test. Le buone pratiche migliorano l'accessibilità ma non fanno parte degli standard formali. Affinché questa impostazione abbia effetto, la tua organizzazione deve consentire la modifica.

experimentalRules

Abilita o disabilita le regole sperimentali per l'esecuzione del test. Le regole sperimentali sono ancora in fase di sviluppo e potrebbero generare falsi positivi. Affinché questa impostazione abbia effetto, la tua organizzazione deve consentire la sovrascrittura nella configurazione globale .

Controller Classi

Le seguenti classi estendono la classe astratta Controller per consentirti di controllare manualmente l'analisi dell'accessibilità delle pagine del tuo sito web.

Controller

abstract class Controller

La Controller classe astratta contiene i metodi per controllare l'analisi della pagina. Ciascuna delle classi concrete estende questa classe, pertanto i seguenti metodi sono disponibili in tutte le classi concrete.

analyze

analyze(): Promise<void>

Analizza la pagina corrente per individuare errori di accessibilità. Questo metodo viene chiamato dopo aver impostato una pagina web per l'analisi (ad esempio, dopo aver inserito valori in un modulo) e aver disattivato l'analisi automatica utilizzando il metodo stop o impostando autoAnalyze su false.

analyze Restituisce

Promise<void>

analyze Comando equivalente di Cypress

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Invia tutti i risultati della scansione di accessibilità ad axe Developer Hub. Dovrebbe essere chiamato al termine dell'esecuzione del test per garantire che i risultati siano stati inviati ai server axe Developer Hub di Deque.

flush Restituisce

Promise<void>

flush Comando equivalente di Cypress

cy.axeWatcherFlush()

start

start(): Promise<void>

Riprende l'analisi automatica delle pagine web. Questo metodo viene chiamato quando si desidera riprendere l'analisi automatica delle pagine web per individuare errori di accessibilità.

start Restituisce

Promise<void>

start Comando equivalente di Cypress

cy.axeWatcherStart()

stop

stop(): Promise<void>

Arresta l'analisi automatica delle pagine web. Dopo aver chiamato il metodo stop , puoi effettuare qualsiasi configurazione aggiuntiva di cui la tua pagina web potrebbe aver bisogno e quindi chiamare il metodo analyze per verificare la presenza di errori di accessibilità nella pagina.

stop Restituisce

Promise<void>

stop Comando equivalente di Cypress

cy.axeWatcherStop()

PlaywrightController

La classe PlaywrightController consente di controllare manualmente l'analisi dell'accessibilità per le esecuzioni di test con Playwright e Playwright Test. È possibile avviare e interrompere l'analisi automatica dell'accessibilità e analizzare le pagine che richiedono una configurazione aggiuntiva.

Per maggiori informazioni su Playwright, consulta la Documentazione su Playwright.

Costruttore

new PlaywrightController(driver: Page): PlaywrightController

Parametri

• driver: Pagina

Il valore driver è un oggetto Playwright Page .

Restituzioni PlaywrightController

Vedere Controller per i metodi implementati nella classe base astratta.

PuppeteerController

La classe PuppeteerController consente il controllo manuale delle esecuzioni di test con Puppeteer. Il controllo manuale consente di effettuare impostazioni aggiuntive richieste dalle pagine web più complesse.

Per maggiori informazioni su Puppeteer, vedere Puppeteer.

Costruttore

new PuppeteerController(driver: Page): PuppeteerController

Parametri

• driver: Pagina

Il valore è un oggetto Puppeteer [Page]. driver (https://pptr.dev/api/puppeteer.page)

Restituisce PuppeteerController

Vedere Controller per i metodi implementati nella classe base astratta.

WdioController

WdioController Questo consente di controllare manualmente l'esecuzione dei test di WebdriverIO e WebdriverIO Testrunner. Per le pagine che richiedono impostazioni o configurazioni aggiuntive, è possibile interrompere i test automatici e analizzare manualmente ogni pagina che richiede tale configurazione.

Costruttore

new WdioController(driver: Browser): WdioController

Parametri

• driver: Browser

Restituisce WdioController

Vedere Controller per i metodi implementati nella classe base astratta.

WebdriverController

Costruttore

new WebdriverController(driver: WebDriver): WebdriverController

Parametri

• driver: WebDriver

Il valore è un oggetto Selenium [WebDriver]. driver (https://www.selenium.dev/documentation/webdriver/)

Restituisce WebdriverController

Vedere Controller per i metodi implementati nella classe base astratta.

Comandi personalizzati Cypress

Nella piattaforma di automazione del browser Cypress, i metodi nelle classi *Controller sono implementati come comandi personalizzati. Per ulteriori informazioni sull'implementazione e l'utilizzo di comandi personalizzati, vedere Comandi personalizzati sul sito della documentazione di Cypress.

Sono implementati i seguenti comandi personalizzati. Ogni comando personalizzato restituisce Chainable<void> per consentire il concatenamento con altri comandi Cypress.

Esempio di comando Cypress

L'esempio seguente mostra come importare i comandi Cypress di axe Developer Hub dal pacchetto @axe-core/watcher e quindi richiamare il comando axeWatcherFlush alla fine di ogni test (inserendolo all'interno di afterEach()):

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

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

Interfaccia Timeouts

L'oggetto timeout (di tipo Timeouts) nell'interfaccia AxeConfiguration consente agli utenti di modificare i valori di timeout (in millisecondi) per le rispettive funzioni del controller o per i comandi personalizzati Cypress.

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