Riferimento API per la versione JavaScript e TypeScript di Watcher

Questa guida di riferimento descrive le API fornite dal @axe-core/watcher pacchetto (anche noto come Axe Watcher o semplicemente Watcher) per JavaScript e TypeScript.

AxeConfiguration Interfaccia

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

apiKey

(Obbligatorio) Il apiKey valore è una delle due proprietà (apiKey e projectId) che devono essere impostate nel tuo AxeConfiguration. Puoi ottenere il suo valore dalla Pagina Gestisci Chiavi API .

autoAnalyze

(Opzionale) Imposta questo valore su false per evitare che le pagine vengano analizzate automaticamente. Per ulteriori informazioni sulla modalità manuale, vedi Controlla le Tuo Scansioni.

buildID

(Opzionale) La buildID proprietà, quando non è null, permette ai test runner paralleli di generare risultati che appaiono come un unico test run in axe Developer Hub. Nel caso di esecuzioni di test paralleli, ogni test runner dovrebbe condividere lo stesso buildID stringa non nulla, che fa sì che ogni esecuzione di test concatenare i suoi risultati con i risultati esistenti per lo stesso buildID e SHA del commit Git. Tuttavia, quando buildID è null, più esecuzioni di test sovrascrivono i risultati esistenti che hanno lo stesso SHA del commit Git.

Vedi Esecuzione di Test in Parallelo per ulteriori informazioni su come utilizzare buildID con vari fornitori di integrazione continua.

configurationOverrides

(Opzionale) Sostituisce i valori impostati nella configurazione globale. Vedi l' Interfaccia ConfigurationOverrides per ulteriori informazioni.

excludeUrlPatterns

(Opzionale) Impedisce a qualsiasi URL che corrisponda a uno dei modelli minimatch nell'array excludeUrlPatterns dall'essere analizzato.

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

In Escludi URL dall'Analisi puoi trovare una tabella di URL e modelli di esempio per verificare le corrispondenze.

git

(Opzionale) Controlla come Watcher raccoglie i metadati Git per l'esecuzione del test corrente. Accetta uno dei tre valori:

• true (predefinito): Watcher raccoglie automaticamente le informazioni di Git (branch, commit SHA, autore, e altri campi) utilizzando il binario locale di Git.
• false: Disabilita tutta la raccolta di metadati Git. Utilizzare questa opzione nei contesti senza Git o quando la raccolta di dati Git non è necessaria.
• Un GitConfig oggetto: Fornisce metadati Git espliciti e salta completamente l'auto-rilevamento. Qualsiasi campo che ometti verrà impostato automaticamente a null. Utilizzare questo metodo quando i tuoi test vengono eseguiti in un repository separato da quello sotto test, o in ambienti CI dove l'auto-rilevamento Git è inaffidabile.

Vedi Fornitura di Metadati Git per maggiori informazioni.

L' GitConfig oggetto ha i seguenti campi opzionali:

Esempio di utilizzo delle variabili d'ambiente CI per fornire metadati Git espliciti:

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

(Obbligatorio) Specifica l'ID del progetto che riceverà i risultati di accessibilità di Watcher. Il tuo ID progetto viene mostrato con le istruzioni quando crei un nuovo progetto, e puoi anche ottenerlo dalla pagina Progetti di axe Developer Hub .

runContext

(Opzionale) Ti consente di scegliere quali elementi includere ed escludere dall'analisi di accessibilità della tua 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 sopra). Puoi specificare include o exclude o entrambi. Ogni 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 del contesto di axe-core.

runOptions

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

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

  important

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

  Quando ancestry è true, l'Axe Developer Hub utilizza invece la posizione dell'elemento nel DOM tree 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 un 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 sono 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: Questo ti consente di limitare quali regole vengono eseguite specificando nomi o tag. Vedi runOnly sotto per ulteriori informazioni.

• rules: Abilita o disabilita le regole usando la proprietà enabled . Vedi rules sotto per ulteriori informazioni.

Di seguito è mostrato un esempio di runOptions:

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

runOnly

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

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

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

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

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

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

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

• Per altri esempi di utilizzo di runOnly (con axe-core), vedi Esempi di Parametri Opzioni
• Per ulteriori informazioni sui valori dei tag disponibili, vedi Tag di axe-core.
• Per informazioni sulle regole, gli ID delle regole e i tag, vedi Descrizioni delle Regole

rules

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

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

