De Axe DevTools Linter Connector gebruiken

De Axe DevTools Linter-connector (ook bekend als de Connector) is een command-line tool voor Linux, macOS en Windows. Het biedt een command-line interface om je bestanden te linten, zodat je de toegankelijkheidscontrole kunt automatiseren. Je kunt het bijvoorbeeld gebruiken voor scripting en CI/CD (continuous integration en continuous delivery). De Connector moet je bestanden naar een instantie van Axe Linter Server sturen, ongeacht of deze wordt gehost door Deque (SaaS) of door je eigen organisatie (on prem of on premises), of je kunt de bestanden lokaal linten zonder de inhoud van je bestanden naar een server te sturen met behulp van de --local optie (zie Lokale Linting hieronder).

Gebruiksscenario's voor de Connector

De Axe DevTools Connector kan

• Controleer toegankelijkheid als onderdeel van Jenkins-builds. Voor meer informatie, zie De Axe DevTools Linter met Jenkins gebruiken.
• Scan je bestanden en voer informatie over toegankelijkheidsfouten in SonarQube in. Zie De Axe DevTools Linter met SonarQube gebruiken voor informatie over hoe je dit opzet.
• Word gebruikt in een GitHub pre-commit script om commits die toegankelijkheidsfouten bevatten te blokkeren. Zie Een Git Pre-Commit Hook met Axe DevTools Linter gebruiken.
• Een basis bieden voor het controleren van uw code op toegankelijkheidsfouten voor diensten zoals:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Lokale Linting

De Connector stelt je in staat om te vermijden dat je bestanden naar een server worden gestuurd door lokaal linten te gebruiken met de --local command-line optie.

• Voordelen van Lokale Linting

  • Veel sneller dan het gebruik van de server.
  • Veel minder kans op netwerkproblemen of serverbelasting. Het is vooral efficiënt bij het linten van grote aantallen bestanden.

• Nadelen van Lokale Linting

  • Vereist meer bronnen van de lokale machine.
  • Updates van de Axe DevTools Linter Connector vereisen dat een nieuwe versie van Agora wordt gedownload en geïnstalleerd.
  • Geen gebruikstracking (als u een licentiesleutel in plaats van een API-sleutel gebruikt).

Vergelijking van licentiesleutels met API-sleutels

Lokaal linten vereist ofwel een API-sleutel of een licentiesleutel. Je kunt ze uw API-sleutels beheren als onderdeel van uw Axe-account (zodat ze flexibiliteit bieden). Je moet echter wel een licentiesleutel aanvragen bij Helpdesk van Deque. Het gebruik van lokaal linten met licentiesleutels volgt het gebruik van je gebruikers (regels code die gelint zijn) niet, maar licentiesleutels vereisen ook geen externe authenticatie.

Installatieopties

Er zijn twee opties voor het installeren van de Axe DevTools Linter Connector:

• Stel een Agora npm-register in en gebruik de infrastructuur die wordt geboden door NodeJS en npm om de Connector te installeren, uit te voeren en bij te werken. Zie De Axe DevTools Linter Connector als een npm-pakket installeren voor meer informatie.
• De andere optie is om handmatig de Connector-binair bestand voor de architectuur van je computer te downloaden en klaar te maken voor gebruik door het uitvoerbit in te stellen (Linux en macOS) en eventuele uitgebreide quarantainestattribute(n) te verwijderen (macOS). Zie de downloadpagina.

Omgevingsvariabelen

De Connector herkent de volgende omgevingsvariabelen:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• AXE_SERVICE_URL
• DEBUG

AXE_LINTER_SERVER_URL en AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL stelt de URL in voor je Axe DevTools Linter-serverinstantie. (Je kunt de server-URL ook instellen met -u of --url opdrachtrijopties.) AXE_LINTER_SERVER_PORT specificeert de poort waarop de server luistert, meestal poort 3000.

Zie Axe DevTools Linter instellen voor meer informatie over het opzetten van je server, en zie URL Snelverwijzing voor de URL voor gebruik met de SaaS-versie van Axe DevTools Linter. (Je hoeft geen poort op te geven bij gebruik van de SaaS-versie van Axe DevTools Linter.)

Het volgende voorbeeld toont het instellen van omgevingsvariabelen voor Axe DevTools Linter die lokaal draait op Linux of macOS (hoewel geen van beide omgevingsvariabele hier vereist is, omdat dit de standaardwaarden zijn):

export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000

Als alternatief kun je op Linux en macOS ook de omgevingsvariabelen instellen in dezelfde commandoregel als de axe-linter-connector opdracht. Het onderstaande voorbeeld toont dit gebruik. (Aangezien dit de standaardwaarden zijn voor de server en poort, hoef je ze niet in te stellen.)

AXE_LINTER_SERVER_PORT=3000 AXE_LINTER_SERVER_URL=http://localhost axe-linter-connector -s . -d .

AXE_SERVICE_URL

De AXE_SERVICE_URL omgevingsvariabele stelt je in staat om een alternatieve server op te geven om je API-sleutel te valideren. De standaardwaarde is https://axe.deque.com.

Klanten met een private cloud hebben een toegewijde authenticatieserver op een klant-specifieke URL. Om lokaal te linten, stel je AXE_SERVICE_URL in op je private cloud-instantie-URL voordat je de Connector uitvoert:

export AXE_SERVICE_URL=https://your-org-axedevtools.dequecloud.com
axe-linter-connector -s . -d . --api-key <your-api-key> --local

Je private cloud-instantie-URL werd verstrekt toen je private cloud-instantie werd ingesteld. Als je deze niet hebt, neem dan contact op met Helpdesk van Deque.

DEBUG

