Referencia de API para la versión de JavaScript y TypeScript de Watcher

Esta guía de referencia describe las APIs proporcionadas por el @axe-core/watcher paquete (también conocido como Axe Watcher o simplemente Watcher) para JavaScript y TypeScript.

AxeConfiguration Interfaz

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

apiKey

(Requerido) El apiKey valor es una de dos propiedades (apiKey y projectId) que deben establecerse en tu AxeConfiguration. Puedes obtener su valor en la Página de Gestión de Claves API .

autoAnalyze

(Opcional) Establece este valor en false para evitar que las páginas se analicen automáticamente. Para más información sobre el modo manual, consulta Controlar Tus Análisis.

buildID

(Opcional) La propiedad buildID , cuando no está null, permite a los corredores de pruebas paralelas generar resultados que aparecen como una única ejecución de prueba en axe Developer Hub. En el caso de ejecuciones de pruebas paralelas, cada corredor de pruebas debería 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 mismo buildID y SHA de confirmación de Git. Sin embargo, cuando buildID está null, múltiples ejecuciones de prueba sobrescriben los resultados existentes que tienen el mismo SHA de confirmación de Git.

Consulta Ejecución de Pruebas en Paralelo para obtener más información sobre cómo usar buildID con varios proveedores de integración continua.

configurationOverrides

(Opcional) Sobrescribe los valores establecidos en la configuración global. Consulta la Interfaz de Sobrescritura de Configuración para más información.

excludeUrlPatterns

(Opcional) Impide que cualquier URL que coincida con los patrones minimatch en el excludeUrlPatterns arreglo se analice.

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

En Excluir URLs del Análisis puedes encontrar una tabla de URLs y patrones de ejemplo para verificar coincidencias.

git

(Opcional) Controla cómo Watcher recopila metadatos de Git para la ejecución de la prueba actual. Acepta uno de tres valores:

• true (por defecto): Watcher recopila automáticamente la información de Git (rama, SHA de commit, autor y otros campos) usando el ejecutable local de Git.
• false: Desactiva toda recolección de metadatos de Git. Utilice esto cuando opere en entornos sin Git o cuando no se necesite la recolección de datos de Git.
• Un GitConfig objeto: Proporciona metadatos de Git explícitos y omite la detección automática por completo. Cualquier campo que omita tendrá por defecto null. Utilice esto cuando sus pruebas se ejecuten en un repositorio separado del repositorio bajo prueba, o en entornos CI donde la detección automática de Git no sea confiable.

Consulte Proporcionar Metadatos de Git para más información.

El GitConfig objeto tiene los siguientes campos opcionales:

Ejemplo usando variables de entorno CI para proporcionar metadatos explícitos de Git:

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: '<your-project-id>',
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    defaultBranch: 'main'
  }
}

projectId

(Requerido) Especifica el ID del proyecto que recibirá los resultados de accesibilidad de Watcher. Su ID de proyecto se muestra con las instrucciones cuando crea un nuevo proyecto, y también puede obtenerlo de la Página de Proyectos del eje Developer Hub .

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. Un conjunto de selectores CSS para los elementos que se incluirán en el análisis:

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

3. Un objeto contexto que contiene las propiedades include y exclude (como se muestra en el ejemplo anterior). Puede especificar include o exclude o ambos. Cada include o exclude puede ser un solo selector CSS o un conjunto de selectores CSS:

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

Más detalles están disponibles en el Documentación de Context de axe-core.

runOptions

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

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

  important

  Si tu página utiliza IDs dinámicos o clases (IDs o clases de elementos que cambian cada vez que se recarga la página), debes especificar ancestry como true para que el Centro de Desarrolladores de Axe pueda detectar y seguir correctamente si los problemas de accesibilidad son duplicados ya que, por defecto, el Centro de Desarrolladores de Axe espera que los IDs y las clases de los elementos permanezcan iguales entre las ejecuciones de prueba.

  Cuando ancestry es true, el Centro de Desarrolladores de Axe utiliza en su lugar la posición del elemento dentro del árbol DOM para localizar el mismo elemento entre las ejecuciones de prueba.

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

  iframe#main-iframe

  Si ancestry es true, el selector incluiría todo el camino desde el elemento raíz, y no hay IDs o clases especificadas:

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

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

