Utilizzo di Axe DevTools Linter Connector

Il Axe DevTools Linter Connector (conosciuto anche come il Connector) è uno strumento da riga di comando per Linux, macOS e Windows. Fornisce un'interfaccia da riga di comando per valutare i tuoi file in modo da poter automatizzare il controllo dell'accessibilità. Puoi, ad esempio, usarlo per scripting e CI/CD (integrazione continua e consegna continua). Il Connector deve inviare i tuoi file a un'istanza di Axe Linter Server, sia ospitata da Deque (SaaS) che dalla tua organizzazione (on prem o on premises), oppure puoi valutare i file localmente senza inviare il contenuto dei tuoi file a un server utilizzando l'opzione --local (vedi Linting Locale sotto).

Casi d'Uso per il Connector

Il Axe DevTools Connector può

• Controlla l'accessibilità come parte delle build di Jenkins. Per maggiori informazioni, vedi Uso di Axe DevTools Linter con Jenkins.
• Scansiona i tuoi file e trasmetti le informazioni sui difetti di accessibilità in SonarQube. Vedi Uso di Axe DevTools Linter con SonarQube per informazioni su come configurarlo.
• Essere utilizzato in uno script pre-commit di GitHub per bloccare i commit che contengono errori di accessibilità. Vedi Uso di un Hook Pre-Commit di Git con Axe DevTools Linter.
• Fornire una base per controllare il tuo codice per difetti di accessibilità per servizi come:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Linting Locale

Il Connector ti permette di evitare di inviare i tuoi file a un server utilizzando linting locale con l'opzione da riga di comando --local.

• Vantaggi del Linting Locale

  • Molto più veloce rispetto all'uso del server.
  • Molto meno probabile incontrare problemi di rete o sovraccarico del server. È particolarmente efficiente durante l'analisi di un gran numero di file.

• Svantaggi del Linting Locale

  • Richiede più risorse della macchina locale.
  • Gli aggiornamenti al Axe DevTools Linter Connector richiedono il download e l'installazione di una nuova versione da Agora.
  • Nessun tracciamento dell'uso (se si utilizza una chiave di licenza invece di una chiave API).

Confronto tra Chiavi di Licenza e Chiavi API

Il linting locale richiede una chiave API o una chiave di licenza. Puoi gestire le tue chiavi API come parte del tuo account Axe (quindi offrono flessibilità). Tuttavia, devi richiedere una chiave di licenza da l'Help Desk di Deque. L'uso del linting locale con chiavi di licenza non traccia l'utilizzo degli utenti (linee di codice valutate), ma le chiavi di licenza non richiedono l'autenticazione remota.

Opzioni di Installazione

Ci sono due opzioni per installare il Axe DevTools Linter Connector:

• Configura un registry npm di Agora e utilizza l'infrastruttura fornita da Node.js e npm per installare, eseguire e aggiornare il connettore. Vedi Installazione del Axe DevTools Linter Connector come pacchetto npm per maggiori informazioni.
• L'altra opzione è scaricare manualmente il binario del Connector per l'architettura del tuo computer e prepararlo per l'uso impostando il bit di esecuzione (Linux e macOS) e cancellando eventuali attributi di quarantena estesi (macOS). Vedi la pagina dei download.

Variabili d'Ambiente

Il Connector riconosce le seguenti variabili d'ambiente:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• AXE_SERVICE_URL
• DEBUG

AXE_LINTER_SERVER_URL e AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL imposta l'URL per la tua istanza del server Axe DevTools Linter. (Puoi anche impostare l'URL del server con -u o --url opzioni della riga di comando.) AXE_LINTER_SERVER_PORT specifica la porta su cui il server ascolta, tipicamente la porta 3000.

