Analizzare le Pagine Utilizzando i File Spec

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

Come utilizzare i sottocomandi spec e bulk-spec per analizzare le pagine usando i file spec

Not for use with personal data

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 html

Un 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 analyze deve 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 page

Selettori

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:

  1. analyze: eseguire un'analisi di accessibilità
  2. change: cambiare il valore di un elemento <input>, <textarea> o <select> tramite JavaScript
  3. click: cliccare un elemento
  4. dismiss: chiudere un popup o modale
  5. eval: eseguire JavaScript arbitrario
  6. press: premere un tasto (con o senza modificatori)
  7. select: selezionare un'opzione in un <select>
  8. type: digitare in un <input>
  9. 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 ruleset

Esempio 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.

note

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 delay

wait

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 30

Azioni 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à spec che 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 modal attende 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.

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.

important

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.