Utilizzo dell'azione GitHub axe DevTools Linter

Questo articolo mostra come utilizzare l'azione GitHub axe DevTools Linter di Deque per verificare la presenza di errori di accessibilità nel codice durante la creazione di una richiesta pull di GitHub. Dopo l'esecuzione dell'azione, la richiesta pull conterrà commenti che mostrano gli errori di accessibilità nei file committati.

Le sezioni seguenti mostrano i passaggi per impostare questa azione GitHub con il tuo repo.

Step 1: Obtain an API Key (SaaS Only)

Per axe DevTools Linter SaaS, è necessario ottenere una chiave API. Puoi ottenerne uno seguendo i passaggi indicati in Ottenere una chiave API SaaS Linter di axe DevTools, oppure puoi utilizzare una chiave API esistente dalla pagina delle impostazioni per il tuo account axe. In caso di problemi nell'ottenere una chiave API, contattare l'help desk di Deque.

Step 2: Create a Repository Secret for Your API Key (SaaS Only)

Se utilizzi axe DevTools Linter SaaS, devi aggiungere la tua chiave API ai segreti del tuo repository, cosa che puoi fare andando alla pagina Impostazioni del tuo repository su GitHub. Per ulteriori informazioni, vedere Creazione di segreti crittografati per un repository su GitHub Docs.

Per il flusso di lavoro di esempio nel passaggio successivo, i segreti dovrebbero essere chiamati:

• AXE_LINTER_API_KEY per la chiave API

Passaggio 3: Creare il flusso di lavoro

Successivamente, devi creare un flusso di lavoro per verificare la presenza di errori di accessibilità nei file. Puoi creare un file denominato axe-linter.yml nella directory .github/workflows del tuo repository.

Puoi creare questo file online come un nuovo flusso di lavoro nella scheda Azioni sulla pagina web del tuo repository (clicca su Imposta tu stesso un flusso di lavoro nella sezione Inizia con GitHub Actions nella parte superiore della pagina Azioni ) oppure crearlo localmente e inviarlo al tuo repository.

L'azione axe-linter viene richiamata nel flusso di lavoro quando viene creata una richiesta pull (on: [pull_request]). Il flusso di lavoro utilizza due dipendenze:

• actions/checkout@v4
• dequelabs/axe-linter-action@v1

Le sezioni seguenti mostrano esempi di .github/workflows/axe-linter.yml che è possibile utilizzare per le versioni SaaS o on-prem di axe DevTools Linter:

Per SaaS

La versione SaaS del flusso di lavoro include il parametro api_key ma non include il parametro axe_linter_url :

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v1
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}          github_token: ${{ secrets.GITHUB_TOKEN }}

Per On-Prem

La versione on-prem del flusso di lavoro include il parametro axe_linter_url ma non include il parametro api_key :

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          axe_linter_url: $AXE_LINTER_URL

In questo esempio, il valore per axe_linter_url viene letto dall'ambiente shell come AXE_LINTER_URL.

Per la versione on-premise di axe DevTools Linter, non è necessaria una chiave API, ma l'istanza di axe DevTools Linter deve essere raggiungibile dai flussi di lavoro GitHub tramite una connessione di rete.

Parametri Azione GitHub

dequelabs/axe-linter-action utilizza i seguenti parametri (specificati negli esempi precedenti nella clausola with ):

Risultati del flusso di lavoro

La seguente schermata mostra il risultato della creazione di una richiesta pull con un file che presenta un errore di accessibilità. Il file bad-file.md contiene livelli di intestazione che vanno dal livello 1 al livello 3, saltando il livello 2, il che costituisce un errore di accessibilità.

Una pull request su GitHub e l'errore segnalato dall'azione GitHub axe DevTools Linter. Il file sul lato destro dell'immagine contiene un errore di accessibilità in cui le intestazioni saltano il livello 2. È presente un avviso di errore dall'azione GitHub che fornisce dettagli sull'errore.(../images/screen-gha-in-action.png)

Risoluzione dei problemi

Il debug dei problemi con le azioni di GitHub può essere complicato perché i messaggi di errore spesso non riescono a rappresentare accuratamente il problema sottostante. Questa sezione contiene alcuni esempi di errori che potresti visualizzare.

Incorrectly Named Secret (SaaS Only)

Se il nome assegnato alla chiave API segreta non corrisponde al nome nel flusso di lavoro, potresti ricevere errori relativi a un comando mancante anziché un errore relativo alla chiave non definita:

... line 41: Missing: command not found

Errori di autorizzazione

Ci sono molti punti nelle azioni GitHub in cui le autorizzazioni possono essere errate. Ad esempio, se fai riferimento a un repository che non è pubblico con una clausola uses , spesso riceverai l'errore che il repository non è stato trovato invece di non avervi accesso:

fatal: repository 'name' not found

File controllati dall'azione

I file con queste estensioni verranno controllati per errori di accessibilità:

• .js
• .jsx
• .tsx
• .html
• .vue
• .md
• .markdown

Prossimi passi

Per informazioni sulle regole utilizzate da axe DevTools Linter per controllare il codice, vedere Regole di accessibilità. Per saperne di più su come impedire che i file con errori di accessibilità vengano committati su Git, consulta Utilizzo di un Git Pre-Commit-Hook.