Analizzare le Pagine Usando 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 analizzarla 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 Comando 

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

Il <output-dir> è dove i risultati JSON vengono salvati. Se omesso, i risultati vengono salvati nella directory di lavoro corrente.

Esempio di utilizzo:

axe spec ./axe-workflow.yaml ./axe-results --format html

Struttura del File Spec

Un file spec definisce uno o più progetti, ciascuno con un elenco di pagine da analizzare e azioni opzionali da eseguire su ciascuna pagina.

Esempio YAML

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/

Progetto

Proprietà Tipo Descrizione
name stringa Nome visualizzato unico del progetto.
id stringa Identificatore unico del progetto.
metadata oggetto Opzionale. Metadati arbitrari per il tuo caso d'uso (ad esempio, nome del prodotto, ambiente).
globalActions array Opzionale. Azioni che rispondono ai cambiamenti di stato su ogni pagina del progetto, ad esempio, chiudere un banner cookie o una finestra pop-up di sondaggio. Vedi Azioni Globali.
pageList array Elenco delle pagine da analizzare. Vedi Pagina.

Pagina

Proprietà Tipo Descrizione
name stringa Nome visualizzato della pagina.
url stringa URL della pagina.
actions array Opzionale. Azioni da eseguire sulla pagina prima o dopo l'analisi. Vedi Azioni.

Formato JSON/YAML

I file di specifiche possono essere scritti in YAML o JSON. La tabella seguente mostra gli stessi valori in ciascun formato. Nota che in JSON, le stringhe di azione che contengono virgolette doppie devono sfuggirle con una barra inversa.

YAML JSON
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\""

Azioni

Le azioni sono stringhe nell'array actions (o globalActions) di un file di specifica. Eseguono compiti come cliccare pulsanti, completare moduli, chiudere finestre di dialogo, attendere stati delle pagine e condurre 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 esegue l'accesso 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 XPath, specificato come una stringa singola o un elenco di stringhe.

Per mirare agli elementi all'interno degli iframe, è necessario utilizzare un elenco. Tutti i selettori nell'elenco tranne l'ultimo identificano gli elementi successivi <iframe> 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 relazione al contesto del documento stabilito dalla voce precedente: il primo selettore è relativo al documento radice, e ciascun selettore di iframe successivo è relativo al documento all'interno dell'iframe precedente.

