Analyser des pages à l'aide de fichiers spec

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

Comment utiliser les sous-commandes spec et bulk-spec pour analyser les pages à l'aide de fichiers spec

Not for use with personal data

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 d'analyser les problèmes d'accessibilité. Utilisez axe spec pour exécuter un seul fichier de spécifications, ou axe bulk-spec pour traiter un répertoire de fichiers de spécifications.

La commande axe spec

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

<output-dir> est l'endroit où les résultats JSON sont enregistrés. S'il est omis, les résultats sont enregistrés dans le répertoire de travail actuel.

Utilisation d'exemple :

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

Structure du fichier spec

Un fichier spec définit un ou plusieurs projets, chacun avec une liste de pages à analyser et des actions optionnelles à 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

Propriété Type Description
name chaîne Nom d'affichage unique du projet.
id chaîne Identifiant unique du projet.
metadata objet Optionnel. Métadonnées arbitraires pour votre cas d'utilisation (par exemple, nom du produit, environnement).
globalActions tableau Optionnel. Actions qui répondent aux changements d'état sur chaque page du projet, par exemple, fermer une bannière de cookies ou une fenêtre contextuelle d'enquête. Voir Actions globales.
screenshot objet Optionnel. Capture une capture d'écran de chaque page après l'analyse. Voir Capture de captures d'écran.
pageList tableau Liste des pages à analyser. Voir Page.

Page

Propriété Type Description
name chaîne Nom d'affichage de la page.
url chaîne URL de la page.
actions tableau Optionnel. Actions à exécuter sur la page avant ou après l'analyse. Voir Actions.

Format JSON/YAML

Les fichiers spec 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'action contenant des guillemets doivent les échapper avec un antislash.

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

Actions

Les actions sont des chaînes de caractères dans le tableau actions (ou globalActions) d'un fichier de spécifications. Elles effectuent 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 :

  • Les 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.
  • Les 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 de la liste, sauf le dernier, identifient successivement les éléments <iframe> dans lesquels naviguer, et doivent être des sélecteurs CSS. Le dernier sélecteur de la liste identifie l'élément cible et peut être un sélecteur CSS ou XPath. Chaque sélecteur de la liste est évalué par rapport au contexte du document établi par l'entrée précédente : le premier sélecteur est relatif au document racine, et chaque sélecteur iframe suivant est relatif au document à l'intérieur du cadre précédent.

Utiliser une seule chaîne (pas une liste) ne permet pas de naviguer à l'intérieur des iframes.

Exemple de sélecteur d'iframe

Considérons 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 le champ de saisie de numéro de carte, utilisez une liste de sélecteurs. Chaque sélecteur CSS est évalué dans le contexte du 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(e) <input>, <textarea> ou <select> via JavaScript
  3. click : cliquer sur un élément
  4. dismiss : fermer une fenêtre contextuelle ou modale
  5. eval : exécuter du JavaScript arbitraire
  6. press : appuyer sur une touche (avec ou sans modificateurs)
  7. select : sélectionner une option dans un(e) <select>
  8. type : taper dans un(e) <input>
  9. wait : attendre un état spécifique ou faire une pause

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 moments 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. Jeux de règles disponibles :

ID de l'ensemble de règles Norme
wcag2 WCAG 2.0 AA
wcag2.1 WCAG 2.1 AA (par défaut)
wcag2.2 WCAG 2.2 AA
wcag2aaa WCAG 2.0 AAA
wcag2.1aaa WCAG 2.1 AAA
wcag2.2aaa WCAG 2.2 AAA
508 Section 508
ttv5 Trusted Tester v5
en301549 EN 301 549
rgaav4 RGAA v4

Pour des informations sur l'inclusion ou l'exclusion d'éléments, voir documentation de l'API axe-core sur le paramètre Context.

# 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 à l'intérieur des é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 jeu de règles 508, 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 élément <input>, <textarea> ou <select> 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 modale 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 des éléments est manquant.

note

Cette action ne ferme pas les boîtes de dialogue natives alert() ou confirm().

