Solución de Problemas

Watcher solo es compatible con Chrome para Pruebas, Chromium o Microsoft Edge

Aunque el sitio web de Axe Developer Hub admite varios navegadores, el paquete Watcher solo es compatible con Google Chrome para Pruebas, Chromium o Microsoft Edge. Problemas que podrías encontrar:

• Si usas Google Chrome versión 139 o posterior, recibirás un error de Watcher. En su lugar, utiliza Chrome para Testing, Chromium o 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, WebDriverJS o Java Selenium, debes configurar tu entorno de pruebas para usar explícitamente Chrome para Testing o Microsoft Edge. Consulta Usar Chrome para Pruebas para los 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.

Microsoft Edge falla con Java Selenium

Si tus pruebas de Java Selenium arrojan un IllegalStateException con el mensaje El soporte de Microsoft Edge requiere Selenium 4 o superior, tu proyecto está utilizando Selenium 3. El EdgeOptions de Selenium 3 está dirigido al navegador legado EdgeHTML, el cual Axe Watcher no soporta. Actualiza selenium-java a la versión 4.x para probar en Microsoft Edge, o sigue probando en Chrome for Testing o Chromium con ChromeOptions y ChromeDriver, que la integración de Java Selenium soporta en Selenium 3.141.59 y versiones posteriores.

Sin Resultados de Microsoft Edge con WebdriverIO

Si tus pruebas de WebdriverIO se ejecutan en Microsoft Edge, se completan sin error y no producen resultados en Axe Developer Hub, verifica tu versión de Watcher. Usar Microsoft Edge con WebdriverIO requiere Watcher 4.6.0 o posterior.

En versiones anteriores, Watcher enviaba sus opciones de navegador a la capacidad goog:chromeOptions. El Microsoft Edge WebDriver las lee desde ms:edgeOptions en su lugar, por lo que las opciones fueron ignoradas y no se realizó ningún análisis. Nada falló, por lo que las pruebas pasaron con un conjunto de resultados vacío. Actualiza a la versión 4.6.0 o posterior para resolver el problema.

La Propiedad args de una Capacidad de Navegador No Es Válida

Si Watcher informa que la propiedad args de tu capacidad de navegador goog:chromeOptions o ms:edgeOptions debe ser un arreglo de cadenas, configura args como un arreglo de banderas de línea de comando del navegador, o elimínalo:

capabilities: {
  browserName: 'MicrosoftEdge',
  'ms:edgeOptions': {
    args: ['--window-size=1280,720']
  }
}

Se rechazan valores como una sola cadena, un objeto o un arreglo que contenga algo distinto a una cadena. Watcher 4.5.0 y versiones anteriores aceptaban algunos de estos y fallaban más tarde con un error no relacionado.

Problemas de Accesibilidad Dentro de un Iframe de Origen Cruzado No Aparecen

Si tu análisis se completa con éxito pero tus resultados no contienen nada de un <iframe> servido desde un origen diferente al de la página en prueba, ese marco no fue analizado. Watcher siempre analiza marcos del mismo origen, pero analiza un marco de origen cruzado solo cuando enumeras el origen de ese marco:

• (JavaScript o TypeScript) allowedOrigins
• (Java) setAllowedOrigins()

axe: {
  allowedOrigins: [ 'https://pay.example.com' ]
}

No incluyas el origen de tu propia aplicación, que siempre está permitido.

Para confirmar qué orígenes fueron omitidos, busca el diagnóstico cross_origin_frame_not_allowlisted. Se informa ya sea que hayas configurado la opción o no, nombra los orígenes de cruce de origen que no fueron analizados y muestra la línea de configuración que puedes pegar. Los diagnósticos aparecen solo en la salida de depuración: configura DEBUG=axe-watcher:* cuando ejecutes tus pruebas (JavaScript o TypeScript), o configura tu marco de registro para mostrar mensajes de DEBUG para Axe Watcher (Java). Con la integración de Java Selenium, también puedes activar el registro de depuración con enableDebugLogger().

Si aún faltan resultados después de enumerar el origen:

• El marco tiene un atributo sandbox que omite allow-same-origin, reportado como cross_origin_frame_unscannable. Luego, el marco tiene un origen opaco que ninguna entrada en tu lista puede nombrar. Agrega allow-same-origin al atributo sandbox.
• El marco redirige lejos del origen en su src, como un dominio apex redirigiendo a www, o http redirigiendo a https. Enumera el origen al que realmente termina el marco.
• El marco está anidado a más de un nivel de profundidad. Los diagnósticos de cobertura se informan desde la página de nivel superior sobre los marcos que incrusta directamente, por lo que un marco profundamente anidado no se reporta.