Vedi Configurazione di Axe DevTools Linter per ulteriori informazioni su come configurare il tuo server, e vedi Riferimenti Rapidi 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 d'ambiente per l'esecuzione di Axe DevTools Linter su una macchina locale su Linux o macOS (anche se qui non è richiesta alcuna variabile d'ambiente poiché 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 d'ambiente sulla stessa riga di comando del comando axe-linter-connector. L'esempio sotto 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 .

AXE_SERVICE_URL

La variabile d'ambiente AXE_SERVICE_URL ti permette di specificare un server alternativo per convalidare la tua chiave API. Il valore predefinito è https://axe.deque.com.

I clienti del cloud privato hanno un server di autenticazione dedicato a un URL specifico per cliente. Per utilizzare il linting locale, imposta AXE_SERVICE_URL sull'URL della tua istanza cloud privata prima di eseguire il Connector:

export AXE_SERVICE_URL=https://your-org-axedevtools.dequecloud.com
axe-linter-connector -s . -d . --api-key <your-api-key> --local

L'URL della tua istanza cloud privata ti è stato fornito quando è stata configurata la tua istanza cloud privata. Se non lo hai, contatta l'Help Desk di Deque.

DEBUG

La variabile d'ambiente DEBUG ti consente di registrare informazioni dettagliate di debug per diagnosticare errori di linting. Imposta 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 Obbligatorie della Riga di Comando

Axe DevTools Linter Connector richiede le seguenti due opzioni:

-s, --source directory-o-file
Indica un file o una directory contenente file da controllare per errori di accessibilità. Vengono cercate anche le sottodirectory. Per escludere i file dalla valutazione, vedi l'opzione exclude nella sezione File di Configurazione.

-d, --destination directory
The directory where the Connector will write the accessibility report.

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

Opzioni Facoltative della Riga di Comando

Potrebbero essere richieste diverse opzioni, a seconda del server a cui ti connetti e di quali altre funzionalità o formati di report desideri utilizzare.

--additional-properties proprietà
Aggiunge proprietà extra ai problemi nel rapporto di accessibilità per le violazioni trovate su componenti mappati su misura. L'unico valore attualmente supportato è customName. Quando specificato, ogni problema che coinvolge un componente mappato personalizzato ottiene una proprietà customName nel rapporto il cui valore è il nome del tag del componente personalizzato che ha generato la violazione. I problemi provenienti da componenti che non fanno parte di un mapping personalizzato non avranno una proprietà customName.

axe-linter-connector -s . -d . --additional-properties customName

Per esempio, se <MyButton> è un componente mappato personalizzato e genera una violazione button-name, il problema nel rapporto apparirà così:

{
    "engineId": "axe-linter-jsx",
    "ruleId": "button-name (https://dequeuniversity.com/rules/axe/4.11/button-name?application=axe-linter)",
    "customName": "MyButton",
    "severity": "MAJOR",
    "type": "BUG",
    "primaryLocation": {
        "filePath": "/path/to/app.jsx",
        "message": "Buttons must have discernible text",
        "textRange": {
            "startLine": 7,
            "endLine": 7,
            "startColumn": 12,
            "endColumn": 20
        }
    }
}

--api-key api-key
Specifica la chiave API per autorizzare il linting con l'istanza SaaS di Axe DevTools Linter o per utilizzare il linting locale. Vedi Ottenere una Chiave API SaaS di Axe DevTools Linter per maggiori informazioni.

--config nome file
Specifica il nome di un file YAML contenente informazioni di configurazione. Puoi anche usare questa opzione senza un nome file, e Axe DevTools Connector seguirà i passaggi in Ordine di Ricerca del File di Configurazione per individuare il file di configurazione. Per informazioni sul file di configurazione, vedi File di Configurazione.

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

--issue-type tipo
Usato per indicare il tipo di problema per SonarQube, predefinito: BUG, valori consentiti: VULNERABILITY, CODE_SMELL, o BUG

--license-key chiave
Specifica la chiave di licenza da utilizzare per l'autenticazione. Contatta l'assistenza Deque per maggiori informazioni sull'ottenimento di una chiave di licenza. Questa opzione richiede anche l'opzione --local.

--local
Accende il linting locale, che utilizza la macchina su cui sta girando Axe DevTools Connector per valutare i tuoi file invece di inviarli a un server. Richiede una chiave API (--api-key) o una chiave di licenza (--license-key). Vedi 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

--retry-backoff-limit limite-di-attesa
Specifica il tempo massimo in millisecondi che il Connector attenderà prima di riprovare la connessione al server in caso di errore. Il predefinito è 30.000 millisecondi (30 secondi).

--retry-count tentativi
Specifica il numero di volte in cui riprovare la connessione al server dopo aver riscontrato un errore di connessione. Il Connector raddoppierà il tempo tra i tentativi (partendo da 500 millisecondi o 0.5 secondi) fino a raggiungere limite-di-attesa (specificato con --retry-backoff-limit), dove rimarrà fino a quando non raggiungerà il numero specificato di tentativi (e fallirà) o si connetterà al server senza errori.

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

File di Configurazione

Puoi utilizzare un file di configurazione YAML con l'opzione --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à valutato. Le regole nel tag wcag2a saranno utilizzate, come specificato nella sezione tags. (Vedi Tag per ulteriori informazioni.)

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

exclude:
  - tmp/**/*.html

L'esempio sopra esclude tutti i file HTML nella directory tmp e nelle sue sottodirectory.

Per maggiori informazioni sulle opzioni di configurazione consentite, vedi Configurazione di Axe DevTools Linter.

Esempio di utilizzo

Per utilizzare il Connector con il server SaaS di Axe DevTools Linter, puoi usare l'opzione --api-key come mostrato sotto:

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, usa l'opzione --local:

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