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

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

Interfaz AxeConfiguration

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

apiKey

(Requerido) El valor de apiKey es una de las dos propiedades (apiKey y projectId) que deben establecerse en su AxeConfiguration. Puede obtener su valor desde la Página de administración de claves API .

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY
}

autoAnalyze

(Opcional) 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 Tus Análisis.

axe: {
  autoAnalyze: false
}

buildID

(Opcional) La propiedad buildID, cuando no es null, permite que los ejecutores de pruebas paralelas generen resultados que aparezcan como una sola ejecución de prueba en Axe Developer Hub. En el caso de ejecuciones de pruebas paralelas, cada ejecutor de pruebas debe compartir la misma cadena buildID 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 es null, múltiples ejecuciones de prueba sobrescriben los resultados existentes que tienen el mismo SHA de confirmación de Git.

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

axe: {
  buildID: process.env.CI_BUILD_ID
}

configurationOverrides

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

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA',
    bestPractices: true
  }
}

elementInternals

(Opcional) Cuando true, Watcher recopila roles y propiedades ARIA establecidos mediante la API ElementInternals de elementos personalizados que usan attachInternals(). Esto reduce los falsos positivos en páginas que utilizan elementos personalizados para componentes interactivos. Requiere la versión 4.12.0 o posterior de axe-core.

axe: {
  elementInternals: true
}

excludeUrlPatterns

(Opcional) Impide que cualquier URL que coincida con cualquiera de los patrones patrones minimatch en la matriz excludeUrlPatterns sea analizado.

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

En Excluir URLs del Análisis puede 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 (predeterminado): Watcher recopila automáticamente información de Git (rama, SHA de confirmación, autor y otros campos) usando el binario local de Git.
• false: Desactiva toda la recopilación de metadatos de Git. Úselo cuando se ejecute en entornos sin Git o cuando no se necesite la recopilación de datos de Git.
• Un objeto GitConfig: Proporciona metadatos explícitos de Git y omite completamente la detección automática. Cualquier campo que omita predetermina a null. Úselo cuando sus pruebas se ejecuten en un repositorio que está separado del repositorio bajo prueba, o en entornos de CI donde la detección automática de Git no es confiable.

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

El objeto GitConfig tiene los siguientes campos:

branch, commitSha y url son los campos completos de Git: una sesión enviada sin los tres se registra como gitless y se guarda, pero Axe Developer Hub cambia a la vista de sesión sin Git, donde el historial de ramas y confirmación de sesiones anteriores no estará visible. Enviar una sesión posterior con los tres campos restaura la vista completa de Git. Si solo uno o dos de los tres están presentes, Axe Watcher elimina todos los campos completos de Git, registra la sesión como sin Git y incluye una advertencia en la respuesta.

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

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    url: process.env.GIT_URL,
    commitAuthor: process.env.GIT_AUTHOR_NAME,
    commitEmail: process.env.GIT_AUTHOR_EMAIL,
    commitMessage: process.env.GIT_COMMIT_MESSAGE,
    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 desde la Página de Proyectos de Axe Developer Hub .

axe: {
  projectId: process.env.AXE_PROJECT_ID
}

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 de contexto que contiene 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 único selector CSS o una matriz de selectores CSS:

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

Hay más detalles disponibles en el Documentación de Context de axe-core.

runOptions

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

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

  important

  Si su página usa IDs o clases dinámicas (IDs de elementos o clases que cambian cada vez que se recarga la página), debe especificar ancestry como true para que Axe Developer Hub pueda detectar y rastrear adecuadamente si hay problemas de accesibilidad duplicados porque, por defecto, Axe Developer Hub espera que los IDs y clases de los elementos se mantengan iguales entre ejecuciones de prueba.

  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.

  Lo siguiente 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 la ruta completa desde el elemento raíz, y no habría 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 le permite limitar qué reglas se ejecutan especificando nombres o etiquetas. Vea runOnly a continuación para más información.

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

Lo siguiente muestra un ejemplo de runOptions:

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

runOnly

