Utilizzo di Axe DevTools Linter Connector

Il Axe DevTools Linter Connector (noto anche come il Connector) è uno strumento da linea di comando per Linux, macOS e Windows. Fornisce un'interfaccia a riga di comando per analizzare i tuoi file in modo da poter automatizzare il tuo controllo sull'accessibilità. Puoi, ad esempio, utilizzarlo per scripting e CI/CD (integrazione continua e distribuzione continua). Il Connector deve inviare i tuoi file a un'istanza di Axe Linter Server, ospitata da Deque (SaaS) o dalla tua organizzazione (on prem o on premises), oppure puoi analizzare localmente i file 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ò

• controllare l'accessibilità come parte delle build di Jenkins. Per ulteriori informazioni, vedi Uso di Axe DevTools Linter con Jenkins.
• Analizzare i tuoi file e fornire informazioni sui difetti di accessibilità a SonarQube. Vedi Uso di Axe DevTools Linter con SonarQube per informazioni su come configurarli.
• 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 l'invio dei tuoi file a un server utilizzando il linting locale con l'opzione della linea 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 (perciò offrono flessibilità). Tuttavia, devi richiedere una chiave di licenza a Help Desk di Deque. L'utilizzo del linting locale con chiavi di licenza non traccia l'uso da parte degli utenti (linee di codice analizzate), ma le chiavi di licenza non richiedono nemmeno autenticazione remota.

Opzioni di Installazione

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

• Impostare un registro npm Agora e utilizzare l'infrastruttura fornita da NodeJS e npm per installare, eseguire e aggiornare il Connector. Consulta Installazione del Axe DevTools Linter Connector come pacchetto npm per maggiori informazioni.
• L'altra opzione è scaricare manualmente il file binario del Connector per l'architettura del tuo computer e prepararlo per l'uso impostando il bit di esecuzione (Linux e macOS) ed eliminando eventuali attributi di quarantena estesi (macOS). Consulta 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 l'istanza del server Axe DevTools Linter. (Puoi anche impostare l'URL del server con le -u o le --url opzioni della riga di comando.) AXE_LINTER_SERVER_PORT specifica la porta su cui il server ascolta, tipicamente la porta 3000.

Consulta Configurazione di Axe DevTools Linter per maggiori informazioni sulla configurazione del tuo server, e consulta 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 axe-linter-connector comando. 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 .

AXE_SERVICE_URL

La AXE_SERVICE_URL variabile d'ambiente ti consente di specificare un server alternativo per convalidare la tua chiave API. Questa variabile d'ambiente è utile per le organizzazioni che utilizzano un'istanza server privata per la convalida delle chiavi API. Il valore predefinito è https://axe.deque.com.

Per ulteriori informazioni sull'utilizzo di server alternativi per la convalida delle chiavi API, contatta l'Help Desk di Deque.

DEBUG

L' DEBUG variabile d'ambiente ti permette di registrare informazioni dettagliate di debug per diagnosticare i fallimenti di linting. Imposta la DEBUG variabile d'ambiente su axe-devtools-linter:* per attivare il log di 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à. Anche le sottodirectory vengono cercate. Per escludere i file dal linting, consulta l'opzione exclude nel File di Configurazione .

-d, --destination directory
La directory in cui il Connector scriverà il report di accessibilità.

-u, --url URL
Specifica il server da utilizzare. L'impostazione predefinita è 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 alle problematiche nel report di accessibilità per le violazioni trovate su componenti mappati su misura. L'unico valore attualmente supportato è customName. Quando specificato, ogni questione che coinvolge un componente mappato su misura acquisisce una customName proprietà nel report il cui valore è il nome del tag del componente personalizzato che ha generato la violazione. Le problematiche derivanti da componenti che non fanno parte di un mapping personalizzato non avranno una customName proprietà.

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

Ad esempio, se <MyButton> è un componente mappato su misura e genera una button-name violazione, la questione nel report 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 usare 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 di SonarQube, predefinito: axe-linter-report.json

--issue-type tipo
Usato per indicare il tipo di questione 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 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 sulla quale il connettore Axe DevTools è in esecuzione per analizzare i tuoi file piuttosto che 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 massimo tempo in millisecondi che il connettore aspetterà prima di ritentare la connessione al server in caso di errore. Il valore predefinito è 30.000 millisecondi (30 secondi).

--retry-count tentativi
Specifica il numero di volte in cui tentare di nuovo la connessione al server dopo aver riscontrato un errore di connessione. Il connettore raddoppierà il tempo tra i tentativi (partendo da 500 millisecondi o 0,5 secondi) fino a raggiungere il limite-di-attesa (specificato con --retry-backoff-limit), e manterrà tale limite fino a raggiungere il numero specificato di tentativi (e fallire) o connettersi 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à analizzato. Le regole nel tag wcag2a verranno utilizzate, come specificato nella sezione tags . (Vedi Tag per maggiori informazioni.)

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

exclude:
  - tmp/**/*.html

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

Per ulteriori informazioni sulle opzioni di configurazione consentite, consulta Configurazione di Axe DevTools Linter.

Esempio di utilizzo

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

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

Per eseguire tutta la linting localmente sul computer che esegue Axe DevTools Connector, usa l' --local opzione:

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