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 spec est un fichier JSON ou YAML qui définit une liste de pages web et les actions du navigateur à effectuer sur chaque page avant d'analyser pour des problèmes d'accessibilité. Utilisez axe spec pour exécuter un fichier spec unique, ou axe bulk-spec pour traiter un répertoire de fichiers spec.

Le axe spec 

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

Le <output-dir>

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 enquête pop-up. Voir Actions globales.
screenshot objet Optionnel. Capture une capture d’écran de chaque page après 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 à effectuer 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 dans le actions (ou globalActions) tableau d'un fichier de spécifications. Ils effectuent des tâches telles que cliquer sur des boutons, remplir des formulaires, fermer des boîtes de dialogue, attendre les états de page et effectuer des analyses d'accessibilité. Les actions s'exécutent dans l'ordre indiqué.

Il existe deux types d'actions :

  • Actions de page exécutées en séquence sur une page spécifique. L' analyze action doit être appelée au moins une fois par page.
  • Actions globales exécutées 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 successivement les <iframe> éléments pour naviguer à l'intérieur, 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 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 d'iframe suivant est relatif au document à l'intérieur de l'iframe précédente.

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: effectuer une analyse d'accessibilité
  2. change: modifier la valeur d'un <input>, <textarea>, ou <select> via JavaScript
  3. click: cliquer sur un élément
  4. dismiss: fermer une popup ou un modal
  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 faire une pause

analyze

Le analyze action 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 ensemble de règles utiliser. Le défaut est WCAG 2.1 AA. Ensembles 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 obtenir des informations sur l'inclusion ou l'exclusion d'éléments, voir la 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 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 de sauvegarde 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

Le change action 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

Le click action 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

Le dismiss action ferme un popup ou une modal en cliquant sur son bouton de fermeture. Fournissez un sélecteur CSS pour le conteneur de la modal et un autre pour le bouton de fermeture. L'action échoue sans problème si l'un des éléments n'est pas présent.

note

Cette action ne renvoie pas les alert() ou confirm() dialogues natifs.

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

eval

Le eval action 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

Le press action envoie une pression de touche à un élément (éventuellement avec des touches de modification). Pour les noms de touches pris en charge, voir 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

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

É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

Le type action tape une chaîne de caractères dans un <input> ou <textarea> élément. Utilisez-la pour remplir des formulaires et remplir 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

Le wait action attend soit qu'un élément atteigne un état spécifié, soit qu'il dorme pendant une durée donnée.

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

Pour la durée du sommeil, les valeurs numériques sont interprétées comme des millisecondes. Les chaînes de caractères sont converties à l'aide du paquet 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 manière procédurale comme les actions de page. Seule une action globale est actuellement prise en charge : dismiss modal.

  • Les actions globales fonctionnent à la fois en mode spec et en mode URI sans interface.
  • Les actions globales ne sont pas procédurales — elles se déclenchent en réponse à des événements de page, et non dans une séquence fixe.
  • Le 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 analyse, ajoutez un screenshot objet à un projet dans votre fichier de spécification. Chaque page produit un fichier PNG nommé <page-id>-screenshot.png (tout / ou \ dans la page id est remplacé par _). Si une page n'a pas de id, un est dérivé de son name en supprimant tous les espaces.

Propriété Type Défaut Description
enabled booléen — Requis. Définir 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 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 screenshotPath champ 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 exécution, utilisez axe bulk-spec avec un répertoire contenant des fichiers de spécifications. L'interface de ligne de commande recherche de manière récursive le répertoire et ses sous-répertoires pour trouver les 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.

Des mises à jour des progrès 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 , ainsi qu'un fichier journal listant tous les fichiers de spécifications échoués 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 à des cas d'utilisation avancés comme les tests avec une version spécifique ou modifié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

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

--dismiss-alerts

Ferme automatiquement le navigateur alert(), confirm(), et prompt() des dialogues 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-analyze

Supprime l'exigence d'une analyze action dans la liste des actions de chaque page. Par défaut, chaque page d'un fichier de spécification doit inclure au moins une analyze action ; ce drapeau désactive cette vérification, ce qui est utile lors de l'exécution d'un flux de travail qui ne réalise que des actions sans lancer de scan 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 les 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 cela avec --format pour contrôler quels formats de rapport sont écrits, ou lorsque vous ne souhaitez que 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 du flux de travail. 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é à partir du pageList.

--page-source

Ajoute la source HTML scannée 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 du pageList.

--scanned-url

Ajoute l'URL de base et l'URL du scan actuel 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 de scan obsolète legacy, qui sera supprimé dans la version 5.0.

important

C'est une option de dernier recours. Il a été signalé qu'elle permettait de terminer les analyses sur des pages qui remplacent 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 le texte décoratif de la sortie du CLI. Les résultats ne sont affichés que lorsque --verbose est également actif. Utilisez cela dans des scripts ou des pipelines CI où vous souhaitez une sortie claire sans bannières de progression ou messages de statut.

-t, --tags

Filtre le jeu de règles standard par balise.

--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 ne soit considéré comme inactif. Une fois que les nouvelles connexions tombent à ce seuil ou en dessous, le CLI procède à l'analyse. Utilisez cela avec --wait-network-idle-timeout pour ajuster lorsque le CLI s'exécute sur des pages avec une activité réseau en arrière-plan.

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