El valor runOnly (parte del objeto runOptions) 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 propiedades type y values. El valor type es una cadena que puede ser rule, rules, tag o tags. La propiedad values debe ser un array de cadenas que representen la(s) regla(s) o etiqueta(s) que desea usar para el análisis de accesibilidad. El siguiente ejemplo muestra cómo usar el objeto runOnly 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 más información sobre los valores de etiquetas disponibles, consulte Etiquetas de axe-core.
• Para información sobre las reglas, identificadores de reglas y etiquetas, consulte Descripciones de Reglas

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 }
    }
  }
}

serverURL

(Opcional) La URL del servidor de Axe Developer Hub a la que Watcher envía los resultados de accesibilidad. Por defecto es https://axe.deque.com.

No necesita establecer este valor si su proyecto fue creado en axe.deque.com. Sin embargo, si su organización utiliza una instancia regional, nube privada o implementación local de Axe Developer Hub, establezca serverURL en la URL base de esa instancia:

axe: {
  apiKey: process.env.ACCESSIBILITY_API_KEY,
  projectId: process.env.PROJECT_ID,
  serverURL: process.env.SERVER_URL // e.g., 'https://axe-eu.deque.com'
}

sessionId

(Opcional) La propiedad sessionId ha sido desaprobada y no debe usarse. Consulte buildID arriba.

testingTypes

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

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

timeout

(Opcional) El objeto timeout (de tipo Timeouts) en AxeConfiguration establece los valores de tiempo de espera en milisegundos para los métodos del controlador respectivos (o comandos personalizados para Cypress). (Consulte el Clases de Controladores para obtener información sobre las clases de controlador y el Comentarios Personalizados de Cypress para obtener información sobre los comandos personalizados de Cypress.) Cuando un tiempo de espera expira, la prueba falla con un mensaje que indica que el tiempo de espera fue superado. 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 Interfaz Timeouts.)

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 prueba especificado y adaptar cómo desea ejecutar Watcher para satisfacer sus necesidades. Consulte Interfaz AxeConfiguration para más información.

cypressConfig

Crea una configuración para Cypress.

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

Parámetros cypressConfig

• config: Cypress.ConfigOptions & Configuration

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

Devoluciones: Cypress.ConfigOptions

Ejemplo cypressConfig

import { defineConfig } from 'cypress'
import { cypressConfig } from '@axe-core/watcher/cypress/config'

