Analizar páginas usando archivos de especificaciones

Un archivo de especificaciones es un archivo JSON o YAML que define una lista de páginas web y las acciones del navegador que se deben realizar en cada página antes de analizar problemas de accesibilidad. Usa axe spec para ejecutar un único archivo de especificaciones, o axe bulk-spec para procesar un directorio de archivos de especificaciones.

• El comando axe spec
• Estructura del archivo de especificaciones
• Acciones
• Selectores
• Acciones globales
• Procesamiento por lotes con axe bulk-spec
• Opciones

El comando axe spec

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

es donde se guardan los resultados JSON. Si se omite, los resultados se guardan en el directorio de trabajo actual. <output-dir>

Ejemplo de uso:

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

Estructura del archivo de especificaciones

Un archivo de especificaciones define uno o más proyectos, cada uno con una lista de páginas a analizar y acciones opcionales a realizar en cada página.

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

Proyecto

Página

Formato JSON/YAML

Los archivos espec pueden escribirse en YAML o JSON. La siguiente tabla muestra los mismos valores en cada formato. Tenga en cuenta que en JSON, las cadenas de acción que contienen comillas dobles deben escaparlas con una barra invertida.

Acciones

Las acciones son cadenas en el array actions (o globalActions) de un archivo espec. Realizan tareas como hacer clic en botones, completar formularios, cerrar diálogos, esperar por estados de páginas y ejecutar análisis de accesibilidad. Las acciones se ejecutan en el orden listado.

Existen dos tipos de acciones:

• Acciones de página se ejecutan en secuencia en una página específica. La acción analyze debe llamarse al menos una vez por página.
• Acciones globales se ejecutan en cada página del proyecto en respuesta a cambios de estado. Consulte Acciones Globales.

Ejemplo de Acción Completa

El siguiente ejemplo inicia sesión en Deque University y analiza el panel de control:

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

Selectores

Muchas acciones toman un argumento de selector que identifica un elemento en la página. Un selector puede ser un selector CSS o un selector XPath, especificado como una sola cadena o una lista de cadenas.

Para dirigirse a elementos dentro de iframes, debe utilizar una lista. Todos los selectores en la lista, excepto el último, identifican sucesivamente elementos a los que navegar y deben ser selectores CSS. El último selector en la lista identifica el elemento objetivo y puede ser CSS o XPath. Cada selector en la lista se evalúa en relación con el contexto de documento establecido por la entrada anterior: el primer selector es relativo al documento raíz, y cada selector de iframe subsecuente es relativo al documento dentro del iframe anterior. <iframe> elementos a los que navegar dentro, y deben ser selectores CSS. El último selector en la lista identifica el elemento de destino y puede ser CSS o XPath. Cada selector en la lista se evalúa en relación con el contexto del documento establecido por la entrada previa: el primer selector es relativo al documento raíz, y cada selector subsecuente de iframe es relativo al documento dentro del iframe precedente.

Usar una sola cadena (no una lista) no puede navegar dentro de iframes.

Ejemplo de Selector de Iframe

Considere esta estructura 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>

Para hacer clic en la entrada del número de tarjeta, use una lista de selectores. Cada selector CSS se evalúa dentro del contexto del documento establecido por la entrada anterior:

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

Para usar XPath para el elemento de destino final (los selectores de iframe aún deben ser CSS):

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

En JSON:

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

Acciones de Página

El CLI admite nueve acciones de página:

1. analyze: ejecutar un análisis de accesibilidad
2. change: cambiar el valor de un <input>, <textarea>, o <select> mediante JavaScript
3. click: hacer clic en un elemento
4. dismiss: cerrar una ventana emergente o modal
5. eval: evaluar JavaScript arbitrario
6. press: presionar una tecla (con o sin modificadores)
7. select: seleccionar una opción en un <select>
8. type: escribir en un <input>
9. wait: esperar un estado específico o dormir

analyze

La acción analyze ejecuta un análisis de accesibilidad. Debe llamarse al menos una vez por página. Puede llamarse múltiples veces para analizar una página en diferentes puntos de un flujo de trabajo (use la variante para distinguir los resultados). with title para distinguir los resultados).

El parámetro opcional ruleset especifica qué conjunto de reglas usar. El predeterminado es WCAG 2.1 AA. Reglas disponibles:

Para obtener información sobre cómo incluir o excluir elementos, consulte la documentación de la API de axe-core sobre el parámetro Contexto.

# 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

Ejemplo combinando múltiples opciones: Analice solo las imágenes dentro de elementos con la clase third-party y formularios que no se validan al enviar, excluyendo elementos con la clase old-api, usando el conjunto de reglas 508 , con un título personalizado y una ubicación de guardado personalizada.

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

La change acción cambia el valor de un <input>, <textarea>, o <select> elemento a través de JavaScript. Use change cuando no están disponibles los eventos normales del DOM.

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

click

La click acción hace clic en el primer elemento que coincide con el selector dado.

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

# Click the body element
click "body"

dismiss

La dismiss acción cierra un popup o modal haciendo clic en su botón de cerrar. Proporcione un selector CSS para el contenedor modal y otro para el botón de cierre. La acción falla de manera controlada si alguno de los elementos no está presente.

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

eval

La eval acción ejecuta JavaScript arbitrario en la página. Úselo para manipular el DOM o realizar acciones personalizadas.

# 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

La press acción envía una pulsación de tecla a un elemento (opcionalmente con teclas modificadoras). Para los nombres de teclas compatibles, consulte la documentación de teclas de 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

La select acción selecciona un <option> de un <select> elemento por su texto visible (no por su value atributo).

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

