Herramienta de Análisis

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

La herramienta analyze realiza un análisis exhaustivo de accesibilidad en páginas web ejecutando un escaneo a través de la extensión Axe DevTools para navegadores en un entorno real. Funciona perfectamente con URL de desarrollo local (por ejemplo, localhost:3000) y URL de producción remotas.

Qué Hace

  1. Autenticación - Valida las credenciales del usuario (ya sea una clave API o un token de acceso OAuth 2.0) para asegurar el acceso autorizado
  2. Recuperación de Configuración - Obtiene la configuración específica de la organización del usuario Configuración de Axe, incluyendo:
    • Estándar de Pruebas de Accesibilidad (por ejemplo, WCAG 2.2 AA)
    • versión de axe-core
    • Necesita revisión / mejores prácticas
    • Reglas Avanzadas predefinido
  3. Análisis Basado en Navegador - Inicializa una instancia del navegador en segundo plano con la extensión Axe DevTools montada
  4. Navegación de Página - Navega a la URL proporcionada por el usuario en su solicitud al agente de IA
  5. Escaneo de Accesibilidad - Realiza un análisis completo de accesibilidad en la página renderizado usando la extensión Axe DevTools para navegadores, asegurando que se pruebe la experiencia real del usuario (no solo el HTML estático)
  6. Entrega de Resultados - Devuelve los resultados de análisis completos al agente en un formato estructurado

Pruebas de Respuesta

La herramienta analyze admite parámetros opcionales viewportWidth y viewportHeight, permitiéndole probar páginas en dimensiones de pantalla específicas. Esto es útil para detectar problemas de accesibilidad que solo aparecen en ciertos tamaños de pantalla, como puntos de interrupción para móviles o tabletas.

Analyze http://localhost:3000 for accessibility issues at a mobile viewport of 375x812

Cuando ambos parámetros se omiten, el escaneo se realiza a 1000×1080. Pasar solo viewportWidth predetermina la altura a 1080; viewportHeight requiere que se establezca viewportWidth. Cualquiera de las dimensiones puede tener hasta 7680 píxeles.

Escaneos Parciales de Página

De forma predeterminada, la herramienta analyze escanea toda la página. Para delimitar el escaneo a una región específica, pase el parámetro opcional selector, útil para enfocarse en un solo componente o excluir partes ruidosas y no relacionadas de la página de los resultados.

  • Una sola cadena de selector CSS apunta a un elemento en el marco superior:

    {
  "url": "http://localhost:3000",
  "selector": "#main"
}

  • Una matriz de selectores CSS atraviesa las fronteras de iframe o shadow-DOM — cada segmento selecciona el host para el siguiente. Use una matriz solo cuando el objetivo se encuentre dentro de un iframe o raíz de sombra:

    {
  "url": "http://localhost:3000",
  "selector": ["iframe#checkout", "#payment-form"]
}

Una matriz admite hasta 10 segmentos. Si el selector no coincide con ningún elemento en la página, el escaneo devuelve un error. Cuando se omite selector, se escanea toda la página.

Indique a su agente de IA en lenguaje natural; el agente traduce su intención en la llamada a la herramienta:

Scan only the #main region of http://localhost:3000 for accessibility issues

Interacciones del Navegador Antes de Escanear

La herramienta analyze admite una matriz opcional before de pasos de interacción que se ejecutan después de que la página carga pero antes del escaneo de accesibilidad. Esto desbloquea varios escenarios de prueba en el mundo real:

  • Páginas con inicio de sesión — complete las credenciales y envíe antes de escanear la página posterior al inicio de sesión
  • Banners de cookies/consentimiento — cierre los banners que de otro modo superpondrían o bloquearían el contenido de la página
  • Contenido dinámico — espera a que aparezca el contenido renderizado por el cliente (cambios de ruta, DOM inyectado tarde) antes de escanear

Los pasos se ejecutan en orden de la matriz, en el mismo contexto del navegador que el escaneo, por lo que las cookies, localStorage, y cualquier cambio de ruta desencadenado por click o fill persisten en el escaneo.

La matriz before admite hasta 20 pasos. Cada paso tiene su propio tiempo de espera de BROWSER_TIMEOUT_MS (predeterminado 30000 ms); no hay una anulación por paso.

