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 ogni pagina prima di analizzarle per problemi di accessibilità. Usa axe spec per eseguire un singolo file spec, oppure axe bulk-spec per elaborare una directory di file spec.

Il axe spec 

axe spec <spec-file> <output-dir> [options]

Il <output-dir> Esempio di utilizzo:

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 Azioni Globali Azioni Globali.
screenshot Opzionale. Metadati arbitrari per il tuo caso d'uso (ad esempio, nome del prodotto, ambiente). Opzionale. Acquisisce uno screenshot di ogni pagina dopo l'analisi. Vedi Acquisizione di screenshot.
pageList Opzionale. Azioni da eseguire sulla pagina prima o dopo l'analisi. Vedi Pagina 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 Azioni 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

(o actions (o globalActions) array di un file di specifiche. Eseguono attività come cliccare pulsanti, compilare moduli, chiudere dialoghi, attendere stati di 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' analyze azione 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, è necessario usare una lista. Tutti i selettori nella lista tranne l'ultimo identificano successivi <iframe> elementi in cui navigare e devono essere selettori CSS. L'ultimo selettore nella lista identifica l'elemento di destinazione e può essere CSS o XPath. Ogni selettore nella lista è valutato rispetto al contesto del documento stabilito dalla voce precedente: il primo selettore è relativo al documento radice, e ciascun selettore successivo degli iframe è relativo al documento all'interno dell'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 <input>, <textarea>, o <select> tramite JavaScript
  3. click: cliccare su un elemento
  4. dismiss: chiudere un popup o modale
  5. eval: valutare 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 uno stato specifico o dormire

analyze

Il analyze azione esegue un'analisi di accessibilità. Deve essere chiamata almeno una volta per pagina. Può essere chiamata più volte per analizzare una pagina in diversi punti di un flusso di lavoro (usa la with title variante per distinguere i risultati).

Il parametro opzionale ruleset specifica quale set di regole utilizzare. Il predefinito è WCAG 2.1 AA. Set 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 su come includere o escludere elementi, consultare la 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: Analizza solo le immagini all'interno degli elementi con la classe third-party e dei moduli che non vengono validati all'invio, escludendo gli elementi con la classe old-api, utilizzando il 508 set di regole, con un titolo personalizzato e una posizione di salvataggio personalizzata.

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

Il change modifica il valore di un <input>, <textarea>, o <select> elemento tramite JavaScript. Usare 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

Il click fa clic sul primo elemento che corrisponde al selettore dato.

# Click a button by class selector
click element ".myButton"

# Click the body element
click "body"

dismiss

Il dismiss chiude un popup o una finestra modale facendo clic sul suo pulsante di chiusura. Fornire un selettore CSS per il contenitore modale e un altro per il pulsante di chiusura. L'azione fallisce in modo indolore 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

Il eval esegue JavaScript arbitrario sulla pagina. Usarla 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

Il press invia una pressione di tasto a un elemento (eventualmente con tasti modificatori). Per i nomi dei tasti supportati, consultare la 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

Il select seleziona un <option> di un <select> elemento tramite il suo testo visibile (non il suo value attributo).

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

Il type digita una stringa in un <input> o <textarea> elemento. Usarla per compilare moduli e riempire 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

Il wait attende che un elemento raggiunga uno stato specifico o sospende l'esecuzione per una durata data.

Stati supportati degli elementi: visible, hidden, selected, enabled, disabled, found.

Per la durata del sonno, i valori numerici sono interpretati come millisecondi. Le stringhe sono convertite utilizzando il pacchetto ms — per 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

# 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 procedere in modo sequenziale come le azioni di pagina. Attualmente è supportata solo un'azione globale: dismiss modal.

  • Le azioni globali funzionano sia in spec modalità 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.
  • Il dismiss modal attende che un determinato modale appaia e lo chiude prima che le azioni di pagina continuino.

Aggiungi le 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 acquisire uno screenshot di ogni pagina dopo l'analisi, aggiungi un screenshot oggetto a un progetto nel tuo file di specifiche. Ogni pagina produce un file PNG denominato <page-id>-screenshot.png (qualsiasi / o \ nella pagina id è sostituito con _). Se una pagina non ha id, uno è derivato dal suo name rimuovendo tutti gli spazi vuoti.

Tipo Descrizione Predefinito stringa
enabled booleano — Obbligatorio. Imposta su true per abilitare l'acquisizione di 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 del riquadro di delimitazione (x, y, width, e height) a ogni nodo di violazione nei risultati axe, registrando dove l'elemento appare 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, ogni risultato include anche un screenshotPath campo con il percorso completo al file di 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 di specifiche in un'unica esecuzione, utilizza axe bulk-spec con una directory contenente file di specifiche. Il CLI cerca ricorsivamente nella directory e nelle sue sottodirectory i file di specifiche.

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 sui progressi vengono stampati su stdout durante l'esecuzione.

I risultati vengono scritti nella directory di output: un file JSON per ogni analyze azione, più un file di log che elenca i file di specifiche non riusciti 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. Necessaria (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 progetto dell'Axe Developer Hub. Necessario (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 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 alternativo axe.js . La maggior parte degli utenti non ne ha bisogno. È destinato a casi d'uso avanzati come i test su una versione specifica o patchata 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 ogni pagina e li aggiunge ai risultati. Richiede --verbose.

--dismiss-alerts

Chiude automaticamente i browser alert(), confirm(), e prompt() le finestre di dialogo 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, o una combinazione separata da virgole. Predefinito: html.

--no-analyze

Rimuove il requisito di un analyze action nell'elenco delle azioni di ogni pagina. Per impostazione predefinita, ogni pagina in un file di specifiche deve includere almeno una analyze action; questo flag disabilita quel controllo, il che è utile quando si esegue un workflow che esegue solo azioni senza eseguire una scansione di accessibilità.

--no-exit

Forza la CLI a uscire con il codice 0 anche quando vengono rilevate violazioni. Per impostazione predefinita, axe spec esce con il codice 1 se vengono rilevate violazioni. Usa questo quando vuoi raccogliere i risultati senza interrompere una build CI.

--no-git-data

Esclude le informazioni sul ramo Git e sul commit quando si inviano i risultati all'Axe Developer Hub. Vedi Invia Risultati all'Axe Developer Hub.

--no-html

Impedisce alla CLI di generare un report HTML. Usalo insieme a --format per controllare quali formati di report vengono scritti, o quando vuoi solo risultati JSON senza un riepilogo 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 workflow. Per impostazione predefinita, le pause configurate con --post-get-pause, --post-script-pause, e --post-analyze-pause si applicano tra le azioni (vedi Configura); questo flag le ignora tutte.

--page-name <name>

Esegue solo la pagina con il nome specificato dal file di specifiche pageList.

--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 nel file di specifiche pageList.

--scanned-url

Aggiunge l'URL di 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 la modalità di scansione deprecata legacy, che verrà rimossa nella versione 5.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 della CLI. I risultati vengono mostrati solo quando --verbose è anch'esso 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.

--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 questo valore o al di sotto, la CLI procede con la scansione. Usa insieme a --wait-network-idle-timeout per regolare quando la CLI si esegue 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 ulteriori opzioni di configurazione, vedi Configura.

Is this page helpful?

Help us improve this page

Still need help?