Analyser des pages en utilisant des fichiers de spécifications

Un fichier de spécifications est un fichier JSON ou YAML qui définit une liste de pages web et les actions du navigateur à exécuter sur chaque page avant de les analyser pour détecter les problèmes d'accessibilité. Utilisez axe spec pour exécuter un fichier de spécifications unique, ou axe bulk-spec pour traiter un répertoire de fichiers de spécifications.

• La commande axe spec
• Structure du fichier de spécifications
• Actions
• Sélecteurs
• Actions globales
• Traitement par lot avec axe bulk-spec
• Options

La commande axe spec

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

Là où les résultats JSON sont sauvegardés. Si omis, les résultats sont sauvegardés dans le répertoire de travail actuel. <output-dir>

Exemple d'utilisation :

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

Structure du fichier de spécifications

Un fichier de spécifications définit un ou plusieurs projets, chacun avec une liste de pages à analyser et des actions facultatives à effectuer sur chaque page.

Exemple YAML

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/

Projet

Page

Format JSON/YAML

Les fichiers de spécification peuvent être écrits en YAML ou JSON. Le tableau suivant montre les mêmes valeurs dans chaque format. Notez que dans JSON, les chaînes d'actions contenant des guillemets doivent les échapper avec un antislash.

Actions

Les actions sont des chaînes dans le actions (ou globalActions) tableau d'un fichier de spécification. Elles exécutent des tâches comme cliquer sur des boutons, remplir des formulaires, fermer des boîtes de dialogue, attendre des états de page et réaliser des analyses d'accessibilité. Les actions s'exécutent dans l'ordre indiqué.

Il existe deux types d'actions :

• Actions de page s'exécutent en séquence sur une page spécifique. L'action analyze doit être appelée au moins une fois par page.
• Actions globales s'exécutent sur chaque page du projet en réponse aux changements d'état. Voir Actions globales.

Exemple d'Action Complète

L'exemple suivant se connecte à Deque University et analyse le tableau de bord :

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

Sélecteurs

De nombreuses actions prennent un argument sélecteur qui identifie un élément sur la page. Un sélecteur peut être un sélecteur CSS ou XPath, spécifié comme une seule chaîne ou une liste de chaînes.

Pour cibler des éléments à l'intérieur des iframes, vous devez utiliser une liste. Tous les sélecteurs dans la liste sauf le dernier identifient des <iframe> éléments successifs à parcourir et doivent être des sélecteurs CSS. Le dernier sélecteur de la liste identifie l'élément cible et peut être CSS ou XPath. Chaque sélecteur dans la liste est évalué par rapport au contexte de document établi par l'entrée précédente : le premier sélecteur est relatif au document racine, et chaque sélecteur d'iframe suivant est relatif au document à l'intérieur de l'iframe précédent.

Utiliser une seule chaîne (pas une liste) ne peut pas naviguer dans les iframes.

Exemple de Sélecteur d'Iframe

Considérez cette structure HTML :

<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>

Pour cliquer sur l'entrée de numéro de carte, utilisez une liste de sélecteurs. Chaque sélecteur CSS est évalué dans le contexte de document établi par l'entrée précédente :

# "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" ]

Pour utiliser XPath pour l'élément cible final (les sélecteurs d'iframe doivent toujours être CSS) :

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

En JSON :

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

Actions de Page

Le CLI prend en charge neuf actions de page :

1. analyze: réaliser une analyse d'accessibilité
2. change: changer la valeur d'un <input>, <textarea>, ou <select> via JavaScript
3. click: cliquer sur un élément
4. dismiss: fermer un popup ou une boîte modale
5. eval: évaluer du JavaScript arbitraire
6. press: appuyer sur une touche (avec ou sans modificateurs)
7. select: sélectionner une option dans un <select>
8. type: taper dans un <input>
9. wait: attendre un état spécifique ou temporiser

analyze

L'action analyze exécute une analyse d'accessibilité. Elle doit être appelée au moins une fois par page. Vous pouvez l'appeler plusieurs fois pour analyser une page à différents points d'un flux de travail (utilisez la variante with title pour distinguer les résultats).

Le paramètre optionnel ruleset spécifie quel jeu de règles utiliser. Le défaut est WCAG 2.1 AA. Règles disponibles :

Pour obtenir des informations sur l'inclusion ou l'exclusion d'éléments, consultez la documentation API axe-core sur le paramètre Contexte.

# 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

Exemple combinant plusieurs options : Analyser uniquement les images dans les éléments avec la classe third-party et les formulaires qui ne sont pas validés lors de la soumission, en excluant les éléments avec la classe old-api, en utilisant le 508 jeu de règles, avec un titre personnalisé et un emplacement d'enregistrement personnalisé.

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"

En 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

L'action change change la valeur d'un <input>, <textarea>, ou <select> élément via JavaScript. Utilisez change lorsque les événements DOM normaux ne sont pas disponibles.

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

click

L'action click clique sur le premier élément qui correspond au sélecteur donné.

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

# Click the body element
click "body"

dismiss

L'action dismiss ferme une fenêtre contextuelle ou un modal en cliquant sur son bouton de fermeture. Fournissez un sélecteur CSS pour le conteneur modal et un autre pour le bouton de fermeture. L'action échoue gracieusement si l'un ou l'autre des éléments n'est pas présent.

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

eval