# 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 réaliser 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 modificateurs). Pour les noms de touches pris en charge, voir le 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 une <option> d'un élément <select> par son texte visible (pas son attribut value).

Étant donné cet 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 tape une chaîne de caractères dans un élément <input> ou <textarea>. Utilisez-la pour remplir des formulaires et 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'action wait attend qu'un élément atteigne un état spécifié, ou fait une pause pendant une durée donnée.

États des éléments pris en charge : visible, hidden, selected, enabled, disabled, found.

Pour les attentes d'état d'élément, l'action réessaie jusqu'à 3 fois par défaut (4 tentatives au total) avant d'échouer. Pour attendre plus longtemps un élément qui charge lentement, ajoutez with <n> retries pour augmenter le nombre de tentatives.

Pour la durée des pauses, les valeurs numériques sont interprétées en millisecondes. Les chaînes sont converties en utilisant le 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

# 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

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 à la fois 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 la page, et non dans une séquence fixe.
  • L'action globale dismiss modal 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"

Capture de captures d'écran

Pour capturer une capture d'écran de chaque page après l'analyse, ajoutez un objet screenshot à un projet dans votre fichier de spécifications. Chaque page produit un fichier PNG nommé <page-id>-screenshot.png (toute / ou \ dans id de la page est remplacée par _). Si une page n'a pas de id, une est dérivée de son name en supprimant tous les espaces.

Propriété Type Défaut Description
enabled booléen — Obligatoire. Réglez sur true pour activer la capture d'écran. Fonctionne avec tous les navigateurs pris en charge.
fullPage booléen false Capture la page complète défilable en utilisant le protocole Chrome DevTools. Nécessite Chrome ou Chromium ; les autres navigateurs reviennent à une capture d’écran du viewport avec un avertissement.
boundingBoxes booléen false Ajoute les coordonnées de la boîte englobante (x, y, width et height) à chaque nœud de violation dans les résultats d'Axe, enregistrant où l'élément apparaît dans la capture d'écran.
dir chaîne <output-dir>/<project-id>/ Répertoire où les fichiers PNG des captures d’écran sont écrits.

Lorsque vous exécutez axe spec avec --verbose, chaque résultat inclut également un champ screenshotPath avec le chemin complet vers le fichier de capture d'écran de cette page.

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

Traitement par lot avec axe bulk-spec

Pour traiter plusieurs fichiers de spécifications en une seule fois, utilisez axe bulk-spec avec un répertoire contenant des fichiers de spécifications. L'interface de ligne de commande recherche récursivement dans le répertoire et ses sous-répertoires des fichiers de spécifications.

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 action analyze, plus un fichier journal répertoriant les fichiers de spécifications 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 du Axe Developer Hub. Requis (avec --axe-devhub-project-id) pour envoyer les résultats à Axe Developer Hub. Voir Envoyer les résultats à Axe Developer Hub.

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

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

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

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

-a, --axe-source <path>

Chemin vers un fichier alternatif axe.js. La plupart des utilisateurs n'ont pas besoin de cette option. Elle est destinée aux cas d'utilisation avancés comme les tests contre une version spécifique ou corrigée de axe-core.

--chrome-options [options]

Passe une liste de commutateurs en ligne de commande de Chrome séparés par des virgules à ChromeDriver. Utilisez cela pour activer des fonctionnalités du navigateur ou contourner des restrictions dans des environnements spécifiques, par exemple dans des environnements CI conteneurisés où le sandbox doit être désactivé.

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

-c, --custom <path>

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

--descendant-links

Récupère les liens de chaque page et les ajoute aux résultats. Nécessite --verbose.

--dismiss-alerts

Ferme automatiquement les dialogues de navigateur alert(), confirm() et prompt() 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, universal ou une combinaison séparée par des virgules. Par défaut : html. Voir --universal-ruleset et --universal-best-practices pour les options applicables lors de l'utilisation de universal.

--no-analyze