Acciones Soportadas

Acción Campos obligatorios Campos opcionales Propósito
click selector Haga clic en el elemento que coincida con el CSS selector (por ejemplo, un botón de enviar, un botón de "Descartar" en un banner).
fill selector, value Rellene un campo de entrada que coincida con selector con value. Úselo para credenciales, consultas de búsqueda o campos de formulario. Una cadena vacía limpia el campo.
waitFor selector state — uno de "visible" (por defecto), "attached", "hidden", "detached" Espere a que el elemento que coincida con selector alcance state. Úselo para condicionar el siguiente paso o el propio escaneo. Elija un selector que exista solo en el estado posterior a la interacción (por ejemplo, un botón de cierre de sesión o el encabezado del panel) — los selectores genéricos como body o #app ya existen antes de la interacción y se resuelven instantáneamente, por lo que no condicionarán nada.
wait ms Pausa durante ms milisegundos (1–5000), luego continúa. Use solo cuando no haya nada en la página que indique que está lista — una transición CSS finalizando, un temporizador de rebote activándose, un lienzo dibujándose. Si un elemento aparece o cambia, use waitFor en su lugar: es más rápido y no adivina. Requiere la versión v1.5.0 o posterior.
tip

Prefiera waitFor sobre wait. Una pausa fija espera más de lo necesario o no lo suficiente, y ralentiza cada escaneo por su duración completa. El total de todos los pasos wait en un array de before está limitado a 10000 ms; una solicitud que supere el límite será rechazada. La pausa se suma al breve asentamiento automático después de cada interacción; no lo reemplaza.

Ejemplo: Iniciar sesión antes de escanear

Indique a su agente de IA en lenguaje natural; el agente traduce su intención en la llamada a la herramienta:

Analyze http://localhost:3000 for accessibility issues. Before running
the analysis, fill in the #username and #password fields with USERNAME
and PASSWORD from ./.env.local, click the button[type=submit] button,
and wait for #main-content to appear.

El agente resuelve el mensaje y llama a la herramienta analyze con un payload similar a:

{
  "url": "http://localhost:3000",
  "before": [
    {
      "action": "fill",
      "selector": "#username",
      "value": "<resolved-from-.env.local>"
    },
    {
      "action": "fill",
      "selector": "#password",
      "value": "<resolved-from-.env.local>"
    },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "waitFor", "selector": "#main-content" }
  ]
}
important

fill.value se trata como sensible. El servidor Axe MCP nunca registra fill.value, nunca lo muestra en mensajes de error, y nunca lo envía a la telemetría. Use fill para cualquier entrada proporcionada por el usuario o secreta (contraseñas, tokens de API, etc.) para que los secretos permanezcan redactados en todo el pipeline — y nunca incruste valores sensibles en un selector, que lo hace aparecen en registros y mensajes de error.

note

El agente resuelve value, no el servidor. El servidor Axe MCP trata a value como una cadena literal — no no lee archivos, expande variables de entorno, o interpreta la sintaxis de marcador de posición como ${VAR}, $VAR, o {{VAR}}. Su agente AI (Claude, Copilot, Cursor, etc.) es responsable de resolver la intención del usuario en una cadena concreta antes de llamar a la herramienta.

En la práctica, esto significa:

  • Formule indicaciones naturalmente — "use nombre de usuario/contraseña de .env.local" funciona. El agente lee el archivo con sus propias herramientas del sistema de archivos y sustituye los valores.
  • No pegue la sintaxis de marcador de posición — escribir value: "${USERNAME}" en una indicación causará que la cadena literal ${USERNAME} se escriba en la entrada.
  • Sea explícito sobre fuentes ambiguas — si dice "use mis credenciales guardadas" sin apuntar al agente a un archivo o variable ambiental, un agente bien intencionado preguntará en lugar de adivinar. Dígale dónde buscar.
caution

Algunos flujos de autenticación no son compatibles. before actions drive the page through Playwright-style interactions in a Dockerized Chromium instance. The following are intentionally out of scope:

  • Captcha desafíos (reCAPTCHA, hCaptcha, etc.)
  • 2FA / TOTP / SMS códigos de verificación
  • SSO de terceros cadenas de redirección (por ejemplo, "Inicia sesión con Google", páginas de inicio de sesión alojadas en Okta)