De DEBUG omgevingsvariabele stelt je in staat om gedetailleerde debuginformatie te loggen voor het diagnosticeren van lintingfouten. Stel de DEBUG omgevingsvariabele in op axe-devtools-linter:* om debugloggen in te schakelen, zoals hieronder weergegeven:

DEBUG=axe-devtools-linter:* axe-linter-connector -s . -d .

Commandoregelopties

Vereiste commandoregelopties

Axe DevTools Linter Connector vereist de volgende twee opties:

-s, --source directory-of-bestand
Geeft een bestand of een directory aan met bestanden die op toegankelijkheidsfouten gecontroleerd moeten worden. Subdirectories worden ook doorzocht. Om bestanden uit te sluiten van linten, zie de exclude optie in de Configuratiebestand sectie.

-d, --destination directory
De directory waar de Connector het toegankelijkheidsrapport zal schrijven.

-u, --url URL
Geeft de server aan die gebruikt moet worden. De standaard is http://localhost. Om de SaaS-server te gebruiken, specificeer --url https://axe-linter.deque.com/

Optionele commandoregelopties

Verschillende opties kunnen vereist zijn, afhankelijk van welke server je verbinding maakt en welke andere functies of rapportformaten je wilt gebruiken.

--additional-properties eigenschap
Voegt extra eigenschappen toe aan issues in het toegankelijkheidsrapport voor overtredingen gevonden op aangepaste-gemapt componenten. De enige momenteel ondersteunde waarde is customName. Wanneer gespecificeerd, verkrijgt elk issue met betrekking tot een custom-gemapped component een customName eigenschap in het rapport waarvan de waarde de tagnaam is van het custom component dat de overtreding veroorzaakte. Issues van componenten die niet deel uitmaken van een custom mapping zullen geen customName eigenschap hebben.

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

Als bijvoorbeeld <MyButton> een custom-gemapped component is en een button-name overtreding veroorzaakt, zal het probleem in het rapport er als volgt uitzien:

{
    "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-sleutel
Geeft de API-sleutel aan om het linten te autoriseren met de SaaS Axe DevTools Linter-instantie of om lokaal te linten. Zie Een Axe DevTools Linter SaaS API-sleutel verkrijgen voor meer informatie.

--config bestandsnaam
Geeft de naam van een YAML-bestand aan met configuratie-informatie. Je kunt deze optie ook gebruiken zonder een bestandsnaam, en de Axe DevTools Connector zal de stappen volgen in Volgorde van Zoeken naar Configuratiebestand om het configuratiebestand te vinden. Voor informatie over het configuratiebestand, zie Configuratiebestand.

--filename bestandsnaam
Geeft de naam van het SonarQube-rapport aan, standaard: axe-linter-report.json

--issue-type type
Wordt gebruikt om het type probleem voor SonarQube aan te geven, standaard: BUG, toegestane waarden: VULNERABILITY, CODE_SMELL of BUG

--license-key sleutel
Geeft de licentiesleutel aan die gebruikt moet worden voor authenticatie. Neem contact op met de Deque Helpdesk voor meer informatie over het verkrijgen van een licentiesleutel. Deze optie vereist ook de --local optie.

--local
Schakelt lokaal linten in, wat gebruikmaakt van de machine waarop de Axe DevTools Connector draait om je bestanden te linten in plaats van de bestanden naar een server te sturen. Vereist een API-sleutel (--api-key) of een licentiesleutel (--license-key). Zie Lokale Linting.

axe-linter-connector -s . -d . --api-key 1234 --local --url https://axe-linter.deque.com/

-R, --reporter reporter
Geeft de rapporteur aan die gebruikt moet worden, standaard: sonarqube

--retry-backoff-limit backoff-limiet
Geeft de maximale tijd in milliseconden die de Connector zal wachten voordat de serververbinding opnieuw wordt geprobeerd bij een fout. De standaard is 30.000 milliseconden (30 seconden).

--retry-count herhalingen
Geeft het aantal keren aan dat opnieuw geprobeerd wordt verbinding te maken met de server na een verbindingsfout. De Connector zal de tijd tussen pogingen verdubbelen (beginnend bij 500 milliseconden of 0,5 seconden) totdat het de backoff-limiet bereikt (gespecificeerd met --retry-backoff-limit), waar het zal blijven tot het opgegeven aantal pogingen is bereikt (en mislukt) of zonder fout verbinding maakt met de server.

--severity niveau
Stelt het ernstniveau in voor SonarQube, standaard: MAJOR, toegestane waarden: BLOCKER, CRITICAL, MAJOR, MINOR of INFO.

Configuratiebestand

Je kunt een YAML-configuratiebestand gebruiken met de --config optie.

Het volgende toont een voorbeeldconfiguratiebestand:

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

In het bovenstaande voorbeeld zal de regel image-alt worden genegeerd, en het bestand meta-refresh.html zal niet gelint worden. De regels in de wcag2a tag zullen worden gebruikt, zoals gespecificeerd in de tags sectie. (Zie Tags voor meer informatie.)

De exclude waarde staat glob-waarden toe (*) en globstar (**), dus het volgende is toegestaan:

exclude:
  - tmp/**/*.html

Het bovenstaande voorbeeld sluit alle HTML-bestanden uit in de tmp directory en zijn subdirectories.

Voor meer informatie over toegestane configuratie-opties, zie Configuratie van Axe DevTools Linter.

Voorbeeldgebruik

Om de Connector te gebruiken met de Axe DevTools Linter SaaS-server, kun je de --api-key optie gebruiken zoals hieronder weergegeven:

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

Om alle linting lokaal uit te voeren op de computer waarop Axe DevTools Connector draait, gebruik de --local optie:

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