• rules: Habilita o deshabilita reglas usando la enabled propiedad. Consulta rules 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 runOnly valor (parte del runOptions objeto) puede ser uno de los siguientes:

1. Una cadena que representa el ID de la regla que te gustaría usar para el análisis de accesibilidad:

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

2. Un arreglo de cadenas que representan los IDs de las reglas que te gustaría usar:

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

3. Un objeto con type y values propiedades. El type valor es una cadena que puede ser rule, rules, tag, o tags. La values propiedad debe ser un array de cadenas que representen la(s) regla(s) o etiqueta(s) que desea utilizar para el análisis de accesibilidad. El siguiente ejemplo muestra cómo usar el runOnly objeto para limitar las pruebas de accesibilidad a reglas etiquetadas como wcag2a:

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

• Para más ejemplos de uso de runOnly (con axe-core), consulte Ejemplos de Parámetros de Opciones
• Para obtener más información sobre los valores de etiquetas disponibles, consulte Etiquetas de axe-core.
• Para obtener información sobre las reglas, los ID de reglas y las etiquetas, consulte Descripciones de Reglas

rules

El rules valor (en el runOptions objeto) 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

(Opcional) La sessionId propiedad ha quedado obsoleta y no debe utilizarse. Vea buildID arriba.

testingTypes

(Opcional) La testingTypes propiedad es un array de cadenas para usar con Cypress para especificar pruebas de componentes o e2e (end-to-end) (o ambas).

axe: {
  testingTypes: ['e2e', 'component']
}

timeout

(Opcional) El timeout objeto (de tipo Timeouts) en AxeConfiguration establece los valores de tiempo de espera en milisegundos para los métodos de controladores respectivos (o comandos personalizados para Cypress). (Vea los Clases de Controladores para obtener información sobre las clases de controladores y los Comentarios Personalizados de Cypress para obtener información sobre los comandos personalizados de Cypress.) Cuando el tiempo de espera expira, la prueba falla con un mensaje que indica que el tiempo de espera fue excedido. Puede aumentar el tiempo de espera para evitar el error.

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

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

Funciones de Configuración

Las funciones de configuración proporcionadas por Watcher le permiten modificar su configuración para el marco de pruebas especificado, así como personalizar cómo desea ejecutar Watcher para adaptarlo a sus necesidades. Vea Interfaz de Configuración de Axe para 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

  Intersección del tipo de Cypress.ConfigOptions y Configuration.

Devuelve: Cypress.ConfigOptions

playwrightConfig

Crea una configuración para Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parámetros

• opts: Configuration & LaunchOptions

  Intersección del tipo de LaunchOptions y Configuration.

Devuelve: LaunchOptions

playwrightTest

Crea una configuración para Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parámetros

• options: Options

  Options es una intersección del tipo de Configuration 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

  Intersección del tipo de LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions, y Configuration.

Devuelve: Options

wdioConfig

Crea una configuración de WebdriverIO.

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

wdioConfig Parámetros

• arg: Options

  Options es una intersección del tipo de RemoteOptions y Configuration.

Devuelve: RemoteOptions

wdioTestRunner

Crea una configuración de WebdriverIO Testrunner.

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

wdioTestRunner Parámetros

• params: unknown[]

  El params valor es uno de los siguientes:

  1. Un arreglo que contiene un valor, el cual es un tipo de intersección de Options.Testrunner y Configuration.
  2. Un arreglo donde el primer valor del arreglo es un AxeConfiguration y el segundo valor es un Options.Testrunner.

**Devuelve**: Options.Testrunner

webdriverConfig

Crea una configuración de Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parámetros

• arg: WebDriverArgs

  Un Configuration extendido para incluir un miembro de Selenium WebDriver Options .

**Devuelve**: Options

Configuration Interfaz

La Configuration interfaz se utiliza con las funciones de configuración y contiene una propiedad:

Todas las funciones de configuración utilizan esta axe propiedad para permitirle configurar Watcher y configurar sus pruebas de accesibilidad. Vea la siguiente sección, Interfaz AxeConfiguration, para más información.

