Analizar páginas usando archivos 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

Cómo usar los subcomandos spec y bulk-spec para analizar páginas utilizando archivos spec

Not for use with personal data

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

El Comando axe spec

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

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

Ejemplo de uso:

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

Estructura del archivo spec

Un archivo spec 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

Propiedad Tipo Descripción
name cadena Nombre de visualización único del proyecto.
id cadena Identificador único del proyecto.
metadata objeto Opcional. Metadatos arbitrarios para su caso de uso (por ejemplo, nombre del producto, entorno).
globalActions arreglo Opcional. Acciones que responden a cambios de estado en cada página del proyecto, por ejemplo, cerrar un aviso de cookies o una encuesta emergente. Vea Acciones Globales.
screenshot objeto Opcional. Captura una captura de pantalla de cada página después del análisis. Vea Captura de Pantallas.
pageList arreglo Lista de páginas para analizar. Vea Página.

Página

Propiedad Tipo Descripción
name cadena Nombre de visualización de la página.
url cadena URL de la página.
actions arreglo Opcional. Acciones a realizar en la página antes o después del análisis. Vea Acciones.

Formato JSON/YAML

Los archivos spec pueden estar escritos en YAML o JSON. La siguiente tabla muestra los mismos valores en cada formato. Tenga en cuenta que en JSON, las cadenas de acciones que contienen comillas dobles deben escaparlas con una barra invertida.

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

Acciones

Las acciones son cadenas en el arreglo actions (o globalActions) de un archivo spec. Realizan tareas como hacer clic en botones, llenar formularios, cerrar diálogos, esperar estados de página 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 ser llamada al menos una vez por página.
  • Acciones globales se ejecutan en cada página del proyecto en respuesta a cambios de estado. Vea Acciones Globales.

Ejemplo completo de acción

El siguiente ejemplo inicia sesión en Deque University y analiza el tablero:

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 selector que identifica un elemento en la página. Un selector puede ser un selector CSS o un selector XPath, especificado como una única cadena o una lista de cadenas.

