Pagina's analyseren met behulp van specificatiebestanden

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

Hoe de subcommando's spec en bulk-spec te gebruiken om pagina's te analyseren met behulp van specificatiebestanden

Not for use with personal data

Een specificatiebestand is een JSON- of YAML-bestand dat een lijst met webpagina's en de browseracties definieert die op elke pagina moeten worden uitgevoerd voordat er op toegankelijkheidsproblemen wordt geanalyseerd. Gebruik axe spec om een enkel specificatiebestand uit te voeren, of axe bulk-spec om een map met specificatiebestanden te verwerken.

De axe spec commando 

axe spec <spec-file> <output-dir> [options]

De <output-dir> is waar de JSON-resultaten worden opgeslagen. Als deze wordt weggelaten, worden de resultaten opgeslagen in de huidige werkmap.

Voorbeeldgebruik:

axe spec ./axe-workflow.yaml ./axe-results --format html

Structuur van het specificatiebestand

Een specificatiebestand definieert een of meer projecten, elk met een lijst van te analyseren pagina's en optionele acties die op elke pagina moeten worden uitgevoerd.

YAML Voorbeeld

projects:
  - name: deque.com
    id: deque.com
    metadata:
      products:
        - CLI
      environment:
        - Prod
    globalActions:
      - dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept"
    pageList:
      - name: Deque search
        url: https://www.deque.com/
        actions:
          - type "axe" into element "#searchform input"
          - click element "#searchform button"
          - wait for element ".m-search-page" to be found
          - analyze
      - name: Axe Dashboard
        url: https://axe.deque.com/

Project

Eigenschap Type Beschrijving
name string Unieke weergavenaam van het project.
id string Unieke identificatie van het project.
metadata object Optioneel. Willekeurige metadata voor uw gebruiksdoel (bijv. productnaam, omgeving).
globalActions array Optioneel. Acties die reageren op toestandsveranderingen op elke pagina in het project, bijvoorbeeld het wegklikken van een cookiebanner of enquête-pop-up. Zie Globale Acties.
screenshot object Optioneel. Maakt een screenshot van elke pagina na analyse. Zie Screenshots Maken.
pageList array Lijst van te analyseren pagina's. Zie Pagina.

Pagina

Eigenschap Type Beschrijving
name string Weergavenaam van de pagina.
url string URL van de pagina.
actions array Optioneel. Acties om uit te voeren op de pagina voor of na de analyse. Zie Acties.

JSON/YAML-formaat

Specificatiebestanden kunnen worden geschreven in YAML of JSON. De volgende tabel toont dezelfde waarden in elk formaat. Let op dat in JSON actiestrings met dubbele aanhalingstekens moeten worden geëscaped met een backslash.

YAML JSON
type "axe" into element "#searchform input" "type \"axe\" into element \"#searchform input\""
dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept" "dismiss modal \"#CybotCookiebotDialog\" with close button \"#CybotCookiebotDialogBodyButtonAccept\""

Acties

Acties zijn strings in de actions (of globalActions) array van een specificatiebestand. Ze voeren taken uit zoals het klikken op knoppen, het invullen van formulieren, het sluiten van vensters, het wachten op paginastatussen en het uitvoeren van toegankelijkheidsanalyses. Acties worden uitgevoerd in de volgorde waarin ze worden vermeld.

Er zijn twee soorten acties:

  • Pagina-acties worden opeenvolgend uitgevoerd op een specifieke pagina. De analyze actie moet minstens één keer per pagina worden aangeroepen.
  • Globale acties worden uitgevoerd op elke pagina in het project als reactie op statuswijzigingen. Zie Globale Acties.

Volledig Actievoorbeeld

Het volgende voorbeeld logt in bij Deque University en analyseert het dashboard:

projects:
  - name: Deque University login flow
    id: deque-university-login-flow
    pageList:
      - name: homepage
        url: https://dequeuniversity.com/
        actions:
          - click element ".loginLink"
          - wait for element ".loginUsername" to be found
          - type "user@example.com" into element ".loginUsername"
          - type "secretpassword" into element "#loginPassword"
          - click element "input[type=submit]"
          - wait for element ".logoutLink" to be found
          - analyze page

