Referencia de la API

Esta guía de referencia describe las API proporcionadas por el paquete (también conocido como @axe-core/watcher axe Watcher *o simplemente * Watcher ).

AxeConfiguration Interfaz

La propiedad axe (un parámetro pasado a las funciones de configuración) es el medio habitual para cambiar su AxeConfiguration para que axe Watcher configure las pruebas de accesibilidad. Las siguientes propiedades están contenidas en AxeConfiguration:

apiKey

El apiKey valor es la única propiedad que debe establecerse en su AxeConfiguration. Puede obtener su valor desde la Página de Proyectos. Consulte Administración de proyectos para obtener más información.

autoAnalyze

Establezca este valor en false para evitar que las páginas se analicen automáticamente. Para obtener más información sobre el modo manual, consulte Controlar Cuándo Se Realiza el Análisis de Página.

buildID

La propiedad opcional buildID , cuando no está establecida null, permite que los ejecutores de pruebas paralelos generen resultados que aparecen como una única ejecución de prueba en axe Developer Hub. En el caso de ejecuciones de pruebas paralelas, cada ejecutor de pruebas debe compartir la misma buildID cadena no nula, lo que hace que cada ejecución de prueba concatene sus resultados con los resultados existentes para el buildID mismo SHA de confirmación de Git. Sin embargo, cuando buildID es null, varias ejecuciones de pruebas sobrescriben los resultados existentes que tienen el mismo SHA de confirmación de Git.

Generalmente, puede obtener un valor utilizable de su proveedor de integración continua. buildID Por ejemplo, puede utilizar estos valores:

• github.run_id

  Disponible dentro de los flujos de trabajo de GitHub. Consulte contexto de GitHub en la documentación de GitHub para obtener más información.

• CIRCLE_PIPELINE_ID

  Con CircleCI, el valor anterior está disponible en el entorno de su proceso. Consulte Variables de entorno integradas en la documentación de CircleCI para obtener más información.

  Otras variables de entorno de integración continua que puedes utilizar para: buildID

  Proveedor	Variable de entorno
  Bitbucket	BITBUCKET_BUILD_NUMBER
  GitLab	CI_PIPELINE_ID
  Jenkins	BUILD_NUMBER

configurationOverrides

(Opcional) Anula los valores establecidos en la configuración global. Consulte la interfaz ConfigurationOverrides para obtener más información.

excludeUrlPatterns

(Opcional) Evita que se analice cualquier URL que coincida con cualquiera de los patrones minimatch en la matriz excludeUrlPatterns .

axe: {
  excludeUrlPatterns: [ 'https://*.example.com/**', 'https://example.org/**' ]
}

Ejemplos

runContext

(Opcional) Le permite elegir qué elementos se incluyen y excluyen del análisis de accesibilidad de su página.

El valor de runContext puede ser:

1. Un único selector CSS para los elementos que se incluirán en el análisis:

   axe: {
     runContext: '.main'
   }

2. Una matriz de selectores CSS para los elementos que se incluirán en el análisis:

   axe: {
     runContext: [ '.main', '.text-block' ]
   }

3. Un objeto de contexto que contiene include y exclude propiedades (como se muestra en el ejemplo anterior). Puede especificar include o exclude o ambos. include o exclude cada uno puede ser un único selector CSS o una matriz de selectores CSS:

   axe: {
     runContext: {
       include: '.main',
       exclude: '.ad-section'
     }
   }

Hay más detalles disponibles en la documentación de contexto de axe-core.

runOptions

(Opcional) El objeto runOptions permite el siguiente subconjunto de propiedades del tipo axe-core Options :

• ancestry: El valor predeterminado es false. Si true, los selectores CSS devueltos incluyen los elementos ancestros de los elementos devueltos.

  important

  Si su página usa clases o identificadores dinámicos (clases o identificadores de elementos que cambian cada vez que se vuelve a cargar la página), debe especificar ancestry como true para que axe Developer Hub pueda detectar y rastrear correctamente si los problemas de accesibilidad son duplicados porque, de manera predeterminada, axe Developer Hub espera que las clases y los identificadores de elementos permanezcan iguales entre ejecuciones de pruebas.

  Cuando ancestry es true, axe Developer Hub utiliza la posición del elemento dentro del árbol DOM para localizar el mismo elemento entre ejecuciones de prueba.

  A continuación se muestra un ejemplo de un selector para un elemento iframe con un ID de main-iframe: ancestry false ** <iframe id="main-iframe" ...>

  iframe#main-iframe

  Si ancestry es true, el selector incluiría la ruta completa desde el elemento raíz y no hay identificadores ni clases especificados:

  html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

