Analizar iframes de origen cruzado

Axe Watcher analiza el contenido de elementos de <iframe> origen junto con el resto de la página. Los marcos servidos desde un origen diferente se omiten por defecto, y los problemas de accesibilidad dentro de ellos se excluyen por completo de sus resultados.

La opción allowedOrigins opta por analizar esos marcos. Usted nombra los orígenes que desea cubrir, y Watcher analiza los marcos servidos desde ellos como parte de cada análisis de la página de incrustación.

Esta opción requiere Watcher 4.6.0 o posterior, y está disponible con las integraciones de JavaScript/TypeScript y las integraciones de Java.

Cuándo Necesita Esto

Establezca allowedOrigins cuando partes significativas de su experiencia de usuario provengan de otro origen, como un formulario de pago alojado, un widget de reserva o programación incrustado, un reproductor multimedia con sus propios controles o un widget de ayuda o chat.

No lo necesita para marcos servidos desde su propio origen, los cuales siempre se analizan.

Configurar Orígenes Permitidos

Enumere solo los orígenes incrustados que desea cubrir. El origen de su propia aplicación siempre está permitido, así que no lo incluya.

JavaScript y TypeScript

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  allowedOrigins: [ 'https://pay.example.com' ]
}

Java

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setAllowedOrigins(new String[] {"https://pay.example.com"});
AxeWatcher watcher = new AxeWatcher(options);

Decida Qué Orígenes Confiar

La lista blanca se aplica en cada marco, no solo en el principal, y funciona en ambas direcciones: un marco acepta un mensaje solo de un origen en su propia lista, y responde solo a esos orígenes. En práctica, cada marco permite su propio origen, cada origen que enumere y, solo cuando el propio origen de ese marco es uno que enumeró, el origen del marco que lo incrusta directamente, siempre que ese incrustador sea la página principal o otro origen que haya enumerado.

Por lo tanto, enumerar un origen no lo autoriza a responder a cualquier página que lo incruste. Lo que autoriza es el intercambio de marcado entre ese marco y su incrustador dentro de la página en prueba, por lo que la lista debe estar limitada a las incrustaciones en las que confía.

Esta es también la razón por la cual no se admiten comodines y por la cual no hay una opción que signifique "analizar cada marco." Una lista blanca que no puede enumerar no es una lista blanca. Nombre cada origen explícitamente y mantenga la lista a las incrustaciones que realmente necesita cubrir.

Considere si la página en prueba muestra algo sensible mientras sus pruebas se ejecutan. Si sus fixtures de prueba utilizan datos personales o de pago realistas, sopeselo contra los orígenes de terceros que está a punto de permitir.

Escriba Correctamente los Orígenes

Cada entrada debe ser un origen y nada más: un esquema (http o https), un anfitrión y un puerto opcional. Watcher normaliza lo que proporciona eliminando una barra diagonal final y un puerto por defecto (:80 para http, :443 para https), poniendo en minúsculas al anfitrión y descartando duplicados.

Watcher rechaza una entrada que no puede usar reportando un error cuando se lee su configuración, en lugar de dejar que la prueba continúe y no analice nada. En Java, setAllowedOrigins() lanza IllegalArgumentException.

Dominios Que Contienen Caracteres No Ingleses

Un dominio que contiene caracteres fuera del alfabeto inglés, como café.example.com o пример.рф, tiene una segunda, equivalente ortografía compuesta solo por las letras a a z, los dígitos 0 a 9 y guiones. Esa ortografía se llama punycode, y siempre comienza con xn--. Los navegadores convierten un dominio a su forma punycode antes de usarlo, así que el punycode es la forma con la que Watcher compara.

Para encontrar la forma de punycode, visite la URL del marco y lea la barra de direcciones de su navegador después de que la página cargue, o utilice cualquier convertidor de punycode en línea.