Cuando su flujo de inicio de sesión real requiere cualquiera de los anteriores, escanee un punto de entrada alternativo:

  • Una cookie de sesión pre-autenticada inyectada con Inyección de Cookies — autentíquese una vez en un navegador real, luego pase la cookie de sesión resultante para que el escaneo comience ya con sesión iniciada
  • Una token de sesión o URL de bypass que su equipo usa para pruebas automatizadas
  • Una URL de pruebas con autenticación desactivada para pruebas de accesibilidad

La herramienta analyze soporta un array opcional cookies que establece cookies en el contexto del navegador antes de la navegación — para que acompañen la primera solicitud a la página. Esto es distinto de acciones de before, que se ejecutan después navegación y por lo tanto no pueden influir en cómo se enruta la solicitud inicial. Dos usos comunes:

  • Enrutamiento de entorno — establece una cookie de selector de rama de característica o de preparación que una capa de borde o CDN lee para decidir qué versión del sitio servir.
  • Sesiones pre-autenticadas — inyecta una cookie de sesión válida para que el escaneo comience ya iniciado sesión, sin pasar por un formulario de inicio de sesión a través de before.

La matriz cookies admite hasta 20 cookies.

Campo Requerido Descripción
name Sí Nombre de la cookie. Aparece en registros y mensajes de error — nunca coloques valores secretos aquí.
value Sí Valor de la cookie. Tratado como sensible: nunca registrado, eco en errores, o enviado a telemetría. Hasta 10,000 caracteres (lo suficientemente largo para JWTs y tokens de sesión).
domain Sí Dominio de la cookie. Requerido para que el alcance sea explícito. Usa un punto inicial (.example.com) para compartir la cookie a través de subdominios.
path No Ruta de la cookie. Por defecto es /.
sameSite No Uno de "Strict", "Lax", o "None". "None" requiere secure: true.
secure No Booleano.
httpOnly No Booleano.
expires No Vencimiento como una marca de tiempo Unix en segundos. Omite para una cookie de sesión.

Ejemplo: Acceder a una página pre-autenticada

Indique a su agente de IA en lenguaje natural; el agente traduce su intención en la llamada a la herramienta:

Analyze https://app.example.com for accessibility issues. Set the session
cookie for app.example.com from ./.env.local so the scan starts already
logged in.

El agente resuelve el valor de la cookie y llama a la herramienta analyze con un paquete similar a:

{
  "url": "https://app.example.com",
  "cookies": [
    {
      "name": "session",
      "value": "<resolved-from-.env.local>",
      "domain": "app.example.com"
    }
  ]
}
important

cookies[*].value se trata como sensible. Al igual que con fill.value, el servidor Axe MCP nunca registra el value de una cookie, nunca lo refleja en mensajes de error, y nunca lo envía a telemetría. Sin embargo, el name de una cookie lo hace aparece en registros y mensajes de error — guarda secretos en value, nunca en name.

note

El agente resuelve value, no el servidor. Los valores de las cookies siguen la misma regla que fill.value en acciones de before: el servidor trata value como una cadena literal y no lee archivos, expande variables de entorno, o interpreta la sintaxis de marcador de posición como ${VAR}. Tu agente de IA resuelve la intención del usuario en una cadena concreta antes de llamar a la herramienta.

Capturas de pantalla

La herramienta analyze puede devolver una captura de pantalla de la página junto con el informe de violación, para que puedas ver qué se escaneó. Pasa el parámetro opcional screenshot para optar — un objeto vacío es suficiente:

{
  "url": "http://localhost:3000",
  "screenshot": {}
}

PNG es el predeterminado. Establece format en "jpeg" para una imagen más pequeña en páginas con muchas fotos:

{
  "url": "http://localhost:3000",
  "screenshot": { "format": "jpeg" }
}

La imagen llega como un bloque de contenido de imagen estándar MCP, después del informe de violación.