export default defineConfig(
  cypressConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

playwrightConfig

Crea una configuración para Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

Parámetros playwrightConfig

• opts: Configuration & LaunchOptions

  Tipo de intersección de LaunchOptions y Configuration.

Devoluciones: LaunchOptions

Ejemplo playwrightConfig

import { chromium } from 'playwright'
import { playwrightConfig } from '@axe-core/watcher/playwright'

const browserContext = await chromium.launchPersistentContext(
  '',
  playwrightConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

playwrightTest

Crea una configuración para Playwright Test.

playwrightTest(options: Options): ReturnValue

Parámetros playwrightTest

• options: Options

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

Devoluciones: ReturnValue

Ejemplo playwrightTest

// fixtures.ts
import { playwrightTest } from '@axe-core/watcher/playwright-test'

export default playwrightTest({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

puppeteerConfig

Crea una configuración para Puppeteer.

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

Parámetros puppeteerConfig

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

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

Devoluciones: Options

Ejemplo puppeteerConfig

import puppeteer from 'puppeteer'
import { puppeteerConfig } from '@axe-core/watcher/puppeteer'

const browser = await puppeteer.launch(
  puppeteerConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

wdioConfig

Crea una configuración de WebdriverIO.

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

Parámetros wdioConfig

• arg: Options

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

Devoluciones: RemoteOptions

Ejemplo wdioConfig

import { remote } from 'webdriverio'
import { wdioConfig } from '@axe-core/watcher/wdio'

const browser = await remote(
  wdioConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    },
    capabilities: { browserName: 'chrome' }
  })
)

wdioTestRunner

Crea una configuración de WebdriverIO Testrunner.

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

Parámetros wdioTestRunner

• params: unknown[]

  El valor params es uno de:

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

Devoluciones: Options.Testrunner

Ejemplo wdioTestRunner

import { wdioTestRunner } from '@axe-core/watcher/wdio'

export const config = wdioTestRunner({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

webdriverConfig

Crea una configuración de Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

Parámetros webdriverConfig

• arg: WebDriverArgs

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

Devoluciones: Options

webdriverConfig Ejemplo

import { Builder } from 'selenium-webdriver'
import { Options } from 'selenium-webdriver/chrome'
import { webdriverConfig } from '@axe-core/watcher/webdriver'

const options = new Options()
const browser = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(
    webdriverConfig({
      axe: {
        apiKey: process.env.API_KEY,
        projectId: process.env.PROJECT_ID
      },
      options
    })
  )
  .build()

Configuration Interfaz

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

Todos los funciones de configuración usan esta propiedad axe para permitirle configurar Watcher y configurar sus pruebas de accesibilidad. Vea la sección Interfaz AxeConfiguration arriba para más información.

ConfigurationOverrides Interfaz

La interfaz ConfigurationOverrides le permite anular la configuración global de la organización para ejecuciones de pruebas individuales. Esta propiedad debe usarse 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.

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA'
  }
}

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.

axe: {
  configurationOverrides: {
    axeCoreVersion: 'latest'
  }
}

bestPractices

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

axe: {
  configurationOverrides: {
    bestPractices: true
  }
}

experimentalRules

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

axe: {
  configurationOverrides: {
    experimentalRules: true
  }
}

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 Controller contiene los métodos para controlar el análisis de páginas. 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 haber ingresado valores en un formulario) y haber desactivado el análisis automático usando el método stop o configurando autoAnalyze en false.

analyze Retorna

Promise<void>

analyze Ejemplo

await controller.analyze()

analyze Comando equivalente de Cypress

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 Retorna

Promise<void>

flush Ejemplo

await controller.flush()

flush Comando equivalente de Cypress

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 Retorna

Promise<void>

start Ejemplo

await controller.start()

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 la página en busca de errores de accesibilidad.

stop Retorna

Promise<void>

stop Ejemplo

await controller.stop()

stop Comando equivalente de Cypress

cy.axeWatcherStop()

PlaywrightController

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

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

Constructor

new PlaywrightController(driver: Page): PlaywrightController

Parámetros

• driver: Page

El valor driver es un objeto Page de Playwright.

Retorna PlaywrightController

PlaywrightController Ejemplo

import { PlaywrightController, wrapPlaywrightPage } from '@axe-core/watcher/playwright'

let page = await browserContext.newPage()
const controller = new PlaywrightController(page)
page = wrapPlaywrightPage(page, controller)

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

PuppeteerController

La clase PuppeteerController permite el control manual de sus ejecuciones de prueba con Puppeteer. El control manual le permite proporcionar configuraciones adicionales requeridas por páginas web más complejas.

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

Constructor

new PuppeteerController(driver: Page): PuppeteerController

Parámetros

• driver: Page

El valor driver es un objeto Page de Puppeteer.

Retorna PuppeteerController

PuppeteerController Ejemplo

import { PuppeteerController, wrapPuppeteerPage } from '@axe-core/watcher/puppeteer'

let page = await browser.newPage()
const controller = new PuppeteerController(page)
page = wrapPuppeteerPage(page, controller)

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

WdioController

El WdioController le permite controlar manualmente las ejecuciones de prueba de WebdriverIO y WebdriverIO Testrunner. Para páginas que requieren configuración o ajustes adicionales, 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

Retorna WdioController

WdioController Ejemplo

import { WdioController, wrapWdio } from '@axe-core/watcher/wdio'

// browser is the WebdriverIO Browser instance from your wdioConfig() setup
const controller = new WdioController(browser)
wrapWdio(browser, controller)

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

WebdriverController

Constructor

new WebdriverController(driver: WebDriver): WebdriverController

Parámetros

• driver: WebDriver

El valor driver es un objeto WebDriver de Selenium.

Retorna WebdriverController

WebdriverController Ejemplo

import { WebdriverController, wrapWebdriver } from '@axe-core/watcher/webdriver'

// browser is the Selenium WebDriver instance from your webdriverConfig() setup
const controller = new WebdriverController(browser)
browser = wrapWebdriver(browser, controller)

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

Comandos Personalizados de Cypress

En la plataforma de automatización de navegadores Cypress, los métodos en las clases *Controller están implementados 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 de Cypress del 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/cypress/support')

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

Interfaz de Tiempos de Espera

El objeto objetivo de tiempo de espera (de tipo Tiempos de Espera) en el 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
}