Utilizzo di Axe DevTools Linter con SonarQube
Come integrare Axe DevTools Linter con SonarQube per monitorare il codice e rilevare problemi di accessibilità
Puoi integrare Axe DevTools Linter con SonarQube per monitorare il tuo codice e rilevare problemi di accessibilità. Puoi utilizzare le idee qui presentate per integrare i sistemi CI/CD con SonarQube. Nella documentazione di SonarQube, consulta la Panoramica dell'integrazione CI per informazioni su come utilizzare GitLab CI/CD, GitHub Actions, Azure Pipelines o Bitbucket Pipelines.
Panoramica sull'Integrazione con SonarQube
L'elemento chiave per l'integrazione con SonarQube è lo strumento da riga di comando, Connettore Axe DevTools Linter. Lo strumento esegue la scansione dei tuoi file e crea un rapporto che viene poi caricato su SonarQube tramite lo strumento CLI di SonarScanner. I passaggi nel dettaglio includono:
- Scansione dei file nelle directory locali.
- Invio dei file al Server Axe DevTools Linter per l'analisi o analisi dei file localmente.
- Raccolta dei risultati dell'analisi come un rapporto JSON compatibile con SonarQube.
- Esecuzione dello strumento SonarScanner CLI su questo rapporto per inviare i problemi a SonarQube come problemi esterni. In questo caso, lo strumento SonarScanner non esegue in realtà la scansione di alcun file. Riporta semplicemente i problemi trovati da Axe DevTools Linter come problemi esterni.
I primi tre passaggi sono eseguiti dal Connettore Axe DevTools, e l'ultimo passaggio è eseguito dal SonarScanner CLI.
La tua integrazione CI/CD personalizzata deve eseguire queste azioni:
- Avvia il Connettore Axe DevTools Linter con gli argomenti appropriati da riga di comando per scansionare i file del tuo progetto e produrre un rapporto JSON compatibile con SonarQube.
- Avvia il SonarScanner CLI per inviare i risultati dell'analisi a SonarQube.
Requisiti
- Connettore Axe DevTools Linter: Consulta Utilizzo di Connettore Axe DevTools Linter per le istruzioni di installazione e utilizzo.
- SonarQube: Questa integrazione è stata testata con SonarQube Community Build 26.4. SonarQube ha modificato il suo Formato Generico Importazione Problemi nella versione 10.3, e le versioni future potrebbero richiedere il formato aggiornato. Se incontri avvisi o problemi di importazione, verifica che le versioni del Connettore Axe DevTools Linter e di SonarQube siano compatibili.
- SonarScanner CLI: Consulta SonarScanner CLI per maggiori informazioni su come scaricare questo strumento.
Configurazione di SonarQube
Per configurare SonarQube, crea un profilo, poi elimina le regole ridondanti dal profilo per disattivarle (alcune regole nei profili appena creati in SonarQube si sovrappongono alle regole controllate da Axe DevTools Linter, risultando in errori duplicati). Puoi eliminare le regole sovrapposte nell'interfaccia di amministrazione di SonarQube. Le sezioni seguenti descrivono come fare.
Crea un Nuovo Profilo di Qualità
Per modificare le regole, fai clic su Profili di Qualità nella parte superiore del sito di amministrazione di SonarQube. Poi fai clic sul menù a tendina Filtra i profili per: e seleziona HTML. Dovresti ora vedere il profilo HTML predefinito di SonarQube. Devi duplicare quel profilo facendo clic sul menù a ingranaggio sulla destra del profilo e scegliendo Copia. SonarQube ti chiederà di assegnare un nome al nuovo profilo copiato. Chiamalo Accessorio di Linter e fai clic sul pulsante Copia.
Ora hai un nuovo profilo di qualità HTML chiamato Accessorio di Linter. Scegli il menù a ingranaggio per il profilo Accessorio di Linter e scegli Imposta come Predefinito affinché questo profilo venga usato per controllare tutti i file HTML.
Rimuovi Regole Ridondanti
Il passo successivo è rimuovere le regole ridondanti dal profilo di Qualità Accessorio di Linter che hai creato. Nell'elenco delle regole HTML, dovrebbero esserci due profili. Il profilo Accessorio di Linter e il profilo standard Sonar. Fai clic sul profilo Accessorio di Linter per accedere alla pagina di configurazione del profilo. Nella parte sinistra dello schermo, dovresti vedere un elenco di diversi tipi di regole nel profilo. Fai clic sul numero in alto a destra di Totale e nella colonna Attive per modificare le regole attive.
Sul lato destro del display c'è un elenco di regole abilitate nel profilo HTML Axe Linter. Disabilita le regole ridondanti indicate di seguito:
- I tag
<fieldset>dovrebbero contenere un<legend> - I link non dovrebbero rivolgersi direttamente alle immagini
- I tag immagine, area e pulsante con immagini dovrebbero avere un attributo "alt"
- I tag
<th>dovrebbero avere attributiidoscope - Le celle della tabella dovrebbero fare riferimento alle loro intestazioni
- I tag
<object>dovrebbero fornire contenuti alternativi - I tag
<strong>e<em>dovrebbero essere utilizzati - I tag
<table>dovrebbero avere una descrizione - I video dovrebbero avere sottotitoli
- Non dovrebbero essere utilizzate mappe immagini lato server (attributo
ismap) - L'elemento
<html>dovrebbe avere un attributo di lingua <frames>dovrebbe avere un attributotitle<table>HTML non dovrebbe essere utilizzato a scopi di layout- Le tabelle utilizzate per il layout non dovrebbero includere markup semantico
- Gli attributi
aria-labeloaria-labelledbydovrebbero essere utilizzati per differenziare elementi simili - Le tabelle dovrebbero avere intestazioni
Queste regole sono menzionate nel passaggio 5 di questo articolo di supporto Deque.
Avrai bisogno di un account Deque per accedere all'articolo di supporto che include le regole ridondanti. Consulta questo articolo per maggiori informazioni sul Centro Assistenza e per ottenere un account.
Crea un file di configurazione SonarQube
È necessario creare un file di configurazione per il SonarScanner CLI di SonarQube. Di seguito è riportato un esempio di file di configurazione, sonar-project.properties.
sonar.projectKey=Test-Deque
sonar.externalIssuesReportPaths=axe-linter-report.jsonIl sonar.projectKey è il nome del progetto in SonarQube dove desideri che SonarScanner riporti i risultati.
Genera un token di sicurezza SonarQube
Il SonarQube Scanner deve essere in grado di connettersi a SonarQube per riportare i risultati. Puoi farlo creando un token di accesso nell'interfaccia web di amministrazione di SonarQube.
Per creare un token di accesso, fai clic su Amministrazione in alto al centro della schermata nell'interfaccia web di amministrazione di SonarQube. Quindi clicca sul menu a tendina Sicurezza vicino alla parte superiore dello schermo e scegli Utenti. Scegli un utente per riportare i risultati a SonarQube e fai clic sull'icona sotto Token per creare un token di sicurezza per quell'utente. Nella finestra popup sotto Genera Token, digita il nome del token e clicca su Genera. Salva il valore di questo token (una stringa esadecimale a 32 bit) perché non potrai più visualizzarlo dopo aver chiuso la finestra Token. (Puoi, tuttavia, generare un nuovo token in qualsiasi momento.)
Il SonarScanner CLI utilizza questo token per riportare i risultati al server. Dovrebbe essere impostato nella variabile di ambiente SONAR_TOKEN.
Esegui l'integrazione
Una volta configurate le regole SonarQube, creato un file di configurazione e generato un token di sicurezza, puoi eseguire l'integrazione. Il processo si compone di due fasi:
- Esegui Axe DevTools Linter Connector per scansionare i file del tuo progetto e generare un report compatibile con SonarQube.
- Esegui SonarScanner CLI per caricare il report su SonarQube.
Genera il report del Linter
Esegui Axe DevTools Linter Connector dalla stessa directory del tuo file sonar-project.properties:
axe-linter-connector -s . -d .Questo produce axe-linter-report.json nella directory corrente. Consulta Utilizzando Axe DevTools Linter Connector per opzioni del server, autenticazione e altre opzioni della riga di comando.
Il Connector deve essere eseguito dalla directory base del progetto SonarScanner affinché i percorsi dei file nel report corrispondano ai file che SonarQube si aspetta.
Caricare il rapporto su SonarQube
Imposta la variabile d'ambiente SONAR_TOKEN sul token di sicurezza che hai generato, quindi esegui la CLI di SonarScanner:
export SONAR_TOKEN=<your-sonarqube-token>
sonar-scanner -Dsonar.host.url=<sonarqube-server-url>Sostituisci <sonarqube-server-url> con l'URL del tuo server SonarQube (ad esempio, http://localhost:9000).
La CLI di SonarScanner legge il file sonar-project.properties, trova il rapporto specificato in sonar.externalIssuesReportPaths e carica i problemi su SonarQube come problemi esterni.
Visualizzare i risultati
Eventuali problemi trovati da Axe DevTools Linter verranno mostrati quando si fa clic su Problemi nell'interfaccia web di SonarQube per il tuo progetto. I problemi di Axe DevTools Linter sono identificati da AXE-LINTER-MD per i file Markdown e da AXE-LINTER-HTML per i file HTML.
Il rapporto
Axe DevTools Linter Connector genera un rapporto JSON che segue il Formato di importazione generico di problemi di SonarQube.
Puoi modificare alcune delle opzioni nel rapporto utilizzando le opzioni della riga di comando di Axe DevTools Linter Connector. Vedi Opzioni facoltative della riga di comando per ulteriori informazioni.