ConfigurationOverrides Interfaz

La ConfigurationOverrides interfaz le permite anular la configuración global de su organización en ejecuciones de pruebas individuales. 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 prueban. Opciones disponibles:

• „All“ - Pruebas 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“
• „RGAAv4“ - versión 4 del RGAA (estándar de accesibilidad francés; requiere axe-core 4.11.0 o posterior)

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 usar para las pruebas. Las opciones disponibles incluyen:

• „latest“ - Última versión soportada actualmente incluida con Axe Watcher
• Versiones específicas desde la 4.4.0 en adelante (por ejemplo, „4.10.2“, „4.9.1“, etc.)

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

bestPractices

Habilita o deshabilita las reglas de mejores prácticas para la ejecución de la prueba. 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 surta efecto.

experimentalRules

Habilita o deshabilita las reglas experimentales para la ejecución de la prueba. 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 surta efecto.

Controller Clases

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

Controller

abstract class Controller

La Controller clase abstracta contiene los métodos para controlar el análisis de página. 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. Llama a este método después de haber configurado una página web para el análisis (como ingresar valores en un formulario) y haber desactivado el análisis automático usando el stop método o configurando autoAnalyze en false.

analyze Devuelve

Promise<void>

analyze Comando de Cypress equivalente

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Envía todos los resultados del escaneo de accesibilidad a Axe Developer Hub. Debe llamarse al final de la ejecución de la prueba para asegurar que los resultados hayan sido enviados a los servidores de Axe Developer Hub de Deque.

flush Devuelve

Promise<void>

flush Comando de Cypress equivalente

cy.axeWatcherFlush()

start

start(): Promise<void>

Resumir 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 para detectar errores de accesibilidad.

start Devuelve

Promise<void>

start Comando de Cypress equivalente

cy.axeWatcherStart()

stop

stop(): Promise<void>

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

stop Devuelve

Promise<void>

stop Comando de Cypress equivalente

cy.axeWatcherStop()

PlaywrightController

El PlaywrightController clase te permite controlar manualmente el análisis de accesibilidad para ejecuciones de pruebas con Playwright y Playwright Test. Puedes iniciar y detener el análisis automático de accesibilidad y analizar páginas que requieren configuraciones adicionales.

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

Constructor

new PlaywrightController(driver: Page): PlaywrightController

Parámetros

• driver: Page

El driver valor es un Page objeto de Playwright.

Devuelve PlaywrightController

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

PuppeteerController

El PuppeteerController clase permite un control manual de tus ejecuciones de pruebas con Puppeteer. El control manual te permite proporcionar configuraciones adicionales requeridas por páginas web más complejas.

Para más información sobre Puppeteer, consulta Puppeteer.

Constructor

new PuppeteerController(driver: Page): PuppeteerController

Parámetros

• driver: Page

El driver valor es un Page objeto de Puppeteer.

Devuelve PuppeteerController

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

WdioController

El WdioController te permite controlar manualmente las ejecuciones de pruebas de WebdriverIO y WebdriverIO Testrunner. Para páginas que requieren configuraciones o ajustes adicionales, puedes detener las pruebas automáticas y analizar manualmente cada página que requiera tal configuración.

Constructor

new WdioController(driver: Browser): WdioController

Parámetros

• driver: Browser

Devoluciones WdioController

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

Controlador Webdriver

Constructor

new WebdriverController(driver: WebDriver): WebdriverController

Parámetros

• driver: WebDriver

El driver valor es un WebDriver objeto de Selenium.

Devoluciones WebdriverController

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

Comandos Personalizados de Cypress

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

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

Ejemplo de Comando Cypress

El siguiente ejemplo muestra cómo importar los comandos de Cypress del Hub de Desarrolladores de Axe 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/cypress/support')

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

Interfaz de Tiempos de Espera

El objetivo de tiempo de espera objeto (del tipo Tiempos de Espera) en la interfaz de Configuración de Axe permite a los usuarios cambiar los valores de tiempo de espera (en milisegundos) para las funciones del controlador respectivas o los comandos personalizados de Cypress.

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