Solución de Problemas
Problemas comunes y soluciones con Axe Watcher
Watcher solo es compatible con Chrome para Pruebas, Chromium o Microsoft Edge
Aunque el sitio web de Axe Developer Hub es compatible con varios navegadores, el paquete Watcher solo es compatible con Google Chrome para Pruebas, Chromium o Microsoft Edge (JavaScript/TypeScript o Java con Playwright). Problemas que podrías encontrar:
- Si usas la versión 139 de Chrome o posterior, recibirás un error de Watcher. Usa Chrome for Testing o Chromium en su lugar (con JavaScript/TypeScript o Java con Playwright, también puedes usar Microsoft Edge).
- Si usas el navegador Electron de Cypress, recibirás un error. Especifica el navegador como Chrome para Pruebas, Chromium o Microsoft Edge cuando invoques Cypress; de lo contrario, el valor predeterminado será el navegador Electron. Consulta Iniciando Navegadores en la documentación de Cypress para obtener más información.
Si usas WebdriverIO o WebDriverJS, debes configurar tu entorno de prueba para usar Chrome for Testing o Microsoft Edge explícitamente. Si usas Java Selenium, debes configurar tu entorno de prueba para usar Chrome for Testing explícitamente. Consulta Usar Chrome para Pruebas para obtener pasos de instalación y ejemplos de configuración específicos de la plataforma.
Consulta Plataformas de Pruebas Automatizadas para obtener más información sobre el software compatible con Watcher.
Resultados Incompletos
Si tu suite de pruebas utiliza múltiples ejecuciones de pruebas en paralelo y utiliza el mismo ID de compilación no nulo, los resultados de cada ejecución de pruebas reemplazarán a los de otras ejecuciones para el mismo SHA de commit de Git, dando resultados incompletos. Debes asegurarte de que cada ejecución de pruebas use el mismo ID de compilación no nulo.
Normalmente estableces el ID de compilación en tu AxeConfiguration.
Para obtener más información sobre el uso de runners de prueba paralelos con diferentes plataformas CI/CD, consulta Ejecución de Pruebas en Paralelo.
Errores de Accesibilidad Duplicados o Conteo de Nuevos Problemas Incorrecto
Si tu sitio web usa IDs dinámicos o nombres de clase que cambian cada vez que se actualiza la página, probablemente veas errores de accesibilidad duplicados, especialmente problemas marcados como nuevos cuando ejecuciones de prueba anteriores muestran el mismo problema en el mismo elemento. (Axe Developer Hub utiliza IDs y clases para identificar el mismo elemento entre ejecuciones de prueba). Para resolver este problema, debes establecer la propiedad ancestry en el objeto runOptions en tu configuración a true. El ejemplo a continuación muestra cómo establecer la opción en tu configuración:
axe: {
runOptions: {
ancestry: true
}
}Consulta Uso de Selectores Dinámicos para obtener más orientación sobre el uso de selectores dinámicos.
Consulta (JavaScript/TypeScript) runOptions o (Java) AxeWatcherOptions.setRunOptions() para obtener más información.
Versión antigua de @axe-core/watcher
Si estás usando la versión 3.18.0 o anterior de @axe-core/watcher, recibirás este mensaje de advertencia:
El Axe Developer Hub ahora se adhiere a la configuración definida en Configuración de Axe, y las ejecuciones de prueba creadas por versiones de @axe-core/watcher versión 3.18.0 o anteriores generan sesiones que no estaban al tanto de la configuración global en Configuración de Axe. Deberías actualizar tu paquete @axe-core/watcher y volver a ejecutar tus pruebas para crear sesiones que sigan la Configuración de Axe de tu empresa. Consulta Uso de configuraciones globales.
No se Capturan Estados de Página Después de Cambiar a un Marco Hijo
Si tu prueba cambia el contexto actual del navegador a un marco hijo usando switchToFrame() (WebdriverIO o WebDriverJS) o switchTo().frame() (Java Selenium), Axe Watcher no capturará los estados de la página para ninguna acción realizada mientras el navegador se centra en el marco hijo. Axe Watcher solo puede analizar el marco de nivel superior.
Por ejemplo, en WebdriverIO, la llamada click() a continuación no producirá un estado de página:
await browser.url('https://example.com')
const iframe = await browser.$('iframe')
await browser.switchToFrame(iframe)
// Actions taken in the child frame will not be analyzed
await button.click()Para reanudar la captura de estados de página, cambie de nuevo al marco de nivel superior antes de continuar:
// WebdriverIO
await browser.switchToParentFrame()
// WebDriverJS / Java Selenium
await driver.switchTo().defaultContent()Cypress no se ve afectado por esta limitación.
Estado de Página Extra Generado por cy.screenshot()
Si llamas a cy.screenshot() en tus pruebas de Cypress, Axe Watcher puede generar un estado de página extra. Cuando Cypress toma una captura de pantalla, modifica brevemente el DOM para desactivar animaciones, y el observador de DOM de Axe Watcher puede detectar esa modificación como un cambio de estado de página. Este es un comportamiento esperado y no afecta la precisión de tus resultados de accesibilidad.
Método del controlador agotando el tiempo
Java Watcher actualmente no te permite cambiar los valores de tiempo de espera.
(Solo JavaScript o TypeScript) Recibirás un mensaje similar al siguiente si las llamadas a métodos del controlador (definido en la clase base abstracta Controller como analyze(), flush(), start() y stop()) o comandos personalizados de Cypress se agotan:
Error: Watcher could not send results to the server. To resolve this problem, adjust your `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/wa-troubleshooting for more troubleshooting.El método especificado Controller (aquí, el método flush()) requirió más tiempo del predeterminado para completarse y se agotó el tiempo. Puedes cambiar el tiempo predeterminado agregando un objeto timeout a tu configuración:
axe: {
timeout: {
flush: 10000
}
}Estos valores de tiempo de espera son independientes del marco de pruebas que estés utilizando, y también podrías necesitar aumentar los valores de tiempo de espera para ese marco.
Consulta Configurar tiempos de espera para obtener información sobre el uso de tiempos de espera.
Consulta Interfaz Timeouts y timeouts para obtener más información. Los valores predeterminados de tiempo de espera se muestran en la tabla en la sección de Interfaz Timeouts.
Resultados no aparecen
Si has ejecutado tu suite de pruebas y no aparecen resultados en Axe Developer Hub para un proyecto específico, la causa podría encontrarse entre las razones en las siguientes secciones:
No Configurar Axe Watcher
Tu suite de pruebas modificada debe llamar al función de configuración apropiado para tu marco de pruebas antes de ejecutar tus pruebas. Si no configuras correctamente Axe Watcher, recibirás un mensaje indicando que necesitas configurar Axe Watcher. Por ejemplo, si olvidas configurar Axe Watcher con Cypress, verás este mensaje cuando ejecutes tu suite de pruebas:
Cypress is not configured for axe Watcher. Please ensure that axe Watcher's cypressConfig() is invoked within Cypress's defineConfig() in your cypress.config.js. All tests will fail with this error.Consulta la instrucciones de configuración para ejemplos de configuración para tu lenguaje y marco de prueba de navegador.
No vaciar resultados
Necesitas llamar a la función flush() (o el comando personalizado axeWatcherFlush() en Cypress) para enviar los resultados recopilados a los servidores de Deque para que los resultados puedan presentarse en el sitio web de Axe Developer Hub. Normalmente, llamas a la función flush() en el hook de limpieza de tu plataforma de automatización.
Por ejemplo, en el archivo support/e2e.js en Cypress, debes agregar la llamada a afterEach():
// Flush axe-watcher results after each test.
afterEach(() => {
cy.axeWatcherFlush()
})Usando la opción --incognito
No puedes usar la opción de línea de comando --incognito con Chrome; de lo contrario, tus pruebas fallarán sin notificación. Si estás usando el modo incógnito para evitar escribir archivos en caché en el disco (los archivos en caché se mantienen solo en memoria en el modo incógnito), utiliza los métodos de caché de tu suite de pruebas en su lugar.
No configurar las variables de entorno requeridas
Si estás experimentando con los ejemplos en el repositorio de watcher-examples en GitHub, ten en cuenta que los ejemplos usan variables de entorno para establecer la clave de API y el ID de proyecto, API_KEY y PROJECT_ID.
Prueba ejecutándose demasiado rápido
Tus pruebas podrían ejecutarse demasiado rápido, descargando la página y liberando sus recursos antes de que Watcher pueda analizarla. Para solucionar este problema, puedes agregar un retraso al final de la prueba para permitir tiempo para analizar la página.
Por ejemplo, en Cypress, puedes agregar un retraso de 10 segundos (10,000 milisegundos) con el método cy.wait():
describe('Visitor', () => {
it('should visit example.com', () => {
cy.visit('https://www.example.com')
cy.wait(10000); })
})Clave API faltante o inválida
Una clave de API inválida o faltante aparece como un archivo de configuración inválido en Cypress. El seguimiento de pila revelará si es inválida o falta. Una clave faltante resulta en lo siguiente:
AssertionError [ERR_ASSERTION]: API key is required
at validateApiKey ...(Se eliminaron muchas líneas del seguimiento de pila para mayor brevedad.)
Una clave inválida resulta en el siguiente seguimiento de pila (acortado):
Error: Server responded to https://axe.deque.com/api/api-keys/test/validate/axe-devtools-watcher with status code 404:
{"error":"Invalid API key"}
at Response.getBody
...Ayuda
Si no puedes resolver tu problema, por favor envíanos un correo electrónico para que podamos ayudarte.