Analizzare le Pagine Utilizzando i File Spec
Come utilizzare i sottocomandi spec e bulk-spec per analizzare le pagine usando i file spec
Un file spec è un file JSON o YAML che definisce un elenco di pagine web e le azioni del browser da eseguire su ciascuna pagina prima di analizzare eventuali problemi di accessibilità. Usa axe spec per eseguire un singolo file spec, oppure axe bulk-spec per elaborare una directory di file spec.
Il Comando axe spec
axe spec <spec-file> <output-dir> [options]Il <output-dir> è dove vengono salvati i risultati JSON. Se omesso, i risultati vengono salvati nella directory di lavoro corrente.
Struttura del File Spec
axe spec ./axe-workflow.yaml ./axe-results --format htmlUn file spec definisce uno o più progetti, ciascuno con un elenco di pagine da analizzare e azioni opzionali da eseguire su ogni pagina.
Esempio YAML
Progetto
projects:
- name: deque.com
id: deque.com
metadata:
products:
- CLI
environment:
- Prod
globalActions:
- dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept"
pageList:
- name: Deque search
url: https://www.deque.com/
actions:
- type "axe" into element "#searchform input"
- click element "#searchform button"
- wait for element ".m-search-page" to be found
- analyze
- name: Axe Dashboard
url: https://axe.deque.com/Proprietà
| Tipo | Descrizione | stringa |
|---|---|---|
name |
URL della pagina. | stringa |
id |
URL della pagina. | oggetto |
metadata |
Opzionale. Metadati arbitrari per il tuo caso d'uso (ad esempio, nome del prodotto, ambiente). | array |
globalActions |
Opzionale. Azioni da eseguire sulla pagina prima o dopo l'analisi. Vedi | Opzionale. Azioni che rispondono ai cambiamenti di stato su ogni pagina del progetto, ad esempio, chiudere un banner cookie o una notifica di sondaggio. Vedi Azioni Globali. |
screenshot |
Opzionale. Metadati arbitrari per il tuo caso d'uso (ad esempio, nome del prodotto, ambiente). | Opzionale. Cattura uno screenshot di ciascuna pagina dopo l'analisi. Vedi Acquisizione di screenshot. |
pageList |
Opzionale. Azioni da eseguire sulla pagina prima o dopo l'analisi. Vedi | Elenco delle pagine da analizzare. Vedi Proprietà. |
Proprietà
| Tipo | Descrizione | stringa |
|---|---|---|
name |
URL della pagina. | stringa |
url |
URL della pagina. | array |
actions |
Opzionale. Azioni da eseguire sulla pagina prima o dopo l'analisi. Vedi | Opzionale. Azioni da eseguire sulla pagina prima o dopo l'analisi. Vedi Le azioni sono stringhe nel. |
I file spec possono essere scritti in YAML o JSON. La seguente tabella mostra gli stessi valori in ciascun formato. Nota che in JSON, le stringhe di azione che contengono virgolette doppie devono essere precedute da un backslash.
YAML
| JSON | Azioni |
|---|---|
type "axe" into element "#searchform input" |
"type \"axe\" into element \"#searchform input\"" |
dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept" |
"dismiss modal \"#CybotCookiebotDialog\" with close button \"#CybotCookiebotDialogBodyButtonAccept\"" |
Le azioni sono stringhe nel
Le azioni sono stringhe nell'array actions (o globalActions) di un file spec. Eseguono compiti come cliccare pulsanti, compilare moduli, chiudere finestre di dialogo, attendere stati della pagina ed eseguire analisi di accessibilità. Le azioni vengono eseguite nell'ordine elencato.
Ci sono due tipi di azioni:
- Azioni di pagina vengono eseguite in sequenza su una pagina specifica. L'azione
analyzedeve essere chiamata almeno una volta per pagina. - Azioni globali vengono eseguite su ogni pagina del progetto in risposta ai cambiamenti di stato. Vedi Azioni Globali.
Esempio completo di azione
Il seguente esempio accede a Deque University e analizza il dashboard:
projects:
- name: Deque University login flow
id: deque-university-login-flow
pageList:
- name: homepage
url: https://dequeuniversity.com/
actions:
- click element ".loginLink"
- wait for element ".loginUsername" to be found
- type "user@example.com" into element ".loginUsername"
- type "secretpassword" into element "#loginPassword"
- click element "input[type=submit]"
- wait for element ".logoutLink" to be found
- analyze pageSelettori
Molte azioni richiedono un argomento selettore che identifica un elemento sulla pagina. Un selettore può essere un selettore CSS o un selettore XPath, specificato come una singola stringa o una lista di stringhe.
Per indirizzare elementi all'interno di iframe, devi usare un elenco. Tutti i selettori nell'elenco tranne l'ultimo identificano elementi <iframe> successivi in cui navigare e devono essere selettori CSS. L'ultimo selettore nell'elenco identifica l'elemento di destinazione e può essere CSS o XPath. Ogni selettore nell'elenco viene valutato in base al contesto del documento stabilito dall'elemento precedente: il primo selettore è relativo al documento radice, e ogni successivo selettore di iframe è relativo al documento dentro l'iframe precedente.
Usare una singola stringa (non una lista) non può navigare all'interno di iframe.
Esempio di selettore di iframe
Considera questa struttura HTML:
<body>
<!-- root document -->
<iframe class="payment-widget">
<!-- document inside the payment-widget iframe -->
<div class="form-wrapper">
<iframe id="card-fields">
<!-- document inside the card-fields iframe -->
<form>
<input type="text" name="card-number" class="card-input">
</form>
</iframe>
</div>
</iframe>
</body>Per cliccare sull'input del numero della carta, usa una lista di selettori. Ogni selettore CSS è valutato all'interno del contesto del documento stabilito dalla voce precedente:
# "iframe.payment-widget" is evaluated in the root document
# "#card-fields" is evaluated in the document inside iframe.payment-widget
# ".card-input" is evaluated in the document inside #card-fields
click element [ "iframe.payment-widget", "#card-fields", ".card-input" ]Per usare XPath per l'elemento di destinazione finale (i selettori degli iframe devono comunque essere CSS):
click element [ "iframe.payment-widget", "#card-fields", "//input[@name='card-number']" ]In JSON:
"click element [\"iframe.payment-widget\", \"#card-fields\", \".card-input\"]"Azioni di pagina
Il CLI supporta nove azioni di pagina:
analyze: eseguire un'analisi di accessibilitàchange: cambiare il valore di un elemento<input>,<textarea>o<select>tramite JavaScriptclick: cliccare un elementodismiss: chiudere un popup o modaleeval: eseguire JavaScript arbitrariopress: premere un tasto (con o senza modificatori)select: selezionare un'opzione in un<select>type: digitare in un<input>wait: attendere un determinato stato o ritardare
analyze
L'azione analyze esegue un'analisi di accessibilità. Deve essere chiamata almeno una volta per pagina. Puoi chiamarla più volte per analizzare una pagina in momenti diversi di un flusso di lavoro (uso la variante with title per distinguere i risultati).
Il parametro opzionale ruleset specifica quale insieme di regole utilizzare. Il predefinito è WCAG 2.1 AA. Insiemi di regole disponibili:
| ID Set di regole | Standard |
|---|---|
wcag2 |
WCAG 2.0 AA |
wcag2.1 |
WCAG 2.1 AA (predefinito) |
wcag2.2 |
WCAG 2.2 AA |
wcag2aaa |
WCAG 2.0 AAA |
wcag2.1aaa |
WCAG 2.1 AAA |
wcag2.2aaa |
WCAG 2.2 AAA |
508 |
Sezione 508 |
ttv5 |
Trusted Tester v5 |
en301549 |
EN 301 549 |
rgaav4 |
RGAA v4 |
Per informazioni sull'inclusione o l'esclusione di elementi, vedi il documentazione dell'API axe-core sul parametro Contesto.
# Analyze using the WCAG 2.1 AA ruleset (default) — all three forms are equivalent
analyze
analyze the page
analyze page
# Analyze using the Section 508 ruleset
analyze page with ruleset "508"
# Analyze with a custom title (useful when analyzing a page multiple times)
analyze the page with title "after login"
# Analyze only a specific element
analyze only element "#main-content"
# Analyze only specific elements
analyze only element "#idOfElement" and element ".classToAnalyze"
# Analyze everything except images that are immediate children of paragraphs
analyze the page excluding element "p > img"
# Analyze everything except elements inside a frame with a specific class
analyze the page excluding element [ ".classOfFrameToExclude", "#idOfElement" ]
# Save results to a specific directory
analyze the page and save in "./homepage-team/"
# Save a copy to an additional directory while also saving to the default location
analyze the page and save a copy in "./homepage-team/"
# Use the axe-core library's built-in default ruleset
analyze the page with the source default rulesetEsempio di combinazione di più opzioni: Analizzare solo le immagini all'interno di elementi con la classe third-party e i moduli che non vengono convalidati alla submit, escludendo gli elementi con la classe old-api, usando l'insieme di regole 508, con un titolo personalizzato e un percorso di salvataggio personalizzato.
analyze only element [ ".third-party", "img"] and element "form[novalidate]" excluding element ".old-api" with ruleset "508" with title "What is this testing" and save in "Results for Some test"In JSON:
"analyze only element [\".third-party\", \"img\"] and element \"form[novalidate]\" excluding element \".old-api\" with ruleset \"508\" with title \"What is this testing\" and save in \"Results for Some test\""change
L'azione change cambia il valore di un elemento <input>, <textarea> o <select> tramite JavaScript. Usa change quando gli eventi DOM normali non sono disponibili.
# Change the value of an input
change the value of "input[name=song]" to "too many puppies"click
L'azione click clicca il primo elemento che corrisponde al selettore fornito.
# Click a button by class selector
click element ".myButton"
# Click the body element
click "body"dismiss
L'azione dismiss chiude un popup o modale cliccando il suo pulsante di chiusura. Fornisci un selettore CSS per il contenitore del modale e un altro per il pulsante di chiusura. L'azione fallisce in modo contenuto se uno degli elementi non è presente.
Questa azione non chiude le finestre di dialogo native alert() o confirm().
# Dismiss a modal using separate selectors for the container and close button
dismiss modal ".myModal" with close button ".myModal .close"eval
L'azione eval esegue JavaScript arbitrario sulla pagina. Usala per manipolare il DOM o eseguire azioni personalizzate.
# Change the page title
eval "document.title = 'hello world'"
# Scroll an element into view
eval "document.querySelector('.someElement').scrollIntoView()"
# Scroll to the bottom of the page
eval "window.scrollTo(0, document.body.scrollHeight)"press
L'azione press invia una pressione del tasto a un elemento (opzionalmente con tasti modificatori). Per i nomi dei tasti supportati, vedi il documentazione dei tasti di Selenium.
# Press H on the body element
press "H" on "body"
# Press Shift+Tab on the navigation element
press "shift+tab" on element ".navigation"
# Press Shift+Control+7 on an element
press "shift+control+7" on element ".foo"select
L'azione select seleziona un <option> di un elemento <select> dal suo testo visibile (non dal suo attributo value).
Dato questo HTML:
<select class="mySelect">
<option></option>
<option value="1">dog</option>
<option value="2">cat</option>
<option value="3">fish</option>
</select># Select by visible option text
select the "dog" option in ".mySelect"
select the "cat" option in element ".mySelect"type
L'azione type digita una stringa in un elemento <input> o <textarea>. Usala per compilare moduli e popolare campi di ricerca.
# Type into an email input
type "user@example.com" into element "input[type=email]"
# Type into a textarea
type "hello world" into "textarea.Message"
# Type with a delay between keystrokes to simulate human typing
type "sloth" into "input[type=search]" with a 150ms key delaywait
L'azione wait attende che un elemento raggiunga uno stato specificato o attende per una durata data.
Stati degli elementi supportati: visible, hidden, selected, enabled, disabled, found.
Per le attese di stato degli elementi, l'azione riprova fino a 3 volte per impostazione predefinita (totale di 4 tentativi) prima di fallire. Per attendere più a lungo un elemento che si carica lentamente, aggiungi with <n> retries per aumentare il numero di tentativi.
Per la durata del sonno, i valori numerici sono interpretati come millisecondi. Le stringhe vengono convertite usando il pacchetto pacchetto ms, ad esempio: 1m = 60.000 ms, 1s = 1.000 ms.
# Wait for an element to appear
wait for element ".myElement" to be found
# Wait for an element to become hidden
wait for element ".myElement" to be hidden
# Allow more retries for a slow-loading element
wait for element ".myElement" to be found with 9 retries
# Sleep for 1 minute
wait for 1m
# Sleep for 1 second
wait for 1s
# Sleep for 30 milliseconds
wait for 30Azioni Globali
Le azioni globali vengono eseguite su ogni pagina di un progetto in risposta ai cambiamenti di stato, piuttosto che essere eseguite proceduralmente come le azioni di pagina. Attualmente è supportata solo un'azione globale: dismiss modal.
- Le azioni globali funzionano sia in modalità
specche in modalità URI senza testa. - Le azioni globali non sono procedurali: si attivano in risposta agli eventi di pagina, non in una sequenza fissa.
- L'azione globale
dismiss modalattende che appaia un modale specificato e lo chiude prima che le azioni di pagina continuino.
Aggiungi azioni globali a un progetto dopo name/id e prima di pageList:
projects:
- id: demo
name: CLI demo
globalActions:
- dismiss modal "#__next .survey" with close button ".survey button.close"
pageList:
- name: homepage
url: https://dequelabs.github.io/aget-demo-site
- name: popup
url: https://dequelabs.github.io/aget-demo-site
actions:
- wait for element "#__next header nav" to be visible
- click element "#__next header nav a[href*=popup]"
- wait for element ".content button" to be found
- analyze with title "before popup"
- click element ".content button"
- analyze with title "with popup"
- dismiss modal ".ReactModal__Content" with close button ".ReactModal__Content .close"
- analyze with title "after popup"
- name: contact
url: https://dequelabs.github.io/aget-demo-site/contact
actions:
- analyze with title "form disabled"
- wait for element "#__next .toggle" to be found
- click element ".toggle button"
- wait for element "input[name=name]" to be enabled
- analyze with title "form enabled"
- type "stephen" into element "input[name=name]"
- type "555-555-5555" into element "input[name=phone]"
- type "stephen@deque.com" into element "input[name=email]"
- type "hello world" into element "textarea[name=message]"
- click element "button[type=submit]"
- wait for element ".thanks" to be found
- analyze with title "thanks message"Acquisizione di screenshot
Per catturare uno screenshot di ciascuna pagina dopo l'analisi, aggiungi un oggetto screenshot a un progetto nel tuo file spec. Ogni pagina produce un file PNG denominato <page-id>-screenshot.png (qualsiasi / o \ nel id della pagina viene sostituito con _). Se una pagina non ha id, uno viene derivato dal suo name rimuovendo tutti gli spazi.
| Tipo | Descrizione | Predefinito | stringa |
|---|---|---|---|
enabled |
booleano | — | Obbligatorio. Impostare su true per abilitare la cattura degli screenshot. Funziona con tutti i browser supportati. |
fullPage |
booleano | false |
Acquisisce l'intera pagina scorrevole utilizzando il Chrome DevTools Protocol. Richiede Chrome o Chromium; altri browser passano a uno screenshot del viewport con un avviso. |
boundingBoxes |
booleano | false |
Aggiunge le coordinate della bounding box (x, y, width e height) a ciascun nodo di violazione nei risultati Axe, registrando dove appare l'elemento nello screenshot. |
dir |
URL della pagina. | <output-dir>/<project-id>/ |
Directory dove vengono scritti i file PNG degli screenshot. |
Quando esegui axe spec con --verbose, ciascun risultato include anche un campo screenshotPath con il percorso completo al file dello screenshot di quella pagina.
projects:
- name: My App
id: my-app
screenshot:
enabled: true
fullPage: true
boundingBoxes: true
dir: ./screenshots
pageList:
- name: Home
url: https://example.com/Elaborazione batch con axe bulk-spec
Per elaborare più file spec in un'unica esecuzione, usa axe bulk-spec con una directory contenente file spec. L'interfaccia CLI cerca ricorsivamente la directory e le sue sottodirectory per i file spec.
axe bulk-spec <spec-files-directory> <output-directory>Il <output-directory> è opzionale — se omesso, i risultati vengono salvati nella directory di lavoro corrente.
Gli aggiornamenti di progresso vengono stampati su stdout durante l'esecuzione.
I risultati sono scritti nella directory di output: un file JSON per ogni azione analyze, oltre a un file di log che elenca qualsiasi file spec che ha fallito e il motivo del fallimento.
Opzioni
Le seguenti opzioni sono disponibili per axe spec:
--axe-devhub-api-key <api-key>
Specifica la chiave API dell'Axe Developer Hub. Richiesto (insieme a --axe-devhub-project-id) per inviare i risultati all'Axe Developer Hub. Vedi Invia Risultati all'Axe Developer Hub.
--axe-devhub-project-id <project-id>
Specifica l'ID del progetto dell'Axe Developer Hub. Richiesto (insieme a --axe-devhub-api-key) per inviare i risultati all'Axe Developer Hub. Vedi Invia Risultati all'Axe Developer Hub.
--axe-devhub-server-url <url>
Specifica l'URL del server dell'Axe Developer Hub. Impostazione predefinita: https://axe.deque.com. Equivalente alla variabile d'ambiente AXE_DEVHUB_SERVER_URL. Vedi Invia Risultati all'Axe Developer Hub.
-a, --axe-source <path>
Percorso verso un file axe.js alternativo. La maggior parte degli utenti non ha bisogno di questa opzione. È inteso per casi d'uso avanzati come testare contro una versione specifica o modificata di axe-core.
--chrome-options [options]
Passa un elenco separato da virgole di opzioni a riga di comando di Chrome a ChromeDriver. Usalo per abilitare le funzionalità del browser o aggirare le restrizioni in ambienti specifici, ad esempio negli ambienti CI containerizzati dove il sandbox deve essere disabilitato.
axe spec workflow.yml --chrome-options="no-sandbox,disable-gpu"-c, --custom <path>
Specifica un file di set di regole personalizzato, sovrascrivendo il set di regole predefinito.
--descendant-links
Raccoglie i link su ciascuna pagina e li aggiunge ai risultati. Richiede --verbose.
--dismiss-alerts
Chiude automaticamente i dialoghi del browser alert(), confirm() e prompt() prima della scansione.
--enable-tracking <state>
Consente di inviare dati alla libreria delle metriche.
--filter <type(s)>
Filtra i tipi di risultati dall'output: passes, violations, incomplete, inapplicable. Richiede --format csv.
-f, --format <type(s)>
Formato/i del report: html, junit, csv, universal, o una combinazione separata da virgole. Predefinito: html. Vedi --universal-ruleset e --universal-best-practices per le opzioni che si applicano quando si utilizza universal.
--no-analyze
Rimuove il requisito per un'azione analyze nella lista delle azioni di ogni pagina. Di default, ogni pagina in un file di specifiche deve includere almeno un'azione analyze; questo flag disattiva quel controllo, utile quando si esegue un workflow che esegue solo azioni senza una scansione di accessibilità.
--no-exit
Forza il CLI a uscire con il codice 0 anche quando vengono trovate violazioni. Di default, axe spec esce con il codice 1 se vengono rilevate violazioni. Usa questo quando vuoi raccogliere risultati senza fallire un build CI.
--no-git-data
Esclude le informazioni sul branch Git e sul commit quando si inviano i risultati all'Axe Developer Hub. Vedi Invia Risultati all'Axe Developer Hub.
--no-html
Impedisce che il CLI generi un report HTML. Usalo insieme a --format per controllare quali formati di report vengono scritti, oppure quando vuoi solo risultati JSON senza un sommario HTML.
--no-reports
Impedisce alla CLI di generare qualsiasi file di report. I risultati sono comunque raccolti e visualizzati nel terminale, ma nulla viene scritto su disco. Utile per verifiche rapide in cui non sono necessari file di output.
--no-wait
Disabilita la pausa automatica tra le azioni del flusso di lavoro. Di default, le pause configurate con --post-get-pause, --post-script-pause e --post-analyze-pause si applicano tra le azioni (vedi Configura); questo flag le bypassa tutte.
--page-name <name>
Esegue solo la pagina con il nome specificato dalla pageList del file di specifiche.
--page-source
Aggiunge il codice sorgente HTML scansionato ai risultati. Richiede --verbose.
--page-title
Aggiunge il titolo della pagina ai risultati. Richiede --verbose.
--remote-proxy <proxy-server>
Instrada il traffico attraverso il server proxy remoto specificato.
--resume-from <name>
Salta tutte le pagine prima della pagina nominata nella pageList del file di specifiche.
--scanned-url
Aggiunge l'URL base e l'URL della scansione corrente ai risultati dettagliati. Solo Chrome. Richiede --verbose.
--set-distinct-id <id>
Sovrascrive il valore ID distinto.
--set-legacy-mode
Abilita il legacy deprecato, che verrà rimosso nella versione v5.0.
Questa è un'opzione di ultima istanza. È stato segnalato che consente di completare le scansioni su pagine che sovrascrivono window.open(), una pratica sconsigliata.
--set-tracking-url <url>
Sovrascrive l'URL a cui vengono inviate le metriche.
--silent-mode
Sopprime tutto il testo decorativo dall'output del CLI. I risultati vengono visualizzati solo quando anche --verbose è attivo. Usalo in script o pipeline CI dove vuoi un output pulito senza banner di progresso o messaggi di stato.
-t, --tags
Filtra il set di regole standard per tag.
--universal-best-practices
Registra bestPracticesEnabled=true nei metadati dell'output in formato universale. Richiede --format universal.
--universal-ruleset <id>
Specifica l'ID del set di regole da registrare nei metadati dell'output in formato universale. Predefinito: wcag2.1. Richiede --format universal. Vedi il tabella dei set di regole per i valori validi.
--user-agent
Imposta una stringa agente utente personalizzata per il browser.
--validate
Convalida il file di specifiche senza eseguirlo.
-v, --verbose
Include output aggiuntivo: risultati Axe e metadati come nome dello strumento, versione e ambiente.
--wait-network-idle-new-connections [number]
Il numero di nuove connessioni di rete che possono essere stabilite prima che la rete sia considerata inattiva. Una volta che le nuove connessioni scendono a o sotto questa soglia, il CLI procede con la scansione. Usa insieme a --wait-network-idle-timeout per regolare quando il CLI opera su pagine con attività di rete in background in corso.
--wait-network-idle-open-connections [number]
Il numero di connessioni di rete aperte che possono rimanere prima che la rete sia considerata inattiva. Una volta che le connessioni aperte scendono a questo valore o al di sotto, la CLI procede con la scansione.
--wait-network-idle-polling-every [ms]
L'intervallo in millisecondi con cui la CLI verifica se la rete è diventata inattiva. Riduci questo valore per rilevamenti più rapidi a costo di un maggiore utilizzo della CPU.
--wait-network-idle-timeout [ms]
Il tempo massimo in millisecondi di attesa affinché l'attività di rete si stabilizzi prima di avviare la scansione. Dopo il caricamento della pagina, la CLI monitora le connessioni di rete attive e attende finché il conteggio delle connessioni non raggiunge la soglia configurata. Se il timeout scade prima che la rete diventi inattiva, la CLI procede comunque con la scansione.
Per opzioni di configurazione aggiuntive, vedi Configura.