Selectoren

Veel acties nemen een selectorargument dat een element op de pagina identificeert. Een selector kan een CSS-selector of een XPath-selector zijn, gespecificeerd als een enkele string of een lijst van strings.

Om elementen binnen iframes te richten, moet u een lijst gebruiken. Alle selectors in de lijst, behalve de laatste, identificeren opeenvolgende <iframe> elementen waarnaar genavigeerd moet worden, en moeten CSS-selectors zijn. De laatste selector in de lijst identificeert het doel-element en kan een CSS- of XPath-selector zijn. Elke selector in de lijst wordt geëvalueerd binnen de documentcontext die is vastgesteld door de vorige vermelding: de eerste selector is relatief aan het hoofddocument, en elke volgende iframe-selector is relatief aan het document binnen het voorafgaande iframe.

Met een enkele string (geen lijst) kan niet in iframes worden genavigeerd.

Voorbeeld van Iframe-selector

Beschouw deze HTML-structuur:

<body>
  <!-- root document -->
  <iframe class="payment-widget">
    <!-- document inside the payment-widget iframe -->
    <div class="form-wrapper">
      <iframe id="card-fields">
        <!-- document inside the card-fields iframe -->
        <form>
          <input type="text" name="card-number" class="card-input">
        </form>
      </iframe>
    </div>
  </iframe>
</body>

Om het kaartnummerinvoerveld aan te klikken, gebruikt u een selectorlijst. Elke CSS-selector wordt geëvalueerd binnen de documentcontext die is vastgesteld door de vorige vermelding:

# "iframe.payment-widget" is evaluated in the root document
# "#card-fields" is evaluated in the document inside iframe.payment-widget
# ".card-input" is evaluated in the document inside #card-fields
click element [ "iframe.payment-widget", "#card-fields", ".card-input" ]

Om XPath te gebruiken voor het uiteindelijke doel-element (de iframe-selectors moeten nog steeds CSS zijn):

click element [ "iframe.payment-widget", "#card-fields", "//input[@name='card-number']" ]

In JSON:

"click element [\"iframe.payment-widget\", \"#card-fields\", \".card-input\"]"

Pagina-acties

De CLI ondersteunt negen pagina-acties:

  1. analyze: voer een toegankelijkheidsanalyse uit
  2. change: verander de waarde van een <input>, <textarea>, of <select> via JavaScript
  3. click: klik een element aan
  4. dismiss: sluit een popup of modaal
  5. eval: voer willekeurige JavaScript uit
  6. press: druk op een toets (met of zonder modificatoren)
  7. select: selecteer een optie in een <select>
  8. type: typ in een <input>
  9. wait: wacht op een specifieke status of slaap

analyze

De analyze actie voert een toegankelijkheidsanalyse uit. Deze moet minstens één keer per pagina worden aangeroepen. U mag deze meerdere keren aanroepen om een pagina te analyseren op verschillende momenten in een workflow (gebruik de with title variant om resultaten te onderscheiden).

De optionele ruleset parameter specificeert welke regels set gebruikt moet worden. De standaard is WCAG 2.1 AA. Beschikbare regelsets:

Regelset ID Standaard
wcag2 WCAG 2.0 AA
wcag2.1 WCAG 2.1 AA (standaard)
wcag2.2 WCAG 2.2 AA
wcag2aaa WCAG 2.0 AAA
wcag2.1aaa WCAG 2.1 AAA
wcag2.2aaa WCAG 2.2 AAA
508 Sectie 508
ttv5 Trusted Tester v5
en301549 EN 301 549
rgaav4 RGAA v4

Voor informatie over het opnemen of uitsluiten van elementen, zie de axe-core API-documentatie over de Context-parameter.

# Analyze using the WCAG 2.1 AA ruleset (default) — all three forms are equivalent
analyze
analyze the page
analyze page

# Analyze using the Section 508 ruleset
analyze page with ruleset "508"

# Analyze with a custom title (useful when analyzing a page multiple times)
analyze the page with title "after login"

# Analyze only a specific element
analyze only element "#main-content"

# Analyze only specific elements
analyze only element "#idOfElement" and element ".classToAnalyze"