Supprime l'exigence d'une action analyze dans la liste d'actions de chaque page. Par défaut, chaque page dans un fichier de spécifications doit inclure au moins une action analyze ; ce drapeau désactive cette vérification, ce qui est utile lors de l'exécution d'un workflow qui effectue uniquement des actions sans exécuter une analyse d'accessibilité.

--no-exit

Force le CLI à quitter avec le code 0 même lorsque des violations sont trouvées. Par défaut, axe spec quitte avec le code 1 si des violations sont détectées. Utilisez cela lorsque vous souhaitez collecter des résultats sans échouer à une construction CI.

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

--no-html

Empêche le CLI de générer un rapport HTML. Utilisez ceci avec --format pour contrôler les formats de rapport écrits, ou lorsque vous souhaitez uniquement des résultats JSON sans un résumé HTML.

--no-reports

Empêche le CLI de générer tout fichier de rapport. Les résultats sont toujours collectés et affichés dans le terminal, mais rien n'est écrit sur le disque. Utile pour des vérifications rapides où les fichiers de sortie ne sont pas nécessaires.

--no-wait

Désactive la pause automatique entre les actions de workflow. Par défaut, les pauses configurées avec --post-get-pause, --post-script-pause et --post-analyze-pause s'appliquent entre les actions (voir Configurer) ; ce drapeau les contourne toutes.

--page-name <name>

Exécute uniquement la page avec le nom spécifié dans le pageList du fichier de spécifications.

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

Route le trafic via le serveur proxy distant spécifié.

--resume-from <name>

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

--scanned-url

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

--set-distinct-id <id>

Remplace la valeur de l'ID distinct.

--set-legacy-mode

Active le legacy obsolète, qui sera supprimé dans la version v5.0.

important

Ceci est une option de dernier recours. Il a été signalé qu'il permet de compléter les analyses sur des pages qui surchargent window.open(), une pratique déconseillée.

--set-tracking-url <url>

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

--silent-mode

Supprime tout texte décoratif de la sortie CLI. Les résultats ne sont affichés que lorsque --verbose est également actif. Utilisez ceci dans les scripts ou les pipelines CI où vous souhaitez une sortie propre sans bannières de progression ou messages de statut.

-t, --tags

Filtre le jeu de règles standard par balise.

--universal-best-practices

Enregistre bestPracticesEnabled=true dans les métadonnées de la sortie au format universel. Nécessite --format universal.

--universal-ruleset <id>

Spécifie l'ID du jeu de règles à enregistrer dans les métadonnées de la sortie au format universel. Par défaut, wcag2.1. Nécessite --format universal. Voir le tableau des jeux de règles pour les valeurs valides.

--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 des sorties supplémentaires : résultats Axe et métadonnées telles que le nom de l'outil, la version et l'environnement.

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

Le nombre de nouvelles connexions réseau pouvant être établies avant que le réseau soit considéré comme inactif. Une fois que les nouvelles connexions tombent à ou en dessous de ce seuil, le CLI procède à l'analyse. Utilisez ceci avec --wait-network-idle-timeout pour ajuster le moment où le CLI s'exécute sur les pages avec une activité réseau en arrière-plan en cours.

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

Le nombre de connexions réseau ouvertes pouvant rester avant que le réseau ne soit considéré comme inactif. Une fois que les connexions ouvertes tombent à ce seuil ou en dessous, le CLI procède à l'analyse.

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

L'intervalle en millisecondes auquel le CLI vérifie si le réseau est devenu inactif. Réduisez cette valeur pour une détection plus rapide au prix d'une utilisation accrue du CPU.

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

Le temps maximum en millisecondes à attendre pour que l'activité réseau se stabilise avant de commencer l'analyse. Après le chargement de la page, le CLI surveille les connexions réseau actives et attend jusqu'à ce que le nombre de connexions atteigne le seuil configuré. Si le délai expire avant que le réseau ne devienne inactif, le CLI procède quand même à l'analyse.

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

Is this page helpful?

Help us improve this page

Still need help?