Utilizzo dell'Azione GitHub di Axe Developer Hub

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

Controlla automaticamente i PR e i commit per i difetti di accessibilità

Not for use with personal data

Richiede:

note

Per altre pipeline CI/CD (come quelle su GitLab, Bitbucket o CircleCI) o quando si utilizza Axe DevTools per le API/CLI Web, puoi utilizzare Commit Status API di Axe Developer Hub come base per la tua integrazione.

Panoramica

Axe Developer Hub GitHub Action ti consente di configurare workflow GitHub per progetti web integrando Axe Watcher, per bloccare commit e pull request se contengono errori di accessibilità.

Quando il tuo suite di test modificata viene eseguito, associa i risultati di accessibilità a un SHA del commit Git e invia tali informazioni ai server Deque. L'azione GitHub viene eseguita dopo dell'esecuzione della tua suite di test, e interroga i server Deque per ottenere i risultati di accessibilità associati all'ultima SHA del commit del branch corrente.

I nuovi e risolti conti dei problemi che l'Azione riporta utilizzano il baseline del commit precedente che ha una scansione su quello stesso branch, non il branch predefinito. Solo i commit sui quali la tua suite di test è stata effettivamente eseguita hanno una scansione, quindi quel commit baseline può risalire a diversi commit precedenti. Se quel commit ha eseguito un set di test diverso, i conti rifletteranno la differenza di copertura piuttosto che un cambiamento reale; vedi Migliori pratiche per confronti accurati.

Configurazione

  1. Crea una Variabile d'Ambiente per il Tuo ID Progetto - Raccomandiamo di memorizzare il tuo ID progetto in una variabile d'ambiente o un'altra variabile GitHub. In questo esempio, memorizzeremo l'ID progetto come una variabile d'ambiente chiamata PROJECT_ID.

  2. Crea un Segreto per la Tua Chiave API - In questo esempio, il segreto creato è chiamato AXE_DEV_HUB_API_KEY, con la tua chiave API personale come valore, ma puoi chiamare il segreto come preferisci. Deve essere richiamato con lo stesso nome nel job del workflow. La tua chiave API è una credenziale: memorizzala sempre come segreto di GitHub Actions piuttosto che inserirla nel file del workflow.

  3. Aggiungi Controlli di Accessibilità alla Tua Suite di Test - Assicurati di aver completato i passaggi in configurazione del progetto per integrare i controlli di accessibilità nella suite di test utilizzata nella tua pipeline CI/CD (Axe Watcher).

  4. Modifica il Tuo Workflow Attuale - Devi modificare il tuo attuale workflow del test runner in .github/workflows e aggiungere l'azione GitHub dopo al job che esegue la tua suite di test.

Esempio di Job

Il job che segue l'azione della tua suite di test dovrebbe eseguire l'azione Axe Developer Hub GitHub. Fai riferimento all'esempio seguente:

jobs:

# ...
# your-CI-test
# ...

# Add the following new job:
# Be sure to replace <choose_latest_tag> with the appropriate version tag
  axe-dev-hub:
    runs-on: ubuntu-latest
    needs: your-CI-test
    steps:
      - uses: actions/checkout@v5
      - uses: dequelabs/axe-devhub-action@<choose_latest_tag>
        with:
          api_key: ${{ secrets.axe_DEV_HUB_API_KEY }}
          project_id: ${{ env.PROJECT_ID }}

Il axe-dev-hub job nell'esempio dipende dal job che esegue la tua suite di test, specificato con la linea needs: your-CI-test. Assicurati di aggiornare questa linea per corrispondere al nome del job che esegue la tua suite di test.

Puoi utilizzare diversi parametri di input per la GitHub Action. Ad esempio, puoi abilitare la soglia di a11y utilizzando enable_a11y_threshold: true. Un elenco completo dei parametri di input può essere trovato nel Axe Developer Hub GitHub Action README.

note

Non è necessario impostare il parametro server_url se hai creato il tuo progetto su axe.deque.com. Se la tua organizzazione utilizza un'istanza regionale, cloud privato o un'installazione in loco di Axe Developer Hub, devi impostare server_url sull'URL base di tale istanza (ad esempio, https://axe-eu.deque.com).

Risultati

L'azione GitHub imposta diversi parametri di output, inclusi un conteggio dei problemi di accessibilità rilevati, problemi risolti e problemi che superano la soglia di a11y.

Se non hai abilitato la soglia di a11y, l'Azione GitHub fallirà ogni volta che sono presenti più di zero errori di accessibilità. Se abilitata, solo le violazioni che superano la soglia di a11y faranno fallire l'Azione GitHub. Scopri di più sull'uso della soglia di a11y per personalizzare Axe Developer Hub in base a ciò che la tua organizzazione desidera prioritizzare.

Il fallimento dell'Azione GitHub allega un commento simile a quello qui sotto alla tua pull request e può bloccare il merging.

Un esempio di messaggio che l'azione GitHub allega a una richiesta di push quando vengono trovati errori di accessibilità.

Clicca sul link nel commento della pull request per rivedere le informazioni sui difetti di accessibilità per quel commit in Axe Developer Hub.

Risoluzione dei problemi

Potresti ricevere un errore come il seguente:

Error: Resource not accessible by integration

Controlla di avere le autorizzazioni necessarie nella pagina delle impostazioni per le azioni. Hai bisogno di permessi di lettura e scrittura per permettere all'azione di aggiungere commenti alle pull request. Per maggiore granularità, potresti scegliere di utilizzare un GITHUB_TOKEN diverso per l'azione GitHub. Aggiungi questo valore al parametro di input github_token.

Esempio di Workflow

Se non hai già un workflow che esegue la tua suite di test, puoi utilizzare l'esempio di workflow come punto di partenza per creare il tuo test runner.

Il flusso di lavoro di esempio si chiama Test (tests.yml) e viene eseguito su ogni commit o pull request. Il job che esegue la suite di test modificata, cypress, mostra come eseguire una suite di test Cypress. Il job successivo nell'esempio, axe-dev-hub, è un'invocazione dell'azione GitHub di Axe Developer Hub.

Il tuo job di suite di test dovrebbe sempre eseguire prima l'azione GitHub di Axe Developer Hub.

tip

La directory d'esempio contiene un progetto di test completo con cui puoi sperimentare.

Riferimenti

Is this page helpful?

Help us improve this page

Still need help?