L'action eval exécute du JavaScript arbitraire sur la page. Utilisez-la pour manipuler le DOM ou effectuer des actions personnalisées.

# 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

L'action press envoie une pression de touche à un élément (éventuellement avec des touches de modification). Pour les noms de touches pris en charge, consultez la documentation des touches Selenium.

# 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

L'action select sélectionne un <option> d'un <select> élément par son texte visible (pas par son value attribut).

Étant donné ce 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

L'action type action saisit une chaîne dans un <input> ou un <textarea> élément. Utilisez-la pour remplir des formulaires et renseigner des champs de recherche.

# 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

L' wait action attend qu'un élément atteigne un état spécifié, ou se met en pause pendant une durée déterminée.

États d'élément pris en charge : visible, hidden, selected, enabled, disabled, found.

Pour la durée de pause, les valeurs numériques sont interprétées comme des millisecondes. Les chaînes sont converties à l'aide du package ms — par exemple, 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

# Sleep for 1 minute
wait for 1m

# Sleep for 1 second
wait for 1s

# Sleep for 30 milliseconds
wait for 30

Actions globales

Les actions globales s'exécutent sur chaque page d'un projet en réponse aux changements d'état, plutôt que de s'exécuter de manière procédurale comme les actions de page. Une seule action globale est actuellement prise en charge : dismiss modal.

• Les actions globales fonctionnent en mode spec et en mode URI sans tête.
• Les actions globales ne sont pas procédurales — elles se déclenchent en réponse aux événements de page, et non dans une séquence fixe.
• L' dismiss modal action globale attend qu'une fenêtre modale spécifiée apparaisse et la ferme avant que les actions de page ne continuent.

Ajoutez des actions globales à un projet après name/id et avant 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"

Traitement par lots avec axe bulk-spec

Pour traiter plusieurs fichiers de spécification en une seule exécution, utilisez axe bulk-spec avec un répertoire contenant des fichiers de spécification. L'interface CLI recherche récursivement le répertoire et ses sous-répertoires pour trouver des fichiers de spécification.

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

Le <output-directory> est optionnel — s'il est omis, les résultats sont enregistrés dans le répertoire de travail actuel.

Les mises à jour de progression sont imprimées sur stdout pendant l'exécution.

Les résultats sont écrits dans le répertoire de sortie : un fichier JSON par analyze action, plus un fichier journal listant tous les fichiers de spécification qui ont échoué et la raison de l'échec.

Options

Les options suivantes sont disponibles pour axe spec:

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

Spécifie la clé API de l'Axe Developer Hub. Requis (avec --axe-devhub-project-id) pour envoyer les résultats à l'Axe Developer Hub. Voir Envoyer des résultats à l'Axe Developer Hub.

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

Spécifie l'ID de projet de l'Axe Developer Hub. Requis (avec --axe-devhub-api-key) pour envoyer les résultats à l'Axe Developer Hub. Voir Envoyer des résultats à l'Axe Developer Hub.

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

Spécifie l'URL du serveur Axe Developer Hub. Par défaut sur https://axe.deque.com. Équivalent à la variable d'environnement AXE_DEVHUB_SERVER_URL . Voir Envoyer les résultats à Axe Developer Hub.

-c, --custom <path>

Spécifie un fichier de règles personnalisé, remplaçant le jeu de règles par défaut.

--descendant-links

Collecte les liens de chaque page et les ajoute aux résultats. Nécessite --verbose.

--dismiss-alerts

Ferme automatiquement les alert(), confirm(), et prompt() boîtes de dialogue du navigateur avant l'analyse.

--enable-tracking <state>

Active l'envoi de données à la bibliothèque de métriques.

--filter <type(s)>

Filtre les types de résultats de la sortie : passes, violations, incomplete, inapplicable. Nécessite --format csv.

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

Format(s) de rapport : html, junit, csv, ou une combinaison séparée par des virgules. Par défaut : html.

--no-git-data

Exclut les informations de branche et de commit Git lors de l'envoi des résultats à Axe Developer Hub. Voir Envoyer les résultats à Axe Developer Hub.

--page-name <name>

Exécute uniquement la page portant le nom spécifié à partir du fichier de spécifications pageList.

--page-source

Ajoute le code source HTML analysé aux résultats. Nécessite --verbose.

--page-title

Ajoute le titre de la page aux résultats. Nécessite --verbose.

--remote-proxy <proxy-server>

Routage du trafic via le serveur proxy distant spécifié.

--resume-from <name>

Ignore toutes les pages avant la page nommée dans le fichier de spécifications pageList.

--scanned-url

Ajoute l'URL de base et l'URL d'analyse actuelle aux résultats détaillés. Chrome uniquement. Nécessite --verbose.

--set-distinct-id <id>

Remplace la valeur de l'ID distinct.

--set-legacy-mode

Active le mode d'analyse déprécié legacy, qui sera supprimé dans la version 5.0.

--set-tracking-url <url>

Remplace l'URL où les données des métriques sont envoyées.

-t, --tags

Filtre le jeu de règles standard par tag.

--user-agent

Définit une chaîne d'agent utilisateur personnalisée pour le navigateur.

--validate

Valide votre fichier de spécifications sans l'exécuter.

-v, --verbose

Inclut une sortie supplémentaire : Résultats Axe et métadonnées telles que le nom de l'outil, la version et l'environnement.

Pour des options de configuration supplémentaires, voir Configurer.