Para apuntar a elementos dentro de iframes, debe usar una lista. Todos los selectores en la lista excepto el último identifican elementos <iframe> sucesivos para navegar dentro, 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 del documento establecido por la entrada anterior: el primer selector es relativo al documento raíz, y cada selector de iframe subsiguiente es relativo al documento dentro del iframe anterior.

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 objetivo final (los selectores de iframe deben seguir siendo 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

La CLI soporta 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 un popup 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 ser llamada al menos una vez por página. Puede llamarla múltiples veces para analizar una página en diferentes puntos de un flujo de trabajo (use la variante with title para distinguir los resultados).

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

ID de conjunto de reglas Estándar
wcag2 WCAG 2.0 AA
wcag2.1 WCAG 2.1 AA (predeterminado)
wcag2.2 WCAG 2.2 AA
wcag2aaa WCAG 2.0 AAA
wcag2.1aaa WCAG 2.1 AAA
wcag2.2aaa WCAG 2.2 AAA
508 Sección 508
ttv5 Tester de Confianza v5
en301549 EN 301 549
rgaav4 RGAA v4

Para información sobre cómo incluir o excluir elementos, vea el documentación de la API axe-core sobre el parámetro 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

Ejemplo combinando múltiples opciones: Analizar solo las imágenes dentro de los elementos con la clase third-party y los formularios que no se validan al enviarse, excluyendo los 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 acción change cambia el valor de un elemento <input>, <textarea> o <select> mediante JavaScript. Use change cuando los eventos DOM normales no estén disponibles.

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

click

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

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

# Click the body element
click "body"

dismiss

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

note

Esta acción no cierra los diálogos nativos de alert() o confirm().

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

eval

La acción eval ejecuta JavaScript arbitrario en la página. Úsela 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 acción press envía una pulsación de tecla a un elemento (opcionalmente con teclas modificadoras). Para nombres de teclas compatibles, vea el 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 acción select selecciona un <option> de un elemento <select> por su texto visible (no por su atributo value).

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 acción type escribe una cadena en un elemento <input> o <textarea>. Úsela para completar formularios y llenar 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 acción wait espera que un elemento alcance un estado especificado o duerme durante una duración dada.

Estados de elementos compatibles: visible, hidden, selected, enabled, disabled, found.

Para esperas de estado de elemento, la acción reintentará hasta 3 veces por defecto (4 intentos totales) antes de fallar. Para esperar más tiempo por un elemento de carga lenta, agregue with <n> retries para aumentar el número de intentos.

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

# 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

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 manera procedimental como las acciones de página. Solo se admite actualmente 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 procedimentales: se activan en respuesta a eventos de página, no en una secuencia fija.
  • La acción global dismiss modal espera a que aparezca un modal especificado y lo cierra antes de que continúen las acciones de página.

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"

Captura de Pantallas

Para capturar una captura de pantalla de cada página después del análisis, agregue un objeto screenshot a un proyecto en su archivo spec. Cada página produce un archivo PNG llamado <page-id>-screenshot.png (cualquier / o \ en el id de la página se reemplaza con _). Si una página no tiene id, se deriva una de su name al eliminar todos los espacios en blanco.

Propiedad Tipo Por defecto Descripción
enabled booleano — Requerido. Establezca en true para habilitar la captura de capturas de pantalla. Funciona con todos los navegadores compatibles.
fullPage booleano false Captura la página completa desplazable usando el Protocolo DevTools de Chrome. Requiere Chrome o Chromium; otros navegadores vuelven a una captura de pantalla de la ventana con una advertencia.
boundingBoxes booleano false Agrega coordenadas de caja delimitadora (x, y, width y height) a cada nodo de violación en los resultados de Axe, registrando dónde aparece el elemento en la captura de pantalla.
dir cadena <output-dir>/<project-id>/ Directorio donde se escriben los archivos PNG de las capturas de pantalla.

Cuando ejecuta axe spec con --verbose, cada resultado también incluye un campo screenshotPath con la ruta completa al archivo de captura de pantalla de esa página.

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

Procesamiento por lotes con axe bulk-spec

Para procesar varios 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 acción analyze, 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 Axe Developer Hub. Requerido (junto con --axe-devhub-project-id) para enviar resultados al Axe Developer Hub. Ver Enviar Resultados a Axe Developer Hub.

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

Especifica el ID del proyecto del Axe Developer Hub. Requerido (junto con --axe-devhub-api-key) para enviar resultados al Axe Developer Hub. Ver Enviar Resultados a Axe Developer Hub.

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

Especifica la URL del servidor de Axe Developer Hub. El valor predeterminado es https://axe.deque.com. Equivalente a la variable de entorno AXE_DEVHUB_SERVER_URL. Ver Enviar Resultados a Axe Developer Hub.

-a, --axe-source <path>

Ruta a un archivo alternativo axe.js. La mayoría de los usuarios no necesitan esta opción. Está destinada para casos de uso avanzado, como pruebas contra una versión específica o parcheada de axe-core.

--chrome-options [options]

Pasa una lista de conmutadores de línea de comando de Chrome, separados por comas, a ChromeDriver. Utilice esto para habilitar funciones del navegador o para superar restricciones en ambientes específicos, por ejemplo, en entornos CI en contenedores donde se debe desactivar el sandbox.

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

-c, --custom <path>

Especifica un archivo de conjunto de reglas personalizado, reemplazando el conjunto de reglas predeterminado.

--descendant-links

Recoge los enlaces en cada página y los agrega a los resultados. Requiere --verbose.

--dismiss-alerts

Descarta automáticamente los diálogos del navegador alert(), confirm() y prompt() antes de escanear.

--enable-tracking <state>

Habilita el envío de datos a la biblioteca de métricas.

--filter <type(s)>

Filtra tipos de resultados del resultado: passes, violations, incomplete, inapplicable. Requiere --format csv.

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

Formato(s) del informe: html, junit, csv, universal, o una combinación separada por comas. Predeterminado: html. Ver --universal-ruleset y --universal-best-practices para opciones que se aplican al usar universal.

--no-analyze

Elimina el requisito de una acción analyze en la lista de acciones de cada página. Por defecto, cada página en un archivo de especificaciones debe incluir al menos una acción analyze; esta bandera desactiva esa verificación, lo cual es útil al ejecutar un flujo de trabajo que solo realiza acciones sin ejecutar un escaneo de accesibilidad.

--no-exit

Fuerza a la CLI a salir con el código 0 incluso cuando se encuentran violaciones. Por defecto, axe spec sale con el código 1 si se detectan violaciones. Use esto cuando quiera recoger resultados sin fallar en una construcción CI.

--no-git-data

Excluye la información de la rama de Git y el commit al enviar resultados al Axe Developer Hub. Ver Enviar Resultados a Axe Developer Hub.

--no-html

Impide que la CLI genere un informe HTML. Úselo junto con --format para controlar qué formatos de informe se escriben, o cuando solo quiera resultados en JSON sin un resumen en HTML.

--no-reports

Impide que el CLI genere cualquier archivo de informe. Los resultados aún se recopilan y se muestran en el terminal, pero no se escribe nada en el disco. Útil para comprobaciones rápidas donde no se necesitan archivos de salida.

--no-wait

Desactiva la pausa automática entre acciones del flujo de trabajo. Por defecto, las pausas configuradas con --post-get-pause, --post-script-pause y --post-analyze-pause se aplican entre acciones (ver Configurar); esta bandera las omite todas.

--page-name <name>

Ejecuta solo la página con el nombre especificado del pageList del archivo de especificaciones.

--page-source

Agrega el código fuente HTML escaneado a los resultados. Requiere --verbose.

--page-title

Agrega el título de la página a los resultados. Requiere --verbose.

--remote-proxy <proxy-server>

Redirige el tráfico a través del servidor proxy remoto especificado.

--resume-from <name>

Omite todas las páginas antes de la página nombrada en el pageList del archivo de especificaciones.

--scanned-url

Agrega la URL base y la URL de escaneo actual a los resultados detallados. Solo Chrome. Requiere --verbose.

--set-distinct-id <id>

Sobrescribe el valor del ID distinto.

--set-legacy-mode

Activa el modo de escaneo heredado obsoleto, que se eliminará en la versión 5.0.

important

Esta es una opción de último recurso. Se ha informado que permite completar escaneos en páginas que sobrescriben window.open(), una práctica desaconsejada.

--set-tracking-url <url>

Sobrescribe la URL donde se envían los datos de métricas.

--silent-mode

Suprime todo el texto decorativo de la salida de la CLI. Los resultados solo se muestran cuando --verbose también está activo. Use esto en scripts o canalizaciones de CI donde desee una salida limpia sin pancartas de progreso ni mensajes de estado.

-t, --tags

Filtra el conjunto de reglas estándar por etiqueta.

--universal-best-practices

Registra bestPracticesEnabled=true en los metadatos del formato de salida universal. Requiere --format universal.

--universal-ruleset <id>

Especifica el ID del conjunto de reglas para registrar en los metadatos del formato de salida universal. Predetermina a wcag2.1. Requiere --format universal. Vea tabla de conjuntos de reglas para valores válidos.

--user-agent

Establece una cadena de agente de usuario personalizada para el navegador.

--validate

Valida tu archivo de especificaciones sin ejecutarlo.

-v, --verbose

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

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

El número de nuevas conexiones de red que pueden establecerse antes de que la red se considere inactiva. Una vez que las nuevas conexiones caen a este umbral o por debajo, la CLI continúa con el escaneo. Úselo junto con --wait-network-idle-timeout para ajustar cuándo la CLI se ejecuta en páginas con actividad de red en segundo plano en curso.

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

El número de conexiones de red abiertas que pueden permanecer antes de que la red se considere inactiva. Una vez que las conexiones abiertas disminuyen al nivel de este umbral, el CLI procede con el análisis.

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

El intervalo en milisegundos en el que el CLI verifica si la red se ha vuelto inactiva. Reduzca este valor para una detección más rápida a costa de un mayor uso de CPU.

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

El tiempo máximo en milisegundos para esperar que la actividad de la red se estabilice antes de comenzar el análisis. Después de cargar la página, el CLI supervisa las conexiones de red activas y espera hasta que el conteo de conexiones alcance el umbral configurado. Si el tiempo de espera transcurre antes de que la red se vuelva inactiva, el CLI procede con el análisis de todos modos.

Para opciones de configuración adicionales, consulte Configurar.

Is this page helpful?

Help us improve this page

Still need help?