No sustituya una ortografía inglesa de aspecto similar, como cafe.example.com por café.example.com. Watcher la acepta, porque es un origen válido, pero nunca coincide con el origen real del marco, por lo que el marco se deja sin analizar silenciosamente.

Las Palabras Clave <same_origin> y <unsafe_all_origins>

El motor de accesibilidad que Watcher utiliza, axe-core, acepta dos palabras clave en su propia configuración equivalente, y puede encontrarlas en la documentación de axe-core o en una configuración que esté migrando:

• <same_origin> significa "el origen propio de esta página." Watcher la acepta, pero no tiene efecto, porque su propio origen siempre está permitido.
• <unsafe_all_origins> significa "todos los orígenes, incluidos aquellos que no ha enumerado." Watcher la rechaza con un error, por las razones descritas en Decida Qué Orígenes Confiar.

Capturar Cambios Realizados Dentro de un Marco

El análisis automático detecta cambios en la página de nivel superior. No puede detectar un cambio hecho dentro un marco, ya sea que ese marco sea del mismo origen o de origen cruzado. Un marco permitido se analiza, por lo tanto, desde el último cambio a la página de nivel superior.

Esto importa cuando interactúa con contenido dentro de un marco. La interacción cambia el contenido del marco, la página de nivel superior permanece sin cambios, y por lo tanto no se ejecuta ningún análisis automático:

// Interacting inside the frame doesn't trigger an automatic analysis
await page.frameLocator('#pay').getByRole('button', { name: 'Continue' }).click()

// Analyze explicitly to capture the resulting state
await controller.analyze()

Llame a analyze() después de la interacción para capturar el estado resultante. Un análisis que solicite explícitamente siempre se ejecuta. Consulte Controle Sus Escaneos para saber cómo obtener un objeto controlador en su marco de prueba.

Encuentre los Marcos que Falta

Watcher informa sobre los marcos de origen cruzado que omitió, ya sea que hayas configurado allowedOrigins o no. Esto significa que puedes descubrir qué incrustaciones faltan en tus resultados antes de configurar nada.

El diagnóstico de cross_origin_frame_not_allowlisted nombra cada origen omitido e incluye la línea de allowedOrigins para pegar en tu configuración. En una página con muchas incrustaciones de terceros, la lista está limitada y el resto se resume como "y N más".

Los diagnósticos solo aparecen en la salida de depuración, y cada uno se informa como máximo una vez por ejecución de prueba.

JavaScript y TypeScript: establece la variable de entorno DEBUG cuando ejecutas tus pruebas.

DEBUG=axe-watcher:* npx playwright test

Java: los controladores registran cada diagnóstico al nivel DEBUG, por lo que configura tu marco de registro para mostrar los mensajes DEBUG para Axe Watcher. Con la integración de Selenium, también puedes llamar a enableDebugLogger() en AxeWatcher.

Otros dos diagnósticos informan sobre marcos que fueron permitidos pero que aún no se analizaron. Ambos se describen en Limitaciones:

• cross_origin_frame_unscannable, para un marco sancionado sin allow-same-origin.
• cross_origin_frame_timed_out, para un marco que no devolvió resultados a tiempo.

Si prefieres que la cobertura de marcos aparezca en tus resultados en lugar de en la salida de depuración, habilita mejores prácticas. La regla frame-tested de axe-core distingue "no hay problemas en este marco" de "este marco nunca fue analizado": un marco que Watcher no pudo alcanzar se informa como necesitando revisión. Porque es una regla de mejor práctica, un conjunto de reglas limitado a las reglas de WCAG lo omite.

Los problemas encontrados dentro de un marco se atribuyen al estado de página de la página que incrusta el marco, no a un estado de página separado propio.

Limitaciones

La limitación que es más probable que encuentres es que el análisis automático no puede ver los cambios realizados dentro de un marco, descrita en Capturar cambios realizados dentro de un marco. El resto están a continuación.