# Analyze everything except images that are immediate children of paragraphs
analyze the page excluding element "p > img"

# Analyze everything except elements inside a frame with a specific class
analyze the page excluding element [ ".classOfFrameToExclude", "#idOfElement" ]

# Save results to a specific directory
analyze the page and save in "./homepage-team/"

# Save a copy to an additional directory while also saving to the default location
analyze the page and save a copy in "./homepage-team/"

# Use the axe-core library's built-in default ruleset
analyze the page with the source default ruleset

Voorbeeld van het combineren van meerdere opties: Analyseer alleen afbeeldingen binnen elementen met de klasse third-party en formulieren die niet worden gevalideerd bij verzending, waarbij elementen met de klasse old-apiworden uitgesloten, gebruikmakend van de 508 regels, met een aangepaste titel en een aangepaste opslaglocatie.

analyze only element [ ".third-party", "img"] and element "form[novalidate]" excluding element ".old-api" with ruleset "508" with title "What is this testing" and save in "Results for Some test"

In JSON:

"analyze only element [\".third-party\", \"img\"] and element \"form[novalidate]\" excluding element \".old-api\" with ruleset \"508\" with title \"What is this testing\" and save in \"Results for Some test\""

change

De change actie wijzigt de waarde van een <input>, <textarea>, of <select> element via JavaScript. Gebruik change wanneer normale DOM-evenementen niet beschikbaar zijn.

# Change the value of an input
change the value of "input[name=song]" to "too many puppies"

click

De click actie klikt op het eerste element dat overeenkomt met de gegeven selector.

# Click a button by class selector
click element ".myButton"

# Click the body element
click "body"

dismiss

De dismiss actie sluit een popup of dialoogvenster door op de sluitknop te klikken. Geef een CSS-selector op voor de modale container en een andere voor de sluitknop. De actie faalt op een elegante manier als een van de elementen niet aanwezig is.

note

Deze actie sluit geen native alert() of confirm() dialoogvensters.

# Dismiss a modal using separate selectors for the container and close button
dismiss modal ".myModal" with close button ".myModal .close"

eval

De eval actie voert willekeurige JavaScript uit op de pagina. Gebruik het om de DOM te manipuleren of aangepaste acties uit te voeren.

# Change the page title
eval "document.title = 'hello world'"

# Scroll an element into view
eval "document.querySelector('.someElement').scrollIntoView()"

# Scroll to the bottom of the page
eval "window.scrollTo(0, document.body.scrollHeight)"

press

De press actie stuurt een toetsdruk naar een element (eventueel met modifier-toetsen). Voor ondersteunde toetsenamen, zie de Selenium-toetsdocumentatie.

# Press H on the body element
press "H" on "body"

# Press Shift+Tab on the navigation element
press "shift+tab" on element ".navigation"

# Press Shift+Control+7 on an element
press "shift+control+7" on element ".foo"

select

De select actie selecteert een <option> van een <select> element op basis van de zichtbare tekst (niet op basis van het value attribuut).

Gegeven deze HTML:

<select class="mySelect">
  <option></option>
  <option value="1">dog</option>
  <option value="2">cat</option>
  <option value="3">fish</option>
</select>
# Select by visible option text
select the "dog" option in ".mySelect"
select the "cat" option in element ".mySelect"

type

De type actie typt een string in een <input> of <textarea> element. Gebruik het om formulieren in te vullen en zoekvelden te populeren.

# Type into an email input
type "user@example.com" into element "input[type=email]"

# Type into a textarea
type "hello world" into "textarea.Message"

# Type with a delay between keystrokes to simulate human typing
type "sloth" into "input[type=search]" with a 150ms key delay

wait

De wait actie wacht ofwel op een element om een gespecificeerde status te bereiken, of pauzeert voor een gegeven duur.

Ondersteunde elementstatussen: visible, hidden, selected, enabled, disabled, found.

Voor het wachten op de toestand van een element, probeert de actie tot 3 keer standaard (in totaal 4 pogingen) voordat het mislukt. Om langer te wachten op een langzaam ladend element, voeg with <n> retries toe om het aantal pogingen te verhogen.

