De Axe DevTools Linter Connector gebruiken

De Axe DevTools Linter Connector (ook bekend als de Connector) is een commandoregeltool voor Linux, macOS en Windows. Het biedt een commandoregelinterface om uw bestanden te linten, zodat u de toegankelijkheidscontrole kunt automatiseren. U kunt het bijvoorbeeld gebruiken voor scripting en CI/CD (continuous integration en continuous delivery). De Connector moet uw bestanden naar een instantie van Axe Linter Server sturen, of die nu wordt gehost door Deque (SaaS) of door uw organisatie (on prem of on premises), of u kunt de bestanden lokaal linten zonder de inhoud van uw bestanden naar een server te sturen met de --local optie (zie Lokale Linting hieronder).

Gebruiksscenario's voor de Connector

De Axe DevTools Connector kan

• Toegankelijkheid controleren als onderdeel van Jenkins-builds. Voor meer informatie, zie De Axe DevTools Linter met Jenkins gebruiken.
• Uw bestanden scannen en informatie over toegankelijkheidsfouten naar SonarQube sturen. Zie De Axe DevTools Linter met SonarQube gebruiken voor informatie over hoe dit moet worden ingesteld.
• Worden gebruikt in een GitHub pre-commit script om commits te blokkeren die toegankelijkheidsfouten bevatten. 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 u in staat om te voorkomen dat u uw bestanden naar een server stuurt door lokale linting te gebruiken met de --local commandoregeloptie.

• 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

Voor lokaal linten is een API-sleutel of een licentiesleutel vereist. U kunt uw API-sleutels beheren als onderdeel van uw Axe-account (waardoor ze flexibiliteit bieden). U moet echter een licentiesleutel aanvragen bij de Helpdesk van Deque. Lokaal linten met licentiesleutels volgt het gebruik van uw gebruikers niet (aantal gelinte coderegels), 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 van NodeJS en npm om de Connector te installeren, te draaien 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-binary te downloaden voor de architectuur van uw computer en deze voor te bereiden voor gebruik door het uitvoerbit in te stellen (Linux en macOS) en eventuele uitgebreide quarantainetoeschrijvingen 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 uw Axe DevTools Linter-serverinstance. (U kunt de server-URL ook instellen met de -u of de --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 instellen van uw server, en zie URL Snelverwijzing voor de URL voor gebruik met de SaaS-versie van Axe DevTools Linter. (U 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 kunt u op Linux en macOS de omgevingsvariabelen ook instellen op dezelfde opdrachtrij als de axe-linter-connector opdracht. Het onderstaande voorbeeld toont dit gebruik. (Echter, omdat dit de standaardwaarden voor de server en poort zijn, hoeft u 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 u in staat een alternatieve server op te geven om uw API-sleutel te valideren. Deze omgevingsvariabele is nuttig voor organisaties die een privéserverinstantie gebruiken voor API-sleutelvalidatie. De standaardwaarde is https://axe.deque.com.

Voor meer informatie over het gebruik van alternatieve servers voor API-sleutelvalidatie, neem contact op met de Helpdesk van Deque.

DEBUG

De DEBUG omgevingsvariabele stelt je in staat om gedetailleerde informatie voor probleemoplossing vast te leggen bij linting-fouten. Stel de DEBUG omgevingsvariabele in op axe-devtools-linter:* om debug logging in te schakelen, zoals hieronder getoond:

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 die bestanden bevat die moeten worden gecontroleerd op toegankelijkheidsfouten. Ook subdirectory's worden doorzocht. Om bestanden uit te sluiten van linting, zie de exclude optie in het Configuratiebestand gedeelte.

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

-u, --url URL
Geeft de server aan die moet worden gebruikt. 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 problemen in het toegankelijkheidsrapport voor overtredingen die zijn gevonden bij aangepaste-gemapt componenten. De enige momenteel ondersteunde waarde is customName. Wanneer gespecificeerd, krijgt elk probleem met een aangepast gemapt component een customName eigenschap in het rapport waarvan de waarde de tagnaam is van het aangepaste component dat de overtreding veroorzaakte. Problemen van componenten die geen deel uitmaken van een aangepaste mapping zullen geen customName eigenschap hebben.

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

Bijvoorbeeld, als <MyButton> een aangepast gemapt 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
Bepaalt de API-sleutel om autorisatie te geven voor linting met de SaaS Axe DevTools Linter-instantie of om lokale linting te gebruiken. Zie Een Axe DevTools Linter SaaS API-sleutel verkrijgen voor meer informatie.

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

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

--issue-type type
Gebruikt om het probleemtype voor SonarQube aan te geven, standaard: BUG, toegestane waarden: VULNERABILITY, CODE_SMELL, of BUG

--license-key sleutel
Specificeert de licentiesleutel die gebruikt wordt 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 lokale linting in, waarbij de machine waar de Axe DevTools Connector op draait gebruikt wordt om je bestanden te linten in plaats van ze 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
Specificeert de te gebruiken reporter, standaard: sonarqube

--retry-backoff-limit backoff-limiet
Specificeert de maximale tijd in milliseconden die de Connector zal wachten voordat hij opnieuw probeert verbinding te maken met de server na een fout. De standaard is 30.000 milliseconden (30 seconden).

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

--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 genegeerd worden 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 map en zijn submappen.

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

Voorbeeldgebruik

Om de Connector met de Axe DevTools Linter SaaS-server te gebruiken, kunt u 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 die Axe DevTools Connector draait, gebruikt u de --local optie:

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