sessionId

(Opzionale) La sessionId proprietà è stata deprecata e non dovrebbe essere utilizzata. Vedi buildID sopra.

testingTypes

(Opzionale) La testingTypes proprietà è un array di stringhe da usare con Cypress per specificare test di componenti o end-to-end (e2e) (o entrambi).

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

timeout

(Opzionale) L'oggetto timeout (di tipo Timeouts) in AxeConfiguration imposta i valori di timeout in millisecondi per i rispettivi metodi del controller (o comandi personalizzati per Cypress). (Vedi le Classi Controller per informazioni sulle classi controller e i Commenti Personalizzati di Cypress per informazioni sui comandi personalizzati di Cypress.) Quando un timeout scade, il test fallisce con un messaggio che indica che il timeout è stato superato. Puoi aumentare la durata del timeout per evitare l'errore.

Questo esempio imposta il timeout del analyze a 8 secondi, flush a 15 secondi, start a 10 secondi e stop a 10 secondi. (I valori predefiniti sono mostrati nella tabella sotto l'interfaccia Timeouts Interfaccia.)

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

Funzioni di Configurazione

Le funzioni di configurazione fornite da Watcher ti permettono di modificare la tua configurazione per il framework di test specificato, oltre a adattare il modo in cui vuoi eseguire Watcher in base ai tuoi bisogni. Vedi Interfaccia AxeConfiguration per ulteriori informazioni.

cypressConfig

Crea una configurazione per Cypress.

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

cypressConfig Parametri

• config: Cypress.ConfigOptions & Configuration

  Tipo intersezione di Cypress.ConfigOptions e Configuration.

Restituisce: Cypress.ConfigOptions

playwrightConfig

Crea una configurazione per Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parametri

• opts: Configuration & LaunchOptions

  Tipo intersezione di LaunchOptions e Configuration.

Restituisce: LaunchOptions

playwrightTest

Crea una configurazione per Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parametri

• options: Options

  Options è un tipo intersezione di Configuration 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 intersezione di LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions, e Configuration.

Restituisce: Options

wdioConfig

Crea una configurazione per WebdriverIO.

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

wdioConfig Parametri

• arg: Options

  Options è un tipo intersezione di RemoteOptions e Configuration.

Restituisce: RemoteOptions

wdioTestRunner

Crea una configurazione per WebdriverIO Testrunner.

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

wdioTestRunner Parametri

• params: unknown[]

  Il params valore è uno dei seguenti:

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

Restituzioni: Options.Testrunner

webdriverConfig

Crea una configurazione Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parametri

• arg: WebDriverArgs

  Un Configuration esteso per includere un membro Selenium WebDriver Options .

Restituzioni: Options

Configuration Interfaccia

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

Tutte le funzioni di configurazione usano questa proprietà per permetterti di configurare il Watcher e impostare i tuoi test di accessibilità. Vedi la sezione successiva, axe AxeConfiguration Interface , per maggiori informazioni.Interfaccia

ConfigurationOverrides L'interfaccia

ti consente di sovrascrivere le impostazioni di configurazione globale della tua organizzazione per i singoli test. Questa proprietà deve essere utilizzata in conformità con le autorizzazioni impostate nella configurazione globale della tua azienda. ConfigurationOverrides Nome

accessibilityStandard

Imposta lo standard di accessibilità da testare. Opzioni disponibili:

• „Tutti“ - Testa contro 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“
• „Testatore Fidato v5“
• „EN 301 549“
• „RGAAv4“ - RGAA versione 4 (standard di accessibilità francese; richiede axe-core 4.11.0 o successivo)

La tua organizzazione deve permettere la sovrascrittura 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 i test. Le opzioni disponibili includono:

• „ultima“ - Ultima versione supportata attualmente inclusa con Axe Watcher
• Versioni specifiche dalla 4.4.0 in poi (es. „4.10.2“, „4.9.1“, ecc.)

La tua organizzazione deve permettere la sovrascrittura di questa impostazione nella configurazione globale e la versione selezionata deve essere tra le opzioni consentite.

bestPractices

Abilita o disabilita le regole di buone pratiche per l'esecuzione del test. Le buone pratiche migliorano l'accessibilità ma non sono parte degli standard formali. La tua organizzazione deve permettere la sovrascrittura di questa impostazione per farla avere effetto.

experimentalRules

Abilita o disabilita le regole sperimentali per l'esecuzione del test. Le regole sperimentali sono ancora in fase di sviluppo e possono produrre falsi positivi. La tua organizzazione deve permettere la sovrascrittura di questa impostazione nella configurazione globale per farla avere effetto.

Controller Classi

Le seguenti classi estendono la Controller classe astratta per consentire 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 delle pagine. Ognuna delle classi concrete estende questa classe, quindi i seguenti metodi sono disponibili in tutte le classi concrete.

analyze

analyze(): Promise<void>

Analizza la pagina corrente per errori di accessibilità. Chiama questo metodo dopo aver configurato una pagina web per l'analisi (come inserire valori in un modulo) e aver disattivato l'analisi automatica utilizzando il stop metodo oppure impostando autoAnalyze su false.

analyze Restituisce

Promise<void>

analyze Comando equivalente in Cypress

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Invia tutti i risultati della scansione di accessibilità all'Axe Developer Hub. Dovrebbe essere chiamato alla fine dell'esecuzione del test per garantire che i risultati siano stati inviati ai server dell'Axe Developer Hub di Deque.

flush Restituisce

Promise<void>

flush Comando equivalente in Cypress

cy.axeWatcherFlush()

start

start(): Promise<void>

Riprende l'analisi automatica delle pagine web. Chiama questo metodo quando vuoi riprendere l'analisi automatica delle pagine web per errori di accessibilità.

start Restituisce

Promise<void>

start Comando equivalente in Cypress

cy.axeWatcherStart()

stop

stop(): Promise<void>

Interrompe l'analisi automatica delle pagine web. Dopo aver chiamato il stop metodo, puoi effettuare qualsiasi ulteriore configurazione necessaria alla tua pagina web e poi chiamare il analyze metodo per verificare la pagina alla ricerca di errori di accessibilità.

stop Restituisce

Promise<void>

stop Comando equivalente in Cypress

cy.axeWatcherStop()

PlaywrightController

La PlaywrightController classe ti permette di controllare manualmente l'analisi di accessibilità per esecuzioni di test con Playwright e Playwright Test. Puoi avviare e interrompere l'analisi automatica di accessibilità e analizzare pagine che richiedono configurazioni aggiuntive.

Per ulteriori informazioni su Playwright, consulta la Documentazione di Playwright.

Costruttore

new PlaywrightController(driver: Page): PlaywrightController

Parametri

• driver: Page

Il driver valore è un oggetto di Page Playwright.

Restituisce PlaywrightController

Vedi Controller per i metodi implementati nella classe base astratta.

PuppeteerController

La PuppeteerController classe consente un controllo manuale delle esecuzioni dei test con Puppeteer. Il controllo manuale consente di fornire configurazioni aggiuntive necessarie per pagine web più complesse.

Per ulteriori informazioni su Puppeteer, consulta Puppeteer.

Costruttore

new PuppeteerController(driver: Page): PuppeteerController

Parametri

• driver: Page

Il driver valore è un oggetto di Page Puppeteer.

Restituisce PuppeteerController

Vedi Controller per i metodi implementati nella classe base astratta.

WdioController

La WdioController permette un controllo manuale delle esecuzioni dei test con WebdriverIO e WebdriverIO Testrunner. Per le pagine che richiedono configurazioni o impostazioni aggiuntive, puoi interrompere i test automatici e analizzare manualmente ciascuna pagina che richiede tali configurazioni.

Costruttore

new WdioController(driver: Browser): WdioController

Parametri

• driver: Browser

Restituisce WdioController

Vedi Controller per i metodi implementati nella classe base astratta.

WebdriverController

Costruttore

new WebdriverController(driver: WebDriver): WebdriverController

Parametri

• driver: WebDriver

Il driver valore è un oggetto Selenium WebDriver .

Restituisce WebdriverController

Vedi Controller per i metodi implementati nella classe base astratta.

Comandi Personalizzati Cypress

Nella piattaforma di automazione browser Cypress, i metodi nelle *Controller classi sono implementati come comandi personalizzati. Vedi Comandi Personalizzati sul sito di documentazione di Cypress per maggiori informazioni su come implementare e utilizzare comandi personalizzati.

I seguenti comandi personalizzati sono implementati. Ogni comando personalizzato restituisce Chainable<void> per permettere il concatenamento con altri comandi Cypress.

Esempio di Comando Cypress

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

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

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

Interfaccia Timeouts

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

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