Preguntas frecuentes
runOnly debe ser un objeto, no un array simple. runOnly: ['img-alt-present'] se ignora silenciosamente (el motor termina ejecutando "todas las reglas"), porque esa forma no tiene ninguno de los campos que el motor realmente comprueba (includeRuleIds, tags, etc.). Es fácil utilizar por error un array simple, así que vale la pena comprobar esto primero.
Solución:
runOnly: { includeRuleIds: ['img-alt-present'] }
Consulta ENGINE_OPTIONS.md para ver la forma completa.
"Mi regla personalizada siempre devuelve cantTell sin un motivo claro"
Primero revisa el campo error del resultado: si dice "<something> is not defined", tu runInPage hace referencia a una variable definida fuera del cuerpo de la función (un const de ámbito de módulo, un helper importado, cualquier cosa a la que no se llegue a través de ctx.*). Esta es una trampa real y común: runInPage se serializa a texto fuente y se vuelve a evaluar más tarde en el contexto de la página, así que la compilación nunca detecta esto: el problema solo aparece cuando se ejecuta la regla, y el fallo parece un resultado normal (aunque poco informativo), no un error de ejecución. Consulta RULE_AUTHORING.md §1.1 para ver la explicación completa y la solución (mueve el valor dentro de runInPage o enrútalo a través de ctx.rule/ctx.helpers).
"Una regla que depende de la geometría (por ejemplo, target-size-minimum) siempre indica notApplicable"
jsdom puro (sin un navegador real) no implementa un motor de diseño CSS: getBoundingClientRect() siempre devuelve una geometría de cero. Las reglas que necesitan información real de maquetación devuelven notApplicable al ejecutarse con jsdom en lugar de adivinar. Ejecuta en su lugar a través de un navegador real (Puppeteer/Playwright, consulta INTEGRATION.md Patrón 2) para obtener hallazgos reales de estas reglas. Consulta LIMITATIONS.md.
"Solo veo apariciones de fail/cantTell. ¿Dónde está la lista de elementos que aprobaron?"
Por diseño, este motor nunca enumera los elementos que una regla aprobó, solo los que señaló. El outcome: 'pass' general de una regla significa "existían uno o más objetivos aplicables y ninguno fue señalado", pero occurrences es [] en ambos casos. Si necesitas saber qué elementos concretos se comprobaron y se consideraron correctos, eso actualmente no se expone. Consulta OUTPUT_SCHEMA.md.
"Una regla que esperaba que se activara devolvió notApplicable / no encontró nada en una página que sé que tiene el problema"
Dos causas comunes, en orden de probabilidad:
- El elemento está excluido del árbol de accesibilidad:
aria-hidden="true", display: none, visibility: hidden, hidden o un ancestro inert. La mayoría de las reglas omiten contenido que ya es invisible para la tecnología de asistencia, ya que comprobar un elemento oculto no tendría sentido y podría producir un fail engañoso sobre contenido que ningún usuario encuentra. Algunas reglas se excluyen explícitamente de este filtro cuando no tendría sentido aplicarlo (por ejemplo, no-autoplay-audio: el audio oculto sigue sonando). Revisa el comentario de encabezado del archivo de la regla específica (@applicability) en src/checks/. excludeSelectors: si has configurado esto (directamente o heredado de una configuración compartida), confirma que el elemento en cuestión no coincide con él. Recuerda que esto también se puede limitar a una sola regla mediante engineOptions.rules[ruleId].excludeSelectors (consulta ENGINE_OPTIONS.md). Si una regla que esperas que se active sigue devolviendo notApplicable/pass solo para un elemento, comprueba si esa regla en particular tiene su propia lista de exclusión configurada, no solo la global.
No. Consulta WCAG_CONFORMANCE.md. Un pass significa que toda comprobación automatizable salió limpia. Una fracción considerable de WCAG requiere juicio humano (texto alternativo preciso, mensajes de error comprensibles) o pruebas dinámicas que la arquitectura de este motor no puede hacer en absoluto (trampas de teclado, reflow al hacer zoom). Consulta LIMITATIONS.md para ver la lista explícita, deliberadamente no exhaustiva.
"¿Debo tratar cantTell como un fallo?"
Trátalo como "necesita que lo revise una persona": por diseño no es ni aprobado ni fallido. La mayoría de los equipos registran los hallazgos de cantTell sin hacer fallar la CI por ellos, ya que hacer fallar una compilación por algo que el motor explícitamente no pudo determinar tiende a enseñar a la gente a ignorar la validación. Consulta POLICY.md si quieres cambiar este comportamiento (por ejemplo, mediante un contrato de política personalizado), y INTEGRATION.md para ver un ejemplo concreto de validación en CI.
"¿Qué pasa si una configuración regional solo está parcialmente traducida?"
Las claves faltantes recurren al inglés por cadena (nunca a un resultado en blanco o roto), de modo que una configuración regional parcial recurre de forma gradual al inglés sin dejar textos vacíos, en lugar de fallar por completo. Consulta I18N.md para ver el mecanismo y la cobertura actual. La paridad de claves se hace cumplir en lugar de darse por hecha: npm run i18n:sync traslada cualquier clave nueva o renombrada de en.json a los demás archivos de configuración regional, y la compilación falla si alguno queda desincronizado. Una clave que agrega conserva el texto en inglés hasta que alguien la traduce, de modo que una configuración regional puede ir atrasada en la redacción sin ir nunca atrasada en las claves.
"runDomRulesInPage frente a runa11yCoreInPage: ¿cuál necesito?"
runDomRulesInPage si la llamas directamente en el mismo proceso de Node (jsdom, un content script de extensión de navegador). runa11yCoreInPage si le entregas la función en sí a un realm de JS diferente: casi siempre page.evaluate en Puppeteer/Playwright, que serializa la función a texto fuente y la vuelve a ejecutar dentro de la pestaña del navegador (que no tiene acceso al ámbito de tus módulos de Node). Consulta INTEGRATION.md para ver ambos patrones desarrollados por completo.