Voor slaapduur worden numerieke waarden geïnterpreteerd als milliseconden. Strings worden omgezet met behulp van het ms pakket, bijvoorbeeld: 1m = 60.000 ms, 1s = 1.000 ms.

# Wait for an element to appear
wait for element ".myElement" to be found

# Wait for an element to become hidden
wait for element ".myElement" to be hidden

# Allow more retries for a slow-loading element
wait for element ".myElement" to be found with 9 retries

# Sleep for 1 minute
wait for 1m

# Sleep for 1 second
wait for 1s

# Sleep for 30 milliseconds
wait for 30

Globale Acties

Globale acties worden op elke pagina in een project uitgevoerd als reactie op toestandsveranderingen, in plaats van procedureel zoals pagina-acties. Momenteel wordt slechts één globale actie ondersteund: dismiss modal.

  • Globale acties werken zowel in spec modus als in headless URI-modus.
  • Globale acties zijn niet procedureel: ze worden geactiveerd als reactie op pagina-evenementen, niet in een vaste volgorde.
  • De dismiss modal globale actie wacht tot een gespecificeerde modal verschijnt en sluit deze voordat de pagina-acties doorgaan.

Voeg globale acties toe aan een project na name/id en voor pageList:

projects:
  - id: demo
    name: CLI demo
    globalActions:
      - dismiss modal "#__next .survey" with close button ".survey button.close"
    pageList:
      - name: homepage
        url: https://dequelabs.github.io/aget-demo-site
      - name: popup
        url: https://dequelabs.github.io/aget-demo-site
        actions:
          - wait for element "#__next header nav" to be visible
          - click element "#__next header nav a[href*=popup]"
          - wait for element ".content button" to be found
          - analyze with title "before popup"
          - click element ".content button"
          - analyze with title "with popup"
          - dismiss modal ".ReactModal__Content" with close button ".ReactModal__Content .close"
          - analyze with title "after popup"
      - name: contact
        url: https://dequelabs.github.io/aget-demo-site/contact
        actions:
          - analyze with title "form disabled"
          - wait for element "#__next .toggle" to be found
          - click element ".toggle button"
          - wait for element "input[name=name]" to be enabled
          - analyze with title "form enabled"
          - type "stephen" into element "input[name=name]"
          - type "555-555-5555" into element "input[name=phone]"
          - type "stephen@deque.com" into element "input[name=email]"
          - type "hello world" into element "textarea[name=message]"
          - click element "button[type=submit]"
          - wait for element ".thanks" to be found
          - analyze with title "thanks message"

Screenshots Maken

Om een screenshot van elke pagina na analyse te maken, voeg een screenshot object toe aan een project in je specificatiebestand. Elke pagina produceert een PNG-bestand met de naam <page-id>-screenshot.png (elke / of \ in de pagina id wordt vervangen door _). Als een pagina geen idheeft, wordt er een afgeleid van zijn name door alle spaties te verwijderen.

Eigenschap Type Standaard Beschrijving
enabled boolean — Vereist. Stel in op true om screenshotvastlegging in te schakelen. Werkt met alle ondersteunde browsers.
fullPage boolean false Maakt een screenshot van de volledige scrollbare pagina met behulp van het Chrome DevTools Protocol. Vereist Chrome of Chromium; andere browsers vallen terug op een viewportscreenshot met een waarschuwing.
boundingBoxes boolean false Voegt coördinaten van het begrenzingsvak (x, y, width, en height) aan elk overtredingsknooppunt in de Axe-resultaten toe te voegen, waarbij wordt geregistreerd waar het element in de screenshot verschijnt.
dir string <output-dir>/<project-id>/ Directory waar PNG-bestanden van de screenshots worden opgeslagen.

Wanneer je axe spec uitvoert met --verbose, bevat elk resultaat ook een screenshotPath veld met het volledige pad naar het screenshotbestand van die pagina. 

projects:
  - name: My App
    id: my-app
    screenshot:
      enabled: true
      fullPage: true
      boundingBoxes: true
      dir: ./screenshots
    pageList:
      - name: Home
        url: https://example.com/

Batchverwerking met axe bulk-spec

