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 a ejecutar en cada página antes de analizar problemas de accesibilidad. Use axe spec para ejecutar un solo archivo spec, o axe bulk-spec para procesar un directorio de archivos spec.

El axe spec Comando

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 banner de cookies o una encuesta emergente. Consulte Acciones Globales.
screenshot objeto Opcional. Captura una captura de pantalla de cada página después del análisis. Ver Captura de Pantallas.
pageList arreglo Lista de páginas a analizar. Consulte 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. Consulte 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 actions (o globalActions) array de un archivo de especificaciones. Realizan tareas como hacer clic en botones, completar formularios, cerrar diálogos, esperar estados de página y realizar análisis de accesibilidad. Las acciones se ejecutan en el orden en que se enumeran.

Existen dos tipos de acciones:

  • Acciones de página se ejecutan en secuencia en una página específica. La analyze acción 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. Ver 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 <iframe> elementos sucesivos para 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 al contexto del 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 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 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: realizar 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

El analyze acción realiza un análisis de accesibilidad. Debe ser llamada al menos una vez por página. Puede llamarla varias veces para analizar una página en diferentes puntos de un flujo de trabajo (use la with title variante para distinguir los resultados).

El ruleset parámetro opcional especifica qué conjunto de reglas usar. El 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, consulte la 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 imágenes dentro de elementos con la clase third-party y formularios que no son validados en el envío, excluyendo elementos con la clase old-api, utilizando el 508 conjunto de reglas, 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

El change acción cambia el valor de un <input>, <textarea>, o <select> elemento mediante JavaScript. Úselo 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

El 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

El dismiss acción 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 segura si cualquiera de los elementos no está presente.

note

Esta acción no descarta alert() o confirm() diálogos nativos.

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

eval

El 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

El press acción envía una pulsación de tecla a un elemento (opcionalmente con teclas modificadoras). Para nombres de teclas soportadas, 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

El 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

El type acción escribe una cadena en un <input> o <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

El wait acción espera que un elemento alcance un estado especificado, o se detiene durante una duración dada.

Estados de elementos 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 manera procedimental como las acciones de página. Actualmente, solo se admite una acción global: dismiss modal.

  • Las acciones globales funcionan tanto en spec modo como en modo URI sin cabeza.
  • Las acciones globales no son procedimentales, se activan en respuesta a eventos de la página, no en una secuencia fija.
  • El dismiss modal acción global espera que aparezca un modal especificado y lo cierra antes de que continúen las acciones de la 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, añada un screenshot objeto a un proyecto en su archivo de especificaciones. Cada página produce un archivo PNG llamado <page-id>-screenshot.png (cualquier / o \ en la página id se reemplaza con _). Si una página no tiene id, uno se deriva de su name eliminando 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 Añade coordenadas del cuadro envolvente (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 screenshotPath campo 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 múltiples archivos de especificaciones en una sola ejecución, use axe bulk-spec con un directorio que contenga archivos de especificaciones. La CLI busca recursivamente en el directorio y sus subdirectorios archivos de especificaciones.

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, además de un archivo de registro que enumera cualquier archivo de especificaciones que haya fallado 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 de 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 del Axe Developer Hub. Por defecto 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 axe.js archivo alternativo. La mayoría de los usuarios no necesita esta opción. Está destinada a casos de uso avanzados, como pruebas con una versión específica o modificada 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

Recolecta los enlaces en cada página y los añade a los resultados. Requiere --verbose.

--dismiss-alerts

Descarta automáticamente alert(), confirm(), y prompt() cuadros de diálogo antes de escanear.

--enable-tracking <state>

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

--filter <type(s)>

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

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

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

--no-analyze

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

--no-exit

Fuerza al 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 desee recopilar resultados sin fallar una compilación de CI.

--no-git-data

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

--no-html

Impide que el CLI genere un reporte HTML. Use esto junto con --format para controlar qué formatos de informe se generan, o cuando solo desee 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); este indicador las omite todas.

--page-name <name>

Ejecuta solo la página con el nombre especificado del archivo de especificación pageList.

--page-source

Añade el código fuente HTML escaneado a los resultados. Requiere --verbose.

--page-title

Añade 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 anteriores a la página nombrada en el archivo de especificación pageList.

--scanned-url

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

--set-distinct-id <id>

Sobrescribe el valor del ID distinto.

--set-legacy-mode

Habilita el modo de escaneo heredadoobsoleto, que se eliminará en la versión 5.0.

important

Esta es una opción de último recurso. Se ha informado que permite completar los análisis 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 del CLI. Los resultados solo se muestran cuando --verbose también está activo. Use esto en scripts o pipelines de CI donde desee una salida limpia sin banners de progreso o mensajes de estado.

-t, --tags

Filtra el conjunto de reglas estándar por etiqueta.

--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 se pueden establecer antes de que la red se considere inactiva. Una vez que las nuevas conexiones disminuyen al nivel de este umbral, el CLI procede con el análisis. Use junto con --wait-network-idle-timeout para ajustar cuándo el CLI se ejecuta en páginas con actividad de red de fondo 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, ver Configurar.

Is this page helpful?

Help us improve this page

Still need help?