• runOnly: Esto le permite limitar qué reglas se ejecutan especificando nombres o etiquetas. Consulte runOnly a continuación para obtener más información.

• rules: Habilite o deshabilite reglas usando la propiedad enabled . Consulte las reglas a continuación para obtener más información.

A continuación se muestra un ejemplo de runOptions:

axe: {
  runOptions: {
    ancestry: true,
    runOnly: {
      type: 'tag',
      values: 'wcag2a'
    },
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

runOnly

El valor (parte del objeto [runOptions] runOnly ) puede ser uno de los siguientes:(#runoptions)

1. Una cadena que representa el ID de la regla que desea utilizar para el análisis de accesibilidad:

   axe: {
     runOptions: {
       runOnly: 'ruleId'
     }
   }

2. Una matriz de cadenas que representan los identificadores de las reglas que desea utilizar:

   axe: {
     runOptions: {
       runOnly: [ 'ruleId1', 'ruleId2' ]
     }
   }

3. Un objeto con type propiedades values . El valor es una cadena que puede ser reglas, una regla, una etiqueta o etiquetas. type ** ** ** ** La propiedad puede ser una cadena o una matriz de cadenas que representan la regla o las etiquetas que desea utilizar para el análisis de accesibilidad. values El siguiente ejemplo muestra el uso del objeto runOnly para limitar las pruebas de accesibilidad a las reglas etiquetadas como wcag2a:

   axe: {
     runOptions: {
       runOnly: {
         type: 'tag',
         values: 'wcag2a'
       }
     }  
   }

• Para obtener más ejemplos de uso (con axe-core), consulte [Ejemplos de parámetros de opciones]. runOnly (https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter-examples)
• Para obtener más información sobre los valores de etiquetas disponibles, consulte Etiquetas axe-core.
• Para obtener información sobre las reglas, los identificadores de reglas y las etiquetas, consulte [Descripciones de reglas].(https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)

rules

El valor rules (en el objeto runOptions ) le permite habilitar (enabled: true) o deshabilitar (enabled: false) reglas específicas durante el análisis, como se muestra a continuación:

axe: {
  runOptions: {
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

sessionId

La propiedad sessionId está obsoleta y no debe utilizarse. Consulte buildID arriba.

timeout

El objeto timeout (de tipo Timeouts) en AxeConfiguration establece los valores de tiempo de espera en milisegundos para los respectivos métodos del controlador (o comandos personalizados para Cypress). (Consulte Clases de controlador para obtener información sobre las clases de controlador y Comandos personalizados de Cypress para obtener información sobre los comandos personalizados de Cypress). Cuando expira un tiempo de espera, la prueba falla con un mensaje que indica que se excedió el tiempo de espera. Puede aumentar el tiempo de espera para evitar el error.

Este ejemplo establece el tiempo de espera en 8 segundos, 15 segundos, 10 segundos y 10 segundos. analyze flush start stop (Los valores predeterminados se muestran en la tabla en Interfaz Timeouts.)

axe: {
  timeout: {
    analyze: 8000
    flush: 15000,
    start: 10000,
    stop: 10000,
  }
}

Clases de controlador

Funciones de configuración

Las funciones de configuración proporcionadas por Watcher te permiten modificar tu configuración para el marco de prueba especificado, así como adaptar la forma en que quieres ejecutar Watcher para satisfacer tus necesidades. Consulte Interfaz de configuración de Axe para obtener más información.

cypressConfig

Crea una configuración para Cypress.

cypressConfig(config: Cypress.ConfigOptions & Configuration): Cypress.ConfigOptions

cypressConfig Parámetros

• config: Cypress.ConfigOptions & Configuration

  Tipo de intersección de Cypress.ConfigOptions y Configuración.

Devuelve: Cypress.ConfigOptions

playwrightConfig

Crea una configuración para Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parámetros

• opts: Configuration & LaunchOptions

  Tipo de intersección de LaunchOptions y Configuración.

Devuelve: LaunchOptions

playwrightTest

Crea una configuración para Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parámetros

• options: Options

  Options es un tipo de intersección de Configuración y LaunchOptions.

Devuelve: ReturnValue

puppeteerConfig

Crea una configuración para Puppeteer.

puppeteerConfig(opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions): Options

puppeteerConfig Parámetros

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  Tipo de intersección de LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions y Configuración.

Devuelve: Options

wdioConfig

Crea una configuración de WebdriverIO.

wdioConfig({ axe, ...options}: Options): RemoteOptions

wdioConfig Parámetros

• arg: Options

  Options es un tipo de intersección de RemoteOptions y Configuración.

Devoluciones: RemoteOptions

wdioTestRunner

Crea una configuración de WebdriverIO Testrunner.

wdioTestRunner(...params: unknown[]): Options.Testrunner

wdioTestRunner Parámetros

• params: desconocido[]

  El valor de params es uno de los siguientes:

  1. Una matriz que contiene un valor, que es un tipo de intersección de Options.Testrunner y Configuration.
  2. Una matriz donde el primer valor de la matriz es un AxeConfiguration y el segundo valor es un Options.Testrunner.

Devoluciones: Options.Testrunner

webdriverConfig

Crea una configuración de Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parámetros

• arg: WebDriverArgs

  Una Configuración ampliada para incluir un elemento Selenium WebDriver Options .

Devoluciones: Options

Configuration Interfaz

Configuration La interfaz se utiliza con las [funciones de configuración] y contiene una propiedad:(#configuration-functions)

Todas las funciones de configuración usan esta axe propiedad para permitirle configurar Watcher y realizar sus pruebas de accesibilidad. Consulte la siguiente sección, AxeConfiguration Interface, para obtener más información.

ConfigurationOverrides Interfaz

La interfaz le permite anular la configuración global de su organización para ejecuciones de pruebas individuales. ConfigurationOverrides Esta propiedad debe utilizarse de acuerdo con los permisos establecidos en la configuración global de su empresa.

accessibilityStandard

Establece el estándar de accesibilidad contra el cual se realizará la prueba. Opciones disponibles:

• 'Todos' - Prueba contra todos los estándares disponibles
• 'WCAG 2.2 AAA'
• 'WCAG 2.2 AA'
• 'WCAG 2.2 A'
• 'WCAG 2.1 AAA'
• 'WCAG 2.1 AA'
• 'WCAG 2.1 A'
• 'WCAG 2.0 AAA'
• 'WCAG 2.0 AA'
• 'WCAG 2.0 A'
• 'Trusted Tester v5'
• 'EN 301 549'

Su organización debe permitir la anulación de esta configuración en la configuración global, y el estándar seleccionado debe estar entre las opciones permitidas.

axeCoreVersion

Especifica qué versión de axe-core utilizar para las pruebas. Las opciones disponibles incluyen:

• 'latest' - Última versión compatible actualmente incluida con axe Watcher
• Versiones específicas de 4.4.0 y posteriores (por ejemplo, '4.10.2', '4.9.1', etc.)

Su organización debe permitir anular esta configuración en la configuración global, y la versión seleccionada debe estar entre las opciones permitidas.

bestPractices

Habilita o deshabilita reglas de mejores prácticas para la ejecución de pruebas. Las mejores prácticas mejoran la accesibilidad pero no forman parte de estándares formales. Su organización debe permitir la anulación de esta configuración para que tenga efecto.

experimentalRules

Habilita o deshabilita reglas experimentales para la ejecución de pruebas. Las reglas experimentales aún están en desarrollo y pueden producir falsos positivos. Su organización debe permitir la anulación de esta configuración en la configuración global para que tenga efecto.

Controller Clases

Las siguientes clases extienden la clase abstracta Controller para permitirle controlar manualmente el análisis de accesibilidad de las páginas de su sitio web.

Controller

abstract class Controller

La clase abstracta contiene los métodos para controlar el análisis de páginas. Controller Cada una de las clases concretas extiende esta clase, por lo que los siguientes métodos están disponibles en todas las clases concretas.

analyze

analyze(): Promise<void>

Analiza la página actual en busca de errores de accesibilidad. Debe llamar a este método después de haber configurado una página web para su análisis (por ejemplo, valores ingresados en un formulario) y haber desactivado el análisis automático utilizando el método stop o configurando autoAnalyze en false.

analyze Devuelve

Promise<void>

analyze Comando equivalente de Cypress

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Envía todos los resultados del análisis de accesibilidad al Centro de desarrolladores de Axe. Se debe llamar al final de la ejecución de la prueba para garantizar que los resultados se hayan enviado a los servidores de Deque's axe Developer Hub.

flush Devoluciones

Promise<void>

flush Comando equivalente de Cypress

cy.axeWatcherFlush()

start

start(): Promise<void>

Reanuda el análisis automático de páginas web. Llama a este método cuando quieras reanudar el análisis automático de páginas web en busca de errores de accesibilidad.

start Devoluciones

Promise<void>

start Comando equivalente de Cypress

cy.axeWatcherStart()

stop

stop(): Promise<void>

Detiene el análisis automático de páginas web. Después de llamar al método stop , puede realizar cualquier configuración adicional que su página web pueda requerir y luego llamar al método analyze para verificar si hay errores de accesibilidad en la página.

stop Devuelve

Promise<void>

stop Comando equivalente de Cypress

cy.axeWatcherStop()

PlaywrightController

La clase le permite controlar manualmente el análisis de accesibilidad para ejecuciones de pruebas con Playwright y Playwright Test. PlaywrightController Puede iniciar y detener el análisis automático de accesibilidad y analizar páginas que requieran configuración adicional.

Para obtener más información sobre Playwright, consulte la Documentación de Playwright.

Constructor

new PlaywrightController(driver: Page): PlaywrightController

Parámetros

• driver: Page

El valor es un objeto Playwright [Page] driver .(https://playwright.dev/docs/api/class-page)

Devoluciones PlaywrightController

Consulte Controller para conocer los métodos implementados en la clase base abstracta.

PuppeteerController

La clase permite el control manual de sus ejecuciones de pruebas con Puppeteer. PuppeteerController El control manual le permite proporcionar configuración adicional requerida por páginas web más complejas.

Para obtener más información sobre Puppeteer, consulte Puppeteer.

Constructor

new PuppeteerController(driver: Page): PuppeteerController

Parámetros

• driver: Página

El valor es un objeto Puppeteer [Page] driver .(https://pptr.dev/api/puppeteer.page)

Returns PuppeteerController

Consulte Controller para conocer los métodos implementados en la clase base abstracta.

WdioController

Le permite controlar manualmente las ejecuciones de pruebas de WebdriverIO y WebdriverIO Testrunner. WdioController Para las páginas que requieren instalación o configuración adicional, puede detener las pruebas automáticas y analizar manualmente cada página que requiera dicha configuración.

Constructor

new WdioController(driver: Browser): WdioController

Parámetros

• driver: Browser

Returns WdioController

Consulte Controller para conocer los métodos implementados en la clase base abstracta.

WebdriverController

Constructor

new WebdriverController(driver: WebDriver): WebdriverController

Parámetros

• driver: WebDriver

El valor es un objeto Selenium [WebDriver]. driver (https://www.selenium.dev/documentation/webdriver/)

Devuelve WebdriverController

Consulte Controller para conocer los métodos implementados en la clase base abstracta.

Comandos personalizados de Cypress

En la plataforma de automatización del navegador Cypress, los métodos de las clases *Controller se implementan como comandos personalizados. Consulte Comandos personalizados en el sitio de documentación de Cypress para obtener más información sobre la implementación y el uso de comandos personalizados.

Se implementan los siguientes comandos personalizados. Cada comando personalizado devuelve Chainable<void> para permitir el encadenamiento con otros comandos de Cypress.

Ejemplo de comando Cypress

El siguiente ejemplo muestra cómo importar los comandos Cypress de axe Developer Hub desde el paquete @axe-core/watcher y luego llamar al comando axeWatcherFlush al final de cada prueba (colocándolo dentro de afterEach()):

// Import the axe-watcher commands.
require('@axe-core/watcher/dist/cypressCommands')

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

Interfaz de tiempos de espera

El objeto timeout (de tipo Timeouts) en la interfaz AxeConfiguration permite a los usuarios cambiar los valores de tiempo de espera (en milisegundos) para las respectivas funciones del controlador o los comandos personalizados de Cypress.

interface Timeouts {
  start?: number
  stop?: number
  flush?: number
  analyze?: number
}