Om meerdere specs-bestanden in één keer te verwerken, gebruik axe bulk-spec met een directory die specs-bestanden bevat. De CLI zoekt recursief in de directory en submappen naar specs-bestanden.

axe bulk-spec <spec-files-directory> <output-directory>

De <output-directory> is optioneel — als deze wordt weggelaten, worden de resultaten opgeslagen in de huidige werkdirectory.

Voortgangsupdates worden naar stdout geprint tijdens de uitvoering.

Resultaten worden geschreven naar de uitvoermap: één JSON-bestand per analyze actie, plus een logbestand met een lijst van eventueel mislukte specs-bestanden en de reden van falen.

Opties

De volgende opties zijn beschikbaar voor axe spec:

--axe-devhub-api-key <api-key>

Specificeert de Axe Developer Hub API-sleutel. Vereist (samen met --axe-devhub-project-id) om resultaten naar de Axe Developer Hub te verzenden. Zie Resultaten verzenden naar Axe Developer Hub.

--axe-devhub-project-id <project-id>

Specificeert het project-ID van de Axe Developer Hub. Vereist (samen met --axe-devhub-api-key) om resultaten naar de Axe Developer Hub te verzenden. Zie Resultaten verzenden naar Axe Developer Hub.

--axe-devhub-server-url <url>

Specificeert de URL van de Axe Developer Hub-server. Standaard is https://axe.deque.com. Equivalent aan de AXE_DEVHUB_SERVER_URL omgevingsvariabele. Zie Resultaten verzenden naar Axe Developer Hub.

-a, --axe-source <path>

Pad naar een alternatief axe.js bestand. De meeste gebruikers hebben deze optie niet nodig. Het is bedoeld voor geavanceerde toepassingen zoals testen tegen een specifieke of aangepaste versie van axe-core.

--chrome-options [options]

Geeft een door komma's gescheiden lijst van Chrome-opdrachtregelopties door aan ChromeDriver. Gebruik dit om browserfuncties in te schakelen of om beperkingen in specifieke omgevingen te omzeilen, bijvoorbeeld in gecontaineriseerde CI-omgevingen waar de sandbox moet worden uitgeschakeld.

axe spec workflow.yml --chrome-options="no-sandbox,disable-gpu"

-c, --custom <path>

Specificeert een aangepast regelsbestand, waarmee het standaardregelsbestand wordt overschreven.

--descendant-links

Verzamelt de links op elke pagina en voegt deze toe aan de resultaten. Vereist --verbose.

--dismiss-alerts

Sluit automatisch browser alert(), confirm(), en prompt() dialogen voordat u scant.

--enable-tracking <state>

Stelt het verzenden van gegevens naar de metrics-bibliotheek in.

--filter <type(s)>

Filtert resultaattypen uit de uitvoer: passes, violations, incomplete, inapplicable. Vereist --format csv.

-f, --format <type(s)>

Rapportformaat(en): html, junit, csv, universal, of een door komma's gescheiden combinatie. Standaard: html. Zie --universal-ruleset en --universal-best-practices voor opties die van toepassing zijn bij het gebruik van universal.

--no-analyze

Verwijdert de vereiste voor een analyze actie in de actielijst van elke pagina. Standaard moet elke pagina in een specificatiebestand ten minste één analyze actie bevatten; deze vlag schakelt die controle uit, wat nuttig is bij het uitvoeren van een workflow die alleen acties uitvoert zonder een toegankelijkheidsscan.

--no-exit

Dwingt de CLI om af te sluiten met code 0 zelfs wanneer er overtredingen worden gevonden. Standaard sluit axe spec af met code 1 als er overtredingen worden gedetecteerd. Gebruik dit wanneer u resultaten wilt verzamelen zonder een CI-build te laten mislukken.

--no-git-data

Sluit Git-branch- en commitinformatie uit bij het verzenden van resultaten naar Axe Developer Hub. Zie Resultaten verzenden naar Axe Developer Hub.

--no-html

Voorkomt dat de CLI een HTML-rapport genereert. Gebruik dit samen met --format om te bepalen welke rapportformaten worden geschreven, of wanneer u alleen JSON-resultaten wilt zonder een HTML-overzicht.

