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 spec-bestand is een JSON- of YAML-bestand dat een lijst van webpagina's en browseracties definieert die op elke pagina moeten worden uitgevoerd voordat er op toegankelijkheidsproblemen wordt geanalyseerd. Gebruik axe spec om een enkel spec-bestand uit te voeren, of axe bulk-spec om een map met spec-bestanden te verwerken.

De axe spec opdracht

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

De <output-dir> is waar JSON-resultaten worden opgeslagen. Indien 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 statuswijzigingen op elke pagina in het project, zoals het sluiten van een cookiebanner of enquête-pop-up. Zie Globale Acties.
screenshot object Optioneel. Maakt een screenshot van elke pagina na de analyse. Zie Screenshots Maken.
pageList array Lijst van pagina's die geanalyseerd moeten worden. Zie Pagina.

Pagina

Eigenschap Type Beschrijving
name string Weergavenaam van de pagina.
url string URL van de pagina.
actions array Optioneel. Acties om op de pagina uit te voeren vóór 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 spec-bestand. Ze voeren taken uit zoals het klikken op knoppen, invullen van formulieren, sluiten van dialogen, wachten op paginastatussen, en uitvoeren van toegankelijkheidsanalyses. Acties worden uitgevoerd in de volgorde waarin ze vermeld staan.

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 op elke pagina in het project uitgevoerd 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, u moet een lijst gebruiken. Alle selectors in de lijst behalve de laatste identificeren opeenvolgende <iframe>-elementen om naar binnen te navigeren, en moeten CSS-selectors zijn. De laatste selector in de lijst identificeert het doelelement en kan een CSS of XPath zijn. Elke selector in de lijst wordt geëvalueerd ten opzichte van de documentcontext die is vastgesteld door de vorige bijdrage: de eerste selector is ten opzichte van het hoofddocument, en elke volgende iframe-selector is ten opzichte van het document binnen het voorgaande 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: wijzig de waarde van een <input>, <textarea>, of <select> via JavaScript
  3. click: klik op een element
  4. dismiss: sluit een pop-up of modal
  5. eval: evalueer willekeurige JavaScript
  6. press: druk op een toets (met of zonder modifier-toetsen)
  7. select: selecteer een optie in een <select>
  8. type: typ in een <input>
  9. wait: wacht op een specifieke toestand of pauzeer

analyze

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

De optionele ruleset-parameter specificeert welke regels moeten worden gebruikt. De standaard is WCAG 2.1 AA. Beschikbare regels:

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 inzending, met uitzondering van elementen met de klasse old-api, 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-gebeurtenissen 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 pop-up of modal door op de sluitknop te klikken. Geef een CSS-selector op voor de modal container en een andere voor de sluitknop. De actie faalt zonder problemen als een van beide elementen niet aanwezig is.

note

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

# 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 toetsaanslag naar een element (optioneel met modifiertoetsen). Voor ondersteunde toetsnamen, 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 zijn zichtbare tekst (niet zijn 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 bevolken.

# 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 tot een element een bepaalde staat bereikt, of pauzeert voor een bepaalde duur.

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

Voor het wachten op elementtoestanden probeert de actie standaard 3 keer keer (in totaal 4 pogingen) opnieuw voordat deze faalt. 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 statuswijzigingen, in plaats van procedureel te worden uitgevoerd zoals pagina-acties. Er wordt momenteel 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 pagina-acties doorgaan.

Voeg globale acties toe aan een project na name/id en vóór 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, voegt u een screenshot-object toe aan een project in uw spec-bestand. Elke pagina produceert een PNG-bestand genaamd <page-id>-screenshot.png (elke / of \ in de pagina id wordt vervangen door _). Als een pagina geen id heeft, wordt er één afgeleid van zijn name door alle spaties te verwijderen.

Eigenschap Type Standaard Beschrijving
enabled boolean — Vereist. Stel in op true om schermopname mogelijk te maken. 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 (x, y, width en height) van het begrenzingsvak toe aan elk overtredingsknooppunt in de Axe-resultaten, 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 u axe spec uitvoert met --verbose, bevat elk resultaat ook een screenshotPath-veld met het volledige pad naar het screenshot-bestand 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 spec-bestanden in één keer te verwerken, gebruik axe bulk-spec met een map die spec-bestanden bevat. De CLI doorzoekt de map en zijn submappen recursief naar spec-bestanden.

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

De <output-directory> is optioneel — indien weggelaten, worden de resultaten opgeslagen in de huidige werkmap.

Voortgangsupdates worden tijdens het uitvoeren naar stdout afgedrukt.

Resultaten worden geschreven naar de uitvoermap: één JSON-bestand per analyze-actie, plus een logbestand dat eventuele mislukte spec-bestanden en de reden voor de mislukking opsomt.

Opties

De volgende opties zijn beschikbaar voor axe spec:

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

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

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

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

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

Geeft de URL van de Axe Developer Hub-server op. 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 gebruiksscenario's 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 ze toe aan de resultaten. Vereist --verbose.

--dismiss-alerts

Sluit automatisch browser alert(), confirm(), en prompt() dialogen voordat er gescand wordt.

--enable-tracking <state>

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

--filter <type(s)>

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

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

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

--no-analyze

Verwijdert de vereiste voor een analyze actie in de actielijst van elke pagina. Standaard moet elke pagina in een spec-bestand 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 je resultaten wilt verzamelen zonder een CI-build te laten mislukken.

--no-git-data

Sluit Git-branch- en commit-informatie 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 je alleen JSON-resultaten wilt zonder een HTML-samenvatting.

--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 zijn de pauzes geconfigureerd met --post-get-pause, --post-script-pause, en --post-analyze-pause van toepassing tussen acties (zie Configureren); deze vlag omzeilt ze allemaal.

--page-name <name>

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

--page-source

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

--page-title

Voegt de paginatitel toe aan de 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 genoemde pagina in de pageList van het spec-bestand.

--scanned-url

Voegt de basis-URL en de 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-scanmodus in, die wordt verwijderd in v5.0.

important

Dit is een laatste redmiddel. Er is gerapporteerd dat hierdoor scans kunnen worden voltooid op pagina's die window.open() overschrijven, een afgeraden praktijk.

--set-tracking-url <url>

Overschrijft de URL waar metrische gegevens heen worden gestuurd.

--silent-mode

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

-t, --tags

Filtert het standaard regelsysteem op tag.

--universal-best-practices

Legt bestPracticesEnabled=true vast in de metadata van de universele formaatuitvoer. Vereist --format universal.

--universal-ruleset <id>

Geeft de regelsset-ID op om vast te leggen in de metadata van de universele formaatuitvoer. 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 opgezet voordat het netwerk als inactief wordt beschouwd. Zodra nieuwe verbindingen dalen tot of onder deze drempel, gaat de CLI door met de scan. Gebruik samen met --wait-network-idle-timeout om af te stemmen wanneer de CLI op pagina's wordt uitgevoerd met voortdurende 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?