Utilizzare una stringa singola (non un elenco) non può navigare all'interno degli 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 il campo del numero di carta, utilizza un elenco di selettori. Ogni selettore CSS viene valutato nel 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 utilizzare XPath per l'elemento di destinazione finale (i selettori di 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 dell'accessibilità
  2. change: cambiare il valore di un <input>, <textarea>, o <select> via JavaScript
  3. click: cliccare su un elemento
  4. dismiss: chiudere un popup o una finestra 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 un stato specifico o attendere

analyze

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

Il parametro opzionale ruleset specifica quale insieme di regole utilizzare. Il predefinito è WCAG 2.1 AA. Regole disponibili:

ID Regolamento 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 Tester affidabile v5
en301549 EN 301 549
rgaav4 RGAA v4

Per informazioni su come includere o escludere elementi, vedere la documentazione dell'API axe-core sul parametro Context.

# 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 degli elementi con la classe third-party e i moduli che non vengono validati all'invio, escludendo gli elementi con la classe old-api, utilizzando il 508 regolamento, 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

L'azione change cambia il valore di un <input>, <textarea>, o <select> elemento tramite JavaScript. Utilizzare 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 dato.

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

# Click the body element
click "body"

dismiss

L'azione dismiss chiude un popup o un modale cliccando il suo pulsante di chiusura. Fornire un selettore CSS per il contenitore del modale e un altro per il pulsante di chiusura. L'azione fallisce gentilmente se uno degli elementi non è presente.

note

Questa azione non chiude i alert() o confirm() dialoghi nativi.

# 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. Usalo 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 di tasto a un elemento (opzionalmente con tasti modificatori). Per i nomi dei tasti supportati, vedere la documentazione dei tasti 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 <select> elemento tramite il suo testo visibile (non attraverso 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

L'azione type l'azione digita una stringa in un <input> o in un <textarea> elemento. Usatela 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

L'azione wait aspetta che un elemento raggiunga uno stato specificato, oppure attende per una durata prestabilita.

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

Per la durata dell'attesa, i valori numerici sono interpretati come millisecondi. Le stringhe vengono 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 si eseguono su ogni pagina di un progetto in risposta ai cambiamenti di stato, piuttosto che eseguire proceduralmente come 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 a eventi di pagina, non in una sequenza fissa.
  • L'azione globale dismiss modal aspetta che un modale specificato appaia 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"

Elaborazione in Lotti con axe bulk-spec

Per elaborare più file di specifiche in un'unica esecuzione, utilizza axe bulk-spec con una directory contenente i 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 sono salvati nella directory di lavoro corrente.

Gli aggiornamenti sul progresso vengono stampati su stdout durante l'esecuzione.

I risultati sono scritti nella directory di output: un file JSON per ciascuna analyze azione, più un file di log che elenca eventuali file di specifiche falliti e il motivo del fallimento.

Opzioni

Le seguenti opzioni sono disponibili per axe spec:

--axe-devhub-api-key <api-key>

Specifica la chiave API di Axe Developer Hub. Necessaria (insieme a --axe-devhub-project-id) per inviare i risultati ad Axe Developer Hub. Vedi Invia Risultati a Axe Developer Hub.

--axe-devhub-project-id <project-id>

Specifica l'ID progetto di Axe Developer Hub. Necessario (insieme a --axe-devhub-api-key) per inviare i risultati ad Axe Developer Hub. Vedi Invia Risultati a Axe Developer Hub.

--axe-devhub-server-url <url>

Specifica l'URL del server di Axe Developer Hub. Predefinito a https://axe.deque.com. Equivalente alla variabile d'ambiente ", "context": "paragraph AXE_DEVHUB_SERVER_URL . Vedi ", "context": "paragraph Invia Risultati a Axe Developer Hub", "context": "link text.", "context": "paragraph

-c, --custom <path>

Specifica un file di regole personalizzato, sostituendo il set di regole predefinito.", "context": "paragraph

--descendant-links

Raccoglie i link su ogni pagina e li aggiunge ai risultati. Richiede ", "context": "paragraph --verbose.", "context": "paragraph

--dismiss-alerts

Chiude automaticamente i ", "context": "paragraph alert()del browser, ", "context": "paragraph confirm()e ", "context": "paragraph prompt() i dialoghi prima della scansione.", "context": "paragraph

--enable-tracking <state>

Consente l'invio di dati alla libreria di metriche.", "context": "paragraph

--filter <type(s)>

Filtra i tipi di risultati dall'output: ", "context": "paragraph passes, ", "context": "paragraph violations, ", "context": "paragraph incomplete, ", "context": "paragraph inapplicable. Richiede ", "context": "paragraph --format csv.", "context": "paragraph

-f, --format <type(s)>

Formato(i) del rapporto: ", "context": "paragraph html, ", "context": "paragraph junit, ", "context": "paragraph csv, o una combinazione separata da virgole. Predefinito: ", "context": "paragraph html.", "context": "paragraph

--no-git-data

Esclude le informazioni del branch e del commit Git quando si inviano i risultati a Axe Developer Hub. Vedi ", "context": "paragraph Invia Risultati a Axe Developer Hub", "context": "link text.", "context": "paragraph

--page-name <name>

Esegue solo la pagina con il nome specificato dal file di specifiche ", "context": "paragraph pageList.", "context": "paragraph

--page-source

Aggiunge il sorgente HTML scansionato ai risultati. Richiede ", "context": "paragraph --verbose.", "context": "paragraph

--page-title

Aggiunge il titolo della pagina ai risultati. Richiede ", "context": "paragraph --verbose.", "context": "paragraph

--remote-proxy <proxy-server>

Instrada il traffico attraverso il server proxy remoto specificato.", "context": "paragraph

--resume-from <name>

Salta tutte le pagine prima della pagina nominata nel file di specifiche ", "context": "paragraph pageList.", "context": "paragraph

--scanned-url

Aggiunge l'URL base e l'URL di scansione corrente ai risultati dettagliati. Solo Chrome. Richiede ", "context": "paragraph --verbose.", "context": "paragraph

--set-distinct-id <id>

Sostituisce il valore ID distinto.", "context": "paragraph

--set-legacy-mode

Abilita la modalità di scansione ", "context": "paragraph legacy", "context": "link textdeprecata, che sarà rimossa nella versione 5.0.", "context": "paragraph

important

Questa è un'opzione di ultima risorsa. È stato segnalato che consente di completare le scansioni su pagine che sovrascrivono ", "context": "paragraph window.open(), una pratica sconsigliata.", "context": "paragraph

--set-tracking-url <url>

Sostituisce l'URL a cui vengono inviati i dati delle metriche.", "context": "paragraph

-t, --tags

Filtra il set di regole standard per tag.", "context": "paragraph

--user-agent

Imposta una stringa agente utente personalizzata per il browser.", "context": "paragraph

--validate

Convalida il tuo file di specifiche senza eseguirlo.", "context": "paragraph

-v, --verbose

Include output aggiuntivo: risultati Axe e metadati come nome dello strumento, versione e ambiente.", "context": "paragraph

Per ulteriori opzioni di configurazione, vedi ", "context": "paragraph Configura", "context": "link text.

Is this page helpful?

Help us improve this page

Still need help?