La type la acción escribe una cadena en un <input> o un <textarea> elemento. Úselo para completar formularios y rellenar campos de búsqueda.

# 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

La wait acción espera que un elemento alcance un estado especificado o duerme durante un tiempo dado.

Estados del elemento soportados: visible, hidden, selected, enabled, disabled, found.

Para la duración del sueño, los valores numéricos se interpretan como milisegundos. Las cadenas se convierten usando el paquete ms — por ejemplo, 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

Acciones Globales

Las acciones globales se ejecutan en cada página de un proyecto en respuesta a cambios de estado, en lugar de ejecutarse de forma procedural como las acciones de página. Actualmente solo se admite una acción global: dismiss modal.

• Las acciones globales funcionan tanto en modo spec como en modo URI sin cabeza.
• Las acciones globales no son procedurales: se activan en respuesta a eventos de página, no en una secuencia fija.
• La dismiss modal acción global espera a que aparezca un modal especificado y lo descarta antes de que las acciones de página continúen.

Agregue acciones globales a un proyecto después de name/id y antes de 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"

Procesamiento por Lotes con axe bulk-spec

Para procesar múltiples archivos spec en una sola ejecución, use axe bulk-spec con un directorio que contenga archivos spec. La CLI busca recursivamente en el directorio y sus subdirectorios archivos spec.

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

El <output-directory> es opcional: si se omite, los resultados se guardan en el directorio de trabajo actual.

Las actualizaciones de progreso se imprimen en stdout durante la ejecución.

Los resultados se escriben en el directorio de salida: un archivo JSON por analyze acción, más un archivo de registro que lista cualquier archivo spec que falló y la razón del fallo.

Opciones

Las siguientes opciones están disponibles para axe spec:

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

Especifica la clave API del Hub para Desarrolladores de Axe. Se requiere (junto con --axe-devhub-project-id) para enviar resultados al Hub para Desarrolladores de Axe. Vea Enviar Resultados al Hub para Desarrolladores de Axe.

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

Especifica el ID del proyecto del Hub para Desarrolladores de Axe. Se requiere (junto con --axe-devhub-api-key) para enviar resultados al Hub para Desarrolladores de Axe. Vea Enviar Resultados al Hub para Desarrolladores de Axe.

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

Especifica la URL del servidor del Hub para Desarrolladores de Axe. Por defecto es https://axe.deque.com. Equivalente a la ", "context": "paragraph AXE_DEVHUB_SERVER_URL variable de entorno. Consulte ", "context": "paragraph Enviar resultados a Axe Developer Hub", "context": "link text.", "context": "paragraph

-c, --custom <path>

Especifica un archivo de conjunto de reglas personalizado, reemplazando el conjunto de reglas predeterminado.", "context": "paragraph

--descendant-links

Recopila los enlaces de cada página y los añade a los resultados. Requiere ", "context": "paragraph --verbose.", "context": "paragraph

--dismiss-alerts

Cierra automáticamente ", "context": "paragraph alert(), ", "context": "paragraph confirm(), y ", "context": "paragraph prompt() los diálogos del navegador antes de escanear.", "context": "paragraph

--enable-tracking <state>

Permite enviar datos a la biblioteca de métricas.", "context": "paragraph

--filter <type(s)>

Filtra tipos de resultados de la salida: ", "context": "paragraph passes, ", "context": "paragraph violations, ", "context": "paragraph incomplete, ", "context": "paragraph inapplicable. Requiere ", "context": "paragraph --format csv.", "context": "paragraph

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

Formato(s) de informe: ", "context": "paragraph html, ", "context": "paragraph junit, ", "context": "paragraph csv, o una combinación separada por comas. Predeterminado: ", "context": "paragraph html.", "context": "paragraph

--no-git-data

Excluye la información de la rama y el commit de Git al enviar resultados a Axe Developer Hub. Consulte ", "context": "paragraph Enviar resultados a Axe Developer Hub", "context": "link text.", "context": "paragraph

--page-name <name>

Ejecuta solo la página con el nombre especificado del archivo de especificaciones ", "context": "paragraph pageList.", "context": "paragraph

--page-source

Añade el código fuente HTML escaneado a los resultados. Requiere ", "context": "paragraph --verbose.", "context": "paragraph

--page-title

Añade el título de la página a los resultados. Requiere ", "context": "paragraph --verbose.", "context": "paragraph

--remote-proxy <proxy-server>

Redirige el tráfico a través del servidor proxy remoto especificado.", "context": "paragraph

--resume-from <name>

Omite todas las páginas antes de la página nombrada en el archivo de especificaciones ", "context": "paragraph pageList.", "context": "paragraph

--scanned-url

Añade la URL base y la URL del escaneo actual a los resultados detallados. Solo Chrome. Requiere ", "context": "paragraph --verbose.", "context": "paragraph

--set-distinct-id <id>

Reemplaza el valor de ID distinto.", "context": "paragraph

--set-legacy-mode

Permite el ", "context": "paragraph modo de escaneo heredado", "context": "link text, que se eliminará en la versión 5.0.", "context": "paragraph

--set-tracking-url <url>

Reemplaza la URL a la que se envían los datos de métricas.", "context": "paragraph

-t, --tags

Filtra el conjunto de reglas estándar por etiqueta.", "context": "paragraph

--user-agent

Establece una cadena de agente de usuario personalizada para el navegador.", "context": "paragraph

--validate

Valida su archivo de especificaciones sin ejecutarlo.", "context": "paragraph

-v, --verbose

Incluye salida adicional: resultados y metadatos de Axe como nombre de la herramienta, versión y entorno.", "context": "paragraph

Para opciones de configuración adicionales, consulte ", "context": "paragraph Configurar", "context": "link text.