Un marco sancionado necesita allow-same-origin

Un marco cuyo atributo sandbox omite allow-same-origin tiene un origen opaco, que ninguna entrada de lista de permitidos puede nombrar, por lo que no puede ser analizado sin importar lo que listes. Una vez que listes su origen, Watcher lo informa con el diagnóstico cross_origin_frame_unscannable. Hasta que lo hagas, se informa como cross_origin_frame_not_allowlisted al igual que cualquier otro marco omitido. Agrega allow-same-origin al atributo sandbox para analizar el marco.

Solo allow-same-origin importa aquí. Un marco sancionado que omite allow-scripts todavía se analiza normalmente, porque el script de contenido de Watcher se ejecuta en un mundo aislado y se ejecuta incluso donde los propios scripts de la página están bloqueados.

Incrustaciones que redirigen

Una incrustación cuyo src redirige a otro origen, como un dominio apex que redirige a www o http redirigiendo a https, termina en un origen que no es el que listaste, por lo que no se analiza. Lista el origen en el que el marco realmente termina en lugar del que tiene en su src.

Marcos anidados más de un nivel profundo no se informan

Los diagnósticos de cobertura de marcos se informan desde la página de nivel superior, sobre los marcos que incrusta directamente. Un marco que no pudo ser alcanzado pero está anidado dos o más niveles profundos no aparecerá en tu salida de depuración, aunque su contenido falte en los resultados.

Un marco que nunca responde falla en el análisis

Un marco que responde al ping inicial de Watcher pero nunca devuelve resultados falla en el análisis directamente en lugar de subinformarlo, y Watcher informa el diagnóstico cross_origin_frame_timed_out. Si una incrustación de terceros lenta hace esto, elimina su origen de allowedOrigins o aumenta runOptions.frameWaitTime.

Presupuesto para análisis más lento

Cada origen que permites agrega todo el contenido de ese marco a cada análisis de la página. El contenido del marco se recopila, se transfiere a la página de nivel superior y se combina con el resto de los resultados, y todo eso ocurre mientras tu prueba espera.

Cuánto tiempo agrega esto crece con el tamaño y la complejidad del contenido del marco, y con el número de marcos que permites. Con el análisis automático habilitado, el costo se repite en cada interacción que analiza Watcher, por lo que una suite de pruebas larga con varios marcos permitidos puede agregar una cantidad sustancial de tiempo a una ejecución. Dos formas de mantenerlo manejable:

• Limita allowedOrigins a las incrustaciones que realmente necesitas cubrir, en lugar de cada origen de terceros en la página.
• Considera habilitarlo por proyecto o por suite de pruebas, para que las suites que no ejercen contenido enmarcado no paguen por ello.

Si deseas medir el efecto en tu propia suite, mide una ejecución representativa antes y después de habilitar la opción.

Tiempos de espera

Debido a que analizar un marco de origen cruzado incluye esperar a que ese marco responda, los tiempos de espera predeterminados de analyze y flush cambian de 5000ms a 10000ms cuando allowedOrigins se establece en un array no vacío. Los valores predeterminados de start y stop no cambian. Los valores de tiempo de espera que establezcas tú mismo siempre se utilizan tal como se dan, por lo que esto solo afecta a los valores predeterminados. Ve Establecer tiempos de espera.

Esto se aplica a las integraciones de JavaScript y TypeScript. Actualmente, Java Watcher no admite tiempos de espera personalizados, y sus valores de tiempo de espera no cambian con esta opción.

Si estableces tus propios tiempos de espera y luego habilitas allowedOrigins, revísalos. Un valor ajustado para una página sin contenido enmarcado puede ahora ser demasiado ajustado.

Temas relacionados

• Establecer tiempos de espera
• Controla tus escaneos
• Mejores prácticas
• Solución de problemas
• Referencia de API para la versión de JavaScript y TypeScript de Watcher
• Opciones de AxeWatcher