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 Web API/CLI, è possibile usare il servizio REST di Axe Developer Hub come base per la propria integrazione.

Panoramica

L'Azione GitHub di Axe Developer Hub ti consente di configurare i workflow GitHub per progetti web che integrano Axe Watcher, per bloccare commit e pull request se contengono errori di accessibilità.

Quando il tuo suite di test modificata è in esecuzione, associa i risultati di accessibilità con un Git commit SHA e invia tali informazioni ai server di Deque. L'azione GitHub viene eseguita dopo il tuo suite di test è in esecuzione e interroga i server di Deque per i risultati di accessibilità associati all'ultimo commit SHA del ramo corrente.

I nuovi conteggi delle questioni risolte che i rapporti di Azione usano si basano su baseline dal commit precedente che ha una scansione su quel ramo, non sul ramo predefinito. Solo i commit su cui è stato effettivamente eseguito il tuo suite di test hanno una scansione, quindi quel commit baseline potrebbe trovarsi diversi commit indietro. Se quel commit ha eseguito un set di test diverso, i conteggi rifletteranno la differenza di copertura piuttosto che un cambiamento reale; vedi Best practice per confronti accurati.

Impostazione

  1. Crea una Variabile d'Ambiente per il Tuo ID Progetto - Ti consigliamo di memorizzare il tuo ID progetto in una variabile d'ambiente o altra variabile GitHub. In questo esempio, memorizzaremo 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 viene chiamato AXE_DEV_HUB_API_KEY, con la tua chiave API personale come valore, ma puoi nominare il segreto come preferisci. Deve essere referenziato con lo stesso nome nel job del workflow. La tua chiave API è una credenziale: conservala sempre come un segreto di GitHub Actions invece di inserirla direttamente 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 Flusso di Lavoro Attuale - Devi modificare il tuo workflow del test runner corrente in .github/workflows e aggiungere l'azione GitHub dopo il lavoro che esegue la tua suite di test.

Esempio di Job

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

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 lavoro axe-dev-hub nell'esempio dipende dal lavoro che esegue la tua suite di test, specificato con la linea needs: your-CI-test. Assicurati di aggiornare questa linea per farla corrispondere al nome del lavoro che esegue la tua suite di test.

Puoi utilizzare più parametri di input per l'Azione GitHub. Ad esempio, puoi abilitare il soglia di accessibilità utilizzando enable_a11y_threshold: true. Un elenco completo dei parametri di input è disponibile nel README di Axe Developer Hub GitHub Action.

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'implementazione on-premises di Axe Developer Hub, devi impostare server_url sull'URL di base di quell'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 a11y.

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

Il fallimento dell'azione GitHub allegherà un commento simile a quello sotto alla tua richiesta di pull e può bloccare l'integrazione.

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 richiesta di pull per esaminare 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

Verifica di avere le autorizzazioni necessarie nella pagina delle impostazioni per le azioni. Hai bisogno di autorizzazioni di lettura e scrittura per consentire all'azione di aggiungere commenti alle pull request. Per maggiore granularità, puoi scegliere di utilizzare una diversa GITHUB_TOKEN per l'azione GitHub. Aggiungi questo valore al parametro di input github_token.

Esempio di flusso di lavoro

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

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

Il lavoro della tua suite di test dovrebbe sempre essere eseguito prima l'azione GitHub di Axe Developer Hub.

tip

La directory di esempio contiene un progetto di test completo con cui puoi fare esperimenti.

Riferimenti

Is this page helpful?

Help us improve this page

Still need help?