Uso de Selectores Dinámicos

Cuando se prueban páginas que generan IDs de elementos o nombres de clase dinámicos en cada carga de página, Axe Watcher puede tener dificultades para rastrear si los problemas de accesibilidad son duplicados a lo largo de las ejecuciones de prueba. Este artículo explica cómo configurar Watcher para manejar estos escenarios correctamente. Un URL dinámico causa el mismo síntoma por una razón diferente y necesita una solución distinta, que se cubre en URLs dinámicas a continuación.

El Problema con los Selectores Dinámicos

Por defecto, Axe Watcher utiliza selectores CSS que incluyen IDs de elementos y clases para identificar dónde ocurren los problemas de accesibilidad. Por ejemplo, un problema podría reportarse en:

iframe#main-iframe

Este enfoque funciona bien cuando los IDs y las clases de su página permanecen consistentes entre cargas de página. Sin embargo, muchas aplicaciones web modernas generan identificadores dinámicos que cambian en cada renderizado de página, como:

• #component-a1b2c3d4
• .form-field-xyz789

Axe Watcher también envía un XPath para cada elemento, y Axe Developer Hub trata una coincidencia en cualquiera de los selectores como el mismo elemento. Dado que un XPath nunca incluye nombres de clase, con frecuencia una página cuyos nombres de clase son únicamente dinámicos se rastrea correctamente sin necesidad de más configuración. Sin embargo, un XPath incluye el ID de un elemento cuando ese ID es único en la página, produciendo una ruta como //div[@id='component-a1b2c3d4']. Un ID dinámico por lo tanto cambia tanto el selector CSS como el XPath, dejando nada estable en lo que coincidir.

Cuando los identificadores cambian entre ejecuciones de prueba de esta manera, Axe Watcher no puede determinar si un problema es un duplicado de un problema detectado previamente o una nueva ocurrencia. Esto puede resultar en:

• El mismo problema siendo reportado como "nuevo" y "resuelto" en cada ejecución de prueba
• Registro inexacto de su progreso en accesibilidad a lo largo del tiempo
• Dificultad para identificar qué problemas se han resuelto realmente

La Solución: Activar el Seguimiento de Ancestría

To handle dynamic selectors, set the ancestry option to true in your runOptions configuration. When enabled, Axe Watcher uses the element's position within the DOM tree rather than relying on IDs and classes to locate elements between test runs.

Con ancestry habilitado, un selector que anteriormente se veía así:

iframe#main-iframe

En su lugar incluirá la ruta completa desde el elemento raíz:

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

Este selector posicional permanece consistente a través de las cargas de página, incluso cuando los IDs y las clases cambian, permitiendo que Axe Watcher rastree con precisión los problemas duplicados.

Ejemplos de Configuración

JavaScript y TypeScript

Agregue la opción ancestry a la runOptions de su configuración de axe:

const config = {
  axe: {
    apiKey: process.env.ACCESSIBILITY_API_KEY,
    projectId: process.env.PROJECT_ID,
    runOptions: {
      ancestry: true
    }
  }
}

Java

Use el método setAncestry() en su objeto AxeRunOptions:

AxeRunOptions runOptions = new AxeRunOptions()
    .setAncestry(true);

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setRunOptions(runOptions);

AxeWatcher watcher = new AxeWatcher(options);

Cuándo Usar el Seguimiento de Ancestría

Habilite ancestry: true cuando su aplicación:

• Utilice frameworks que generen IDs de componentes dinámicos (React, Vue, Angular)
• Emplee bibliotecas CSS-in-JS que generen nombres de clase únicos
• Tenga campos de formulario o elementos interactivos con identificadores autogenerados
• Muestre conteos inconsistentes de "nuevo problema" y "problema resuelto" entre ejecuciones de prueba para lo que parecen ser los mismos problemas

Compromisos a Considerar

Aunque el seguimiento de ancestría soluciona el problema del selector dinámico, hay algunas consideraciones:

• Legibilidad de selectores: Los selectores posicionales son más largos y pueden ser más difíciles de leer al revisar problemas en Axe Developer Hub.
• Sensibilidad a la estructura del DOM: Si la estructura del DOM de su página cambia significativamente entre renderizados (no solo los IDs/clases), los selectores posicionales también pueden cambiar.
• Depuración: Al investigar un problema, puede resultarle más fácil localizar un elemento por un ID significativo que por su posición en el árbol DOM.

Para la mayoría de las aplicaciones con identificadores dinámicos, los beneficios de un seguimiento preciso de problemas superan estos compromisos.

URLs dinámicas

Los selectores de elementos son solo parte de cómo Axe Developer Hub identifica un problema. La URL de la página también se compara, en su totalidad, incluyendo cualquier cadena de consulta. Activar ancestry no tiene efecto en esta comparación.

Un URL que varía entre ejecuciones de prueba, por lo tanto, produce los mismos síntomas que un selector dinámico, y lo hace de manera más agresiva: cuando no se ha visto antes un URL, cada problema encontrado en él se informa como nuevo, sin que se consulten los selectores de elementos en absoluto. Las causas comunes incluyen:

• IDs de sesión o tokens de autenticación incluidos en la cadena de consulta
• Marcas de tiempo o parámetros de descarga de caché, como ?v=1738012800
• IDs aleatorios en la ruta, como /orders/8f3c1b2a/summary
• Datos de prueba que generan un registro nuevo, y por lo tanto un URL nuevo, en cada ejecución

No hay una opción de configuración que normalice las URLs antes de que se comparen, por lo que esto tiene que resolverse en su suite de pruebas: navegue a URLs deterministas, para que la misma página produzca la misma URL en cada ejecución. En la práctica, esto generalmente significa usar datos de prueba fijos en vez de generar nuevos registros por ejecución, y eliminar o fijar los parámetros de consulta volátiles antes de que la página sea escaneada.

Si un URL realmente no puede ser estabilizado, puedes mantenerlo fuera de tus resultados por completo con excludeUrlPatterns, aunque esto significa que la página no se escanea en absoluto en lugar de rastrearse correctamente. Consulta Excluir URLs del análisis para más detalles.

Ver también

• Referencia API para JavaScript y TypeScript Documentación completa para runOptions y otras opciones de configuración
• Referencia API de Java para opciones de tiempo de ejecución Clase AxeRunOptions
• Entendiendo cómo Axe Developer Hub identifica problemas duplicados Glosario: Duplicado