Lo que muestra la captura de pantalla

  • El área visible de la pantalla, no la página completa. El contenido debajo del pliegue no se incluye. Para capturar más de la página, pasa un viewportHeight alto (por ejemplo, 4096) para que el área visible cubra lo que deseas ver.
  • La página tal como estaba inmediatamente antes de que comenzara el escaneo. La captura ocurre justo antes de axe.run(), así que los cambios en el DOM que ocurren durante el escaneo — re-renderizado de SPA, actualizaciones de useEffect, animaciones, solicitudes en vuelo — no se reflejan. En aplicaciones de una sola página este desfase es común.
caution

No tomes la captura de pantalla como la fuente de verdad de lo que Axe vio. Debido al desfase de tiempo mencionado, un elemento visible en la imagen puede no ser lo que Axe evaluó. Pide a tu agente que no describa elementos visibles pero no señalados como si fueran resultados de escaneo — el informe de violación es autoritativo.

Costo y soporte al cliente

tip

Solicita capturas de pantalla con deliberación. Un bloque de contenido de imagen cuesta tokens de entrada de imagen en el siguiente turno de tu agente — aproximadamente un orden de magnitud más que el texto equivalente. Pide una captura cuando realmente quieras ver la página, en lugar de agregarla a cada escaneo.

Si la imagen se renderea en línea depende de tu cliente MCP. El servidor siempre devuelve un bloque de imagen compatible con la especificación, pero algunos clientes colapsan los resultados de la herramienta o omiten vistas previas de imagen — VS Code con Copilot lo muestra, mientras que Cursor y Claude Desktop pueden no hacerlo. Una vista previa faltante es una limitación del lado del cliente, no una captura fallida.

Guardando capturas de pantalla en el disco

La captura de pantalla también puede escribirse en un archivo, lo cual es la manera confiable de ver una captura en un cliente que no renderiza imágenes en línea. Establece saveTo en una ruta absoluta:

{
  "url": "http://localhost:3000",
  "screenshot": { "saveTo": "/Users/me/Desktop/home.png" }
}

O establece save: true para permitir que el servidor elija el nombre del archivo:

{
  "url": "http://localhost:3000",
  "screenshot": { "save": true }
}
Campo Tipo Propósito
saveTo string Ruta absoluta para escribir la imagen. Si apunta a un directorio existente, se escribe un nombre de archivo generado dentro de él. Implica guardar, por lo que save no es necesario junto a él.
save boolean Escribe la imagen bajo un nombre de archivo generado en el directorio de capturas de pantalla del servidor (AXE_SCREENSHOT_DIR, por defecto el directorio de sistema operativo temporal). Se ignora cuando saveTo está configurado.
inline boolean Si también adjuntar la imagen como un bloque en línea (por defecto true). Establece false para omitir la imagen en línea y devolver solo la ruta guardada.

La ruta absoluta que se escribió regresa en el arreglo de messages de la respuesta, para que tu agente pueda decirte dónde encontrar el archivo.

tip

Combina un guardado con inline: false para evitar pagar por la imagen dos veces. Si tu cliente no puede renderizar la imagen en línea de todos modos, { "save": true, "inline": false } escribe el archivo y omite el bloque de contenido de imagen — ahorrando los tokens de entrada de imagen que de otro modo costaría en el próximo turno de tu agente.

inline: false solo entra en efecto una vez que el guardado realmente tiene éxito. Si la escritura falla, la imagen todavía se devuelve en línea para que la captura no se pierda.

important

Bajo la distribución de Docker, el archivo se escribe dentro del contenedor. Para alcanzarlo desde tu host, monta un volumen sobre el directorio de destino y apunta saveTo (o AXE_SCREENSHOT_DIR) a la ruta del lado del contenedor. El servidor no detecta si existe un montaje; sin uno, el archivo se escribe y luego se descarta con el contenedor.

El guardado se aplica a solo escaneos exitosos. Si el escaneo falla después de que se capturó la captura de pantalla, la imagen se devuelve en línea junto con el error sin importar inline, y nunca se escribe en disco.

Cuando falla la captura

La captura de pantalla se hace con el mejor esfuerzo y nunca falla un escaneo. Si la captura se agota, el escaneo aún devuelve sus resultados con una nota en el array de messages de la respuesta:

Screenshot capture failed: <reason>