--no-reports

Voorkomt dat de CLI een rapportbestand genereert. Resultaten worden nog steeds verzameld en weergegeven in de terminal, maar er wordt niets naar de schijf geschreven. Handig voor snelle controles waarbij uitvoerbestanden niet nodig zijn.

--no-wait

Schakelt de automatische pauze tussen workflowacties uit. Standaard worden de pauzes geconfigureerd met --post-get-pause, --post-script-pause, en --post-analyze-pause toegepast tussen acties (zie Configureren); deze vlag omzeilt ze allemaal.

--page-name <name>

Voert alleen de pagina met de opgegeven naam uit van het spec-bestand pageList.

--page-source

Voegt de gescande HTML-bron toe aan resultaten. Vereist --verbose.

--page-title

Voegt de paginatitel toe aan resultaten. Vereist --verbose.

--remote-proxy <proxy-server>

Leidt verkeer om via de opgegeven externe proxyserver.

--resume-from <name>

Slaat alle pagina's over vóór de benoemde pagina in het spec-bestand pageList.

--scanned-url

Voegt de basis-URL en huidige scan-URL toe aan gedetailleerde resultaten. Alleen voor Chrome. Vereist --verbose.

--set-distinct-id <id>

Overschrijft de waarde van de unieke ID.

--set-legacy-mode

Schakelt de verouderde legacy-scanmodusin, die in versie 5.0 wordt verwijderd.

important

Dit is een laatste redmiddel. Er is gerapporteerd dat het mogelijk scans op pagina's kan voltooien die overschrijven window.open(), een niet-aangeraden methode.

--set-tracking-url <url>

Overschrijft de URL waar metrische gegevens heen worden gestuurd.

--silent-mode

Onderdrukt alle decoratieve tekst in de CLI-uitvoer. Resultaten worden alleen weergegeven wanneer --verbose ook actief is. Gebruik dit in scripts of CI-pijplijnen waar u schone uitvoer zonder voortgangsbanners of statusberichten wilt.

-t, --tags

Filtert het standaard regelsysteem op tag.

--universal-best-practices

Registreert bestPracticesEnabled=true in de metadata van de output in universeel formaat. Vereist --format universal.

--universal-ruleset <id>

Specificeert de ruleset-ID om te registreren in de metadata van de output in universeel formaat. Standaard is wcag2.1. Vereist --format universal. Zie de ruleset-tabel voor geldige waarden.

--user-agent

Stelt een aangepaste user-agentstring voor de browser in.

--validate

Valideert uw spec-bestand zonder het uit te voeren.

-v, --verbose

Bevat extra output: Axe-resultaten en metadata zoals toolnaam, versie en omgeving.

--wait-network-idle-new-connections [number]

Het aantal nieuwe netwerkverbindingen dat mag worden gemaakt voordat het netwerk als inactief wordt beschouwd. Zodra nieuwe verbindingen dalen tot of onder deze drempel gaat de CLI verder met de scan. Gebruik samen met --wait-network-idle-timeout om af te stemmen wanneer de CLI draait op pagina's met lopende achtergrondnetwerkactiviteit.

--wait-network-idle-open-connections [number]

Het aantal open netwerkverbindingen dat mag blijven voordat het netwerk als inactief wordt beschouwd. Zodra open verbindingen dalen tot of onder deze drempel gaat de CLI verder met de scan.

--wait-network-idle-polling-every [ms]

Het interval in milliseconden waarop de CLI controleert of het netwerk inactief is geworden. Verlaag deze waarde voor snellere detectie ten koste van een hoger CPU-gebruik.

--wait-network-idle-timeout [ms]

De maximale tijd in milliseconden om te wachten tot netwerkactiviteit zich heeft gestabiliseerd voordat de scan begint. Na het laden van de pagina controleert de CLI de actieve netwerkverbindingen en wacht tot het aantal verbindingen de ingestelde drempel bereikt. Als de timeout verstrijkt voordat het netwerk inactief wordt, gaat de CLI toch verder met de scan.

Voor aanvullende configuratieopties, zie Configureren.

Is this page helpful?

Help us improve this page

Still need help?