Utilizzo di axe DevTools Linter Connector

axe DevTools Linter Connector (noto anche come Connettore) è uno strumento da riga di comando per Linux, macOS e Windows. Fornisce un'interfaccia a riga di comando per eseguire il lint dei file in modo da automatizzare il controllo di accessibilità. Ad esempio, è possibile utilizzarlo per la creazione di script e per CI/CD (integrazione continua e distribuzione continua). Il Connettore deve inviare i file a un'istanza di axe Linter Server (ospitata da Deque o dalla tua organizzazione) oppure puoi eseguire il lint dei file localmente senza inviare il contenuto dei file a un server utilizzando l'opzione --local , vedi Linting locale di seguito.

Casi d'uso per il connettore

Il connettore axe DevTools può

• Verificare l'accessibilità come parte delle build di Jenkins. Per ulteriori informazioni, vedere Utilizzo di axe DevTools Linter con Jenkins.
• Esegui la scansione dei tuoi file e inserisci informazioni sui difetti di accessibilità in SonarQube. Per informazioni su come impostare questa opzione, vedere Utilizzo di axe DevTools Linter con SonarQube .
• Può essere utilizzato in uno script pre-commit di GitHub per bloccare i commit che contengono errori di accessibilità. Vedere Utilizzo di un Git Pre-Commit Hook con axe DevTools Linter.
• Fornire una base per verificare il codice per individuare difetti di accessibilità per servizi quali:
  • Bitbucket
  • CircleCI
  • GitLab
  • Servizi DevOps di Azure

Linting locale

Il connettore consente di evitare di inviare i file a un server utilizzando il linting locale con l' --local opzione della riga di comando.

• Vantaggi del Linting Locale

  • Molto più veloce rispetto all'utilizzo del server.
  • Molto meno probabile che si verifichino problemi di rete o di carico del server. È particolarmente efficiente quando si esegue il linting di un gran numero di file.

• Svantaggi del linting locale

  • Richiede più risorse della macchina locale.
  • Per aggiornare l'axe DevTools Linter Connector è necessario scaricare e installare una nuova versione da Agora.
  • Nessun monitoraggio dell'utilizzo (se si utilizza una chiave di licenza anziché una chiave API).

Chiavi di licenza a confronto con chiavi API

Per il linting locale è necessaria una chiave API o una chiave di licenza. Puoi gestire le tue chiavi API come parte del tuo account axe (quindi offrono flessibilità). Tuttavia, è necessario richiedere una chiave di licenza all'Help Desk di Deque. L'utilizzo del linting locale con le chiavi di licenza non tiene traccia dell'utilizzo da parte degli utenti (linee di codice sottoposte a linting), ma le chiavi di licenza non richiedono nemmeno l'autenticazione remota.

Configurazione

Per informazioni sul download di axe DevTools Linter Connector, vedere Download di axe DevTools Linter Connector.

Su Linux e macOS, il file di comando necessita che il suo flag di esecuzione sia impostato, come mostrato di seguito:

chmod +x axe-linter-connector-linux
chmod +x axe-linter-connector-macos

Quando scarichi l'eseguibile su macOS, viene impostato l'attributo di quarantena, che devi eliminare prima di poter utilizzare il connettore:

xattr -d com.apple.quarantine axe-linter-connector-macos

Rinomina l'eseguibile (per eliminare il sistema operativo e il trattino alla fine del nome del file) e copialo o collegalo in una directory sul tuo percorso in modo che possa essere utilizzato con altri strumenti (ad esempio con un Git pre-commit hook, vedi Utilizzo di un Git Pre-Commit Hook con axe DevTools Linter).

Variabili d'ambiente

Il connettore riconosce le seguenti variabili ambientali:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• DEBUG

AXE_LINTER_SERVER_URL e AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL imposta l'URL per l'istanza del server axe DevTools Linter. (È anche possibile impostare l'URL del server con le -u o --url opzioni della riga di comando.) AXE_LINTER_SERVER_PORT specifica la porta su cui il server è in ascolto, in genere la porta 3000.

Per maggiori informazioni sulla configurazione del server, vedere Configurazione di axe DevTools Linter e Riferimento rapido URL per l'URL da utilizzare con la versione SaaS di axe DevTools Linter. (Non è necessario specificare una porta quando si utilizza la versione SaaS di axe DevTools Linter.)

L'esempio seguente mostra come impostare le variabili di ambiente per axe DevTools Linter in esecuzione sul computer locale su Linux o macOS (anche se nessuna delle due variabili di ambiente è richiesta qui perché questi sono i valori predefiniti):

export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000

In alternativa, su Linux e macOS, puoi anche impostare le variabili di ambiente sulla stessa riga di comando del comando axe-linter-connector . L'esempio seguente mostra questo utilizzo. (Tuttavia, poiché questi sono i valori predefiniti per il server e la porta, non è necessario impostarli.)

AXE_LINTER_SERVER_PORT=3000 AXE_LINTER_SERVER_URL=http://localhost axe-linter-connector -s . -d .

DEBUG

La variabile d'ambiente DEBUG consente di registrare informazioni di debug dettagliate per diagnosticare errori di linting. Impostare la variabile d'ambiente DEBUG su axe-devtools-linter:* per attivare la registrazione del debug, come mostrato di seguito:

DEBUG=axe-devtools-linter:* axe-linter-connector -s . -d .

Opzioni della riga di comando

Opzioni della riga di comando richieste

axe DevTools Linter Connector richiede le due opzioni seguenti:

-s, --source directory-o-file
Indica un file o una directory contenente i file da controllare per eventuali errori di accessibilità. La ricerca viene effettuata anche nelle sottodirectory. Per escludere i file dal linting, vedere l'opzione exclude nella sezione File di configurazione .

-d, --destinazione **
Directory in cui Connector scriverà il report sull'accessibilità.

-u, --url URL
Specifica il server da utilizzare. Il valore predefinito è http://localhost. Per utilizzare il server SaaS, specificare --url https://axe-linter.deque.com/

Opzioni facoltative della riga di comando

Potrebbero essere necessarie diverse opzioni, a seconda del server a cui ci si connette e delle altre funzionalità o formati di report che si desidera utilizzare.

--api-key api-key
Specifica la chiave API per autorizzare il linting con l'istanza SaaS axe DevTools Linter o per utilizzare il linting locale. Per ulteriori informazioni, vedere Ottenere una chiave API axe DevTools Linter SaaS .

--config nome file
Specifica il nome di un file YAML contenente informazioni di configurazione. È possibile utilizzare questa opzione anche senza un nome file: axe DevTools Connector seguirà i passaggi descritti in File di configurazione multipli per individuare i file di configurazione. Per informazioni sul file di configurazione, vedere File di configurazione.

--filename filename
Specifica il nome del report SonarQube, predefinito: axe-linter-report.json

--issue-type type
Utilizzato per indicare il tipo di problema per SonarQube, predefinito: BUG, valori consentiti: VULNERABILITÀ, PROBLEMI_DI_CODICE o BUG

--license-key chiave
Specifica la chiave di licenza da utilizzare per l'autenticazione. Contattare l'Help Desk Deque per ulteriori informazioni su come ottenere una chiave di licenza. Questa opzione richiede anche l'opzione --local .

--local
Attiva il linting locale, che utilizza la macchina su cui è in esecuzione axe DevTools Connector per eseguire il lint dei file anziché inviarli a un server. Richiede una chiave API (--api-key) o una chiave di licenza (--license-key). Vedere Linting Locale.

axe-linter-connector -s . -d . --api-key 1234 --local --url https://axe-linter.deque.com/

-R, --reporter reporter
Specifica il reporter da utilizzare, predefinito: sonarqube

--limite-backoff limite-backoff
Specifica il tempo massimo in millisecondi che il connettore attenderà prima di ritentare la connessione al server in caso di errore. **** Il valore predefinito è 30.000 millisecondi (30 secondi).

--conteggio tentativi **
Specifica il numero di tentativi di connessione al server dopo aver riscontrato un errore di connessione. Il connettore raddoppierà il tempo tra i tentativi (a partire da 500 millisecondi o 0,5 secondi) finché non raggiunge il limite di backoff (specificato con --retry-backoff-limit), dove rimarrà finché non raggiungerà il numero specificato di tentativi (e fallirà) o si connetterà al server senza errori.

--severity **
Imposta il livello di gravità per SonarQube, predefinito: MAJOR, valori consentiti: BLOCKER, CRITICO, MAJOR, MINOR o INFO

File di configurazione

È possibile utilizzare un file di configurazione YAML con l'opzione di comando --config .

Di seguito è riportato un esempio di file di configurazione:

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

Nell'esempio sopra, la regola image-alt verrà ignorata e il file meta-refresh.html non verrà sottoposto a linting. Verranno utilizzate le regole nel tag wcag2a , come specificato nella sezione tag . (Per maggiori informazioni, vedere Tag .)

Il valore exclude consente valori glob (*) e globstar (**), quindi è consentito quanto segue:

exclude:
  - tmp/**/*.html

L'esempio sopra riportato escluderebbe tutti i file HTML nella directory tmp o in una qualsiasi delle sue sottodirectory.

Per maggiori informazioni sulle opzioni di configurazione consentite, vedere Configurazione di axe DevTools Linter.

Esempio di utilizzo

Per utilizzare Connector con il server SaaS axe DevTools Linter, è possibile utilizzare l'opzione api-key come mostrato di seguito:

axe-linter-connector -s . -d . --api-key 83cc5831-a35b-4a2d-9c2b-84fd2eec0a4d  --url https://axe-linter.deque.com/

Per eseguire tutto il linting localmente sul computer che esegue axe DevTools Connector, utilizzare l'opzione --local :

axe-linter-connector -s . -d . --api-key b5a34bba-7b0f-4ccb-9eb2-195ac6c56aee --local --url https://axe-linter.deque.com/