Si el el escaneo en sí falla después de que se tomó la captura de pantalla, la imagen se devuelve con la respuesta de error de todas formas — el estado visual de la página en el momento en que las cosas salieron mal suele ser la evidencia de depuración más útil que tienes.

note

Las capturas de pantalla que solicitas no se envían a Deque. La imagen se captura localmente y se devuelve directamente a tu agente. Esto es separado del captura de pantalla de página completa que Reglas Avanzadas suben para la evaluación del lado del servidor; ver Qué se envía a Deque.

Reglas Avanzadas

Más allá del conjunto de reglas estándar de axe-core, la herramienta analyze puede ejecutar Reglas Avanzadas — pruebas automatizadas que utilizan capturas de pantalla, visión por computadora y modelos de lenguaje grandes para detectar problemas que axe-core por sí sola no puede, como encabezados que solo parecen encabezados o imágenes informativas con texto alternativo poco útil.

Qué preajuste se ejecuta está gobernado por el Configuración de Axe de tu organización, y — donde tu administrador lo permita — puede ser reemplazado por servidor con AXE_ADVANCED_RULES o por escaneo con el argumento advancedRules:

{
  "url": "http://localhost:3000",
  "advancedRules": "thorough"
}

Cada respuesta informa el preajuste que realmente se ejecutó y de dónde provino:

{
  "advancedRules": {
    "value": "thorough",
    "source": "tool_arg"
  }
}

Las Reglas Avanzadas vienen con tu suscripción a Axe DevTools para Web, la misma que te proporciona el Axe MCP Server. Añaden aproximadamente de 15 a 20 segundos a un escaneo, consumen Créditos de AI, y son el único caso donde analyze envía datos de la página (una captura de pantalla completa más la estructura de la página) a Deque para su evaluación. Consulta Reglas Avanzadas para presets, precedencias, mensajes de degradación y detalles de privacidad.

Beneficios Clave

  • Pruebas en Navegadores Reales - Prueba la página realmente renderizada, no solo el código fuente, garantizando resultados precisos
  • Estándares de la Organización - Respeta las configuraciones de Axe de tu equipo para pruebas consistentes en todos los usuarios
  • Cobertura Integral - Aprovecha la plataforma Axe líder en la industria
  • Pruebas de Respuesta - Prueba en dimensiones específicas del viewport para detectar problemas de accesibilidad específicos de puntos de ruptura
  • Escaneos Dirigidos - Delimita un escaneo a una región específica, iframe o raíz de sombra con el parámetro selector
  • Páginas Autenticadas e Interactivas - Escanea páginas detrás de un inicio de sesión, descarta banners de cookies, o espera contenido dinámico usando acciones before
  • Cookies de Sesión y de Entorno - Ingresa ya autenticado, o dirígete a un entorno específico, inyectando cookies antes de la navegación con el parámetro cookies
  • Contexto Visual - Devuelve una captura de pantalla de la página junto al informe con el parámetro screenshot, incluso cuando un escaneo falla
  • Reglas Avanzadas - Detecta problemas que requieren razonamiento visual o contextual, con un umbral de confianza que controla tu organización
  • Pruebas Guiadas Inteligentes - Ejecuta las Pruebas Guiadas de Teclado, Elementos Interactivos y Diálogo Modal en la misma página en la misma llamada con el parámetro igtTools

Salida

La herramienta devuelve una respuesta JSON estructurada que contiene:

  • Todas las violaciones de accesibilidad encontradas
  • Niveles de severidad de las violaciones (críticas, serias, moderadas, menores)
  • Selectores de elementos específicos y código fuente
  • IDs y descripciones de reglas
  • Un bloque de advancedRules que informa el preajuste Reglas Avanzadas que se ejecutó y de dónde provino
  • Un array de messages que lleva cualquier nota sobre la ejecución (por ejemplo, una captura de pantalla fallida, una ejecución degradada de reglas avanzadas, o la ruta a la que se guardó una captura de pantalla)

Cuando se establece screenshot, un bloque de contenido de imagen sigue al informe. Cuando se establece igtTools, los resultados de IGT se devuelven junto con los resultados de Axe, clasificados por nombre de IGT.

Is this page helpful?

Help us improve this page

Still need help?