Si el análisis falla por completo en lugar de subinformar, busca el diagnóstico cross_origin_frame_timed_out: un marco respondió el ping inicial de Watcher pero no devolvió resultados a tiempo. Ya sea elimina ese origen de tu lista o aumenta runOptions.frameWaitTime.

Si el marco es analizado pero sus resultados no reflejan lo que hizo tu prueba dentro de él, el análisis automático es la causa. No puede detectar cambios realizados dentro de un marco, por lo que un marco permitido se analiza tal como estaba en el último cambio de la página de nivel superior. Llama a analyze() tú mismo después de interactuar con contenido dentro de un marco. Este es un problema separado de No se Capturan Estados de Página Después de Cambiar a un Marco Hijo, que se aplica cuando el contexto del navegador se cambia al marco.

Consulta Analizar iframes de Origen Cruzado para obtener la imagen completa.

Orígenes Rechazados por allowedOrigins

Si Watcher informa que una entrada allowedOrigins no es válida, la entrada no es un origen simple que se pueda comparar con un marco. Cada entrada necesita un esquema (http o https), un host y un puerto opcional, sin nada más. Causas comunes:

• Un comodín, como https://*.example.com. Nombra cada origen explícitamente.
• Una ruta, cadena de consulta, fragmento o credenciales, como https://pay.example.com/checkout.
• Un esquema faltante, como pay.example.com.
• Un esquema distinto de http o https.
• Un dominio que contiene caracteres fuera del alfabeto inglés, como café.example.com. Usa la forma punycode en su lugar.

Watcher rechaza estos en lugar de ignorarlos, porque una entrada que no coincide con el verdadero origen de un marco dejaría el marco sin analizar mientras tu ejecución de prueba aún reporta éxito. Consulta Analizar iframes de Origen Cruzado.

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 utiliza IDs dinámicos que cambian cada vez que se actualiza la página, es probable que veas errores de accesibilidad duplicados, en particular problemas marcados como nuevos cuando ejecuciones de prueba anteriores exhiben el mismo problema en el mismo elemento. (Axe Developer Hub identifica el mismo elemento entre ejecuciones de prueba por su selector CSS y su XPath, ambos de los cuales incorporan el ID del elemento). 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.

Si tus conteos de problemas siguen siendo incorrectos después de habilitar ancestry, verifica si las URLs que tus pruebas visitan cambian entre ejecuciones. La URL se compara en su totalidad, incluyendo cualquier cadena de consulta, por lo que un ID de sesión o un parámetro para evadir caché hace que cada problema en la página parezca nuevo. Consulta URLs dinámicas.

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 utilizando switchToFrame() (WebdriverIO o WebDriverJS) o switchTo().frame() (Java Selenium), Axe Watcher no capturará los estados de la página para ninguna acción tomada mientras el navegador está enfocado en el marco hijo. Axe Watcher captura los estados de la página solo mientras el contexto del navegador está en el marco de nivel superior.

Este es un asunto separado de si el iframe contenido se analiza. Watcher analiza marcos de mismo origen, y marcos de origen cruzado cuyo origen enumeras; consulta Analizar iframes de Origen Cruzado.

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()

El método de setContent() de Playwright no es compatible

Axe Watcher no es compatible con pruebas que llamen a los métodos de page.setContent() o frame.setContent() de Playwright. Esta limitación se aplica tanto al paquete de JavaScript/TypeScript como a la biblioteca de Java.

Estos métodos reemplazan todo el documento, utilizando internamente document.write(), lo que descarta el contexto del que Axe Watcher depende para analizar la página. Axe Watcher analiza la página exitosamente hasta el punto de la llamada, pero después de esto, Axe Watcher ya no puede analizar la página ni enviar sus resultados, y su prueba falla con mensajes de tiempo de espera similares a los siguientes:

Error: Watcher timed out before it could finish analyzing the page state. To resolve this problem, increase the `timeout.analyze` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.

Error: Watcher timed out sending results to the server. To resolve this problem, increase the `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.

En lugar de establecer el marcado directamente, sírvalo desde una URL y navegue a ella con page.goto() para que el navegador cargue el documento normalmente:

// Not supported by Axe Watcher:
await page.setContent('<my-button disabled></my-button>')

// Navigate to a URL that serves the same markup instead:
await page.goto('http://localhost:6006/my-button.html')

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

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

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.