12k
All articles

¿Qué es el árbol de accesibilidad?

Comprende cómo los navegadores crean el árbol de accesibilidad, calculan roles y nombres, lo inspeccionan en DevTools y prueban controles con Playwright.

OpenReplay Team
OpenReplay Team
¿Qué es el árbol de accesibilidad?

El árbol de accesibilidad es una segunda representación de una página web que el navegador construye a partir del DOM para las tecnologías de asistencia. Conserva el rol, el nombre accesible, el estado y el valor de cada elemento significativo, y descarta la mayoría de los contenedores que solo sirven para la maquetación.

Te encuentras con él cuando una auditoría señala “button has no accessible name”, cuando un linter se queja de un div clicable o cuando el getByRole de Playwright no encuentra un elemento que ves en pantalla. Los tres informan sobre la misma estructura. Este artículo explica cómo construye el navegador ese árbol, qué contiene cada nodo, cómo inspeccionarlo y cómo escribir pruebas contra él.

Puntos clave

  • Los navegadores construyen el árbol de accesibilidad a partir del DOM, la semántica nativa de HTML y los atributos ARIA. Los elementos div y span que solo sirven para aplicar estilos normalmente no obtienen un nodo propio.
  • El contenido oculto con display: none, visibility: hidden, el atributo hidden o aria-hidden="true" queda excluido del árbol de accesibilidad, aunque siga presente en el DOM.
  • De forma simplificada, el nombre accesible de un elemento se obtiene primero de aria-labelledby, después de aria-label, luego del etiquetado nativo (<label>, alt), a continuación del contenido de texto y, por último, de title.
  • Un <div> con un manejador de clic no tiene rol de botón en el árbol, por lo que los lectores de pantalla no lo anuncian como control y los usuarios de teclado no pueden alcanzarlo.
  • El localizador getByRole de Playwright y las ARIA snapshots trabajan a partir de roles y nombres accesibles, de modo que las pruebas escritas con ellos fallan ante los mismos errores que bloquean a los usuarios de tecnologías de asistencia.

Cómo construye el navegador el árbol de accesibilidad

Los navegadores construyen el árbol de accesibilidad a partir de tres fuentes: el DOM, la semántica integrada de los elementos HTML y los atributos ARIA que haya. HTML-AAM define cómo se asigna cada elemento HTML a un rol accesible, y Core-AAM 1.2 define cómo se asignan los roles, estados y propiedades ARIA a las API de accesibilidad de cada plataforma.

La correspondencia entre el DOM y el árbol de accesibilidad no es uno a uno. Un <div> o un <span> que existe solo para flexbox o para aplicar estilos normalmente se aplana y desaparece. En sentido contrario, HTML-AAM establece que un <video> con el atributo controls expone sus controles integrados, como reproducir y volumen, como nodos hijos asignados a roles como button y slider. Ninguno de esos controles aparece en el DOM de la página.

El contenido oculto también se elimina. WAI-ARIA 1.2 excluye elementos del árbol cuando no se muestran (display: none, visibility: hidden, el atributo HTML hidden) o cuando llevan aria-hidden="true". Una clase CSS de “ocultación visual” o sr-only es un caso distinto: desplaza el contenido fuera de la pantalla, por lo que el contenido permanece en el árbol.

¿Qué contiene un nodo accesible?

Cada nodo del árbol de accesibilidad expone hasta cuatro cosas: un rol (qué es), un nombre (cómo se llama), unos estados (su condición actual) y, en algunos controles, un valor. Este es un checkbox con etiqueta:

<label><input type="checkbox" checked> Email me product updates</label>

En el formato de ARIA snapshot de Playwright, el nodo resultante tiene este aspecto (a modo ilustrativo):

- checkbox "Email me product updates" [checked]

El rol es checkbox, el <label> aporta el nombre y [checked] es el estado. Un checkbox comunica su información a través de su estado de marcado. El valor se aplica a controles como los cuadros de texto y los sliders, y el formato de snapshot lo coloca después de dos puntos:

- textbox "Email": ada@example.com

Para saber cómo se eligen los roles individuales y cuándo conviene añadir roles ARIA por tu cuenta, consulta Understanding Accessibility Roles in HTML.

¿Cómo se calcula el nombre accesible?

De forma simplificada, el navegador toma el nombre accesible de un elemento de la primera fuente que lo proporcione:

  1. aria-labelledby, que apunta al texto de otros elementos
  2. aria-label
  3. El etiquetado nativo: un elemento <label> o el texto alt de una imagen
  4. El propio contenido de texto del elemento, en los roles que admiten obtener el nombre a partir del contenido (botones, enlaces)
  5. El atributo title, como último recurso

ARIA tiene prioridad sobre el etiquetado nativo. Si un botón tiene el texto visible “Send” y aria-label="Submit form", el lector de pantalla anuncia “Submit form”, y es posible que un usuario de control por voz que diga “click Send” no obtenga ninguna coincidencia. El algoritmo completo, incluidos los controles incrustados y la recursión, se encuentra en Accessible Name and Description Computation 1.2.

¿Cómo usan los lectores de pantalla el árbol de accesibilidad?

Los lectores de pantalla no leen el DOM. Leen el árbol de accesibilidad a través de la API de accesibilidad del sistema operativo, que el navegador implementa. Las tablas de correspondencias de Core-AAM abarcan MSAA con IAccessible2 y UI Automation en Windows, la AX API (NSAccessibility) en macOS y ATK/AT-SPI en Linux. El lector de pantalla consulta a esos objetos su rol, nombre y estado, y escucha eventos como los cambios de foco. Si una propiedad nunca llega al árbol, el usuario nunca la oye.

Cómo inspeccionar el árbol de accesibilidad

Tanto Chrome DevTools como Firefox DevTools muestran el árbol de accesibilidad directamente: Chrome mediante la pestaña Accessibility del panel Elements, y Firefox mediante su Accessibility Inspector.

Chrome: abre el panel Elements, selecciona un nodo y abre la pestaña Accessibility (puede estar oculta tras el botón More Tabs »). Muestra el rol, el nombre y las propiedades calculados, además del origen del nombre. Activa Show accessibility tree para sustituir el árbol DOM del panel Elements por el árbol de accesibilidad de toda la página. La referencia de accesibilidad de Chrome DevTools documenta ambas funciones. Chrome dispone además de una página interna, chrome://accessibility, para depuración a nivel de navegador.

Firefox: el Accessibility Inspector se abre desde el menú contextual de la página (Inspect Accessibility Properties) o haciendo clic derecho sobre un nodo en el panel HTML del Inspector y eligiendo Show Accessibility Properties. El inspector expone el propio árbol de accesibilidad de Gecko, en lugar de información procedente de la capa de accesibilidad de la plataforma, por lo que muestra el mismo resultado en todos los sistemas operativos.

Dos errores que revela el árbol de accesibilidad

El árbol de accesibilidad hace evidentes dos errores habituales en componentes: un div clicable sin rol de botón y un botón de icono sin nombre accesible. Cada problema se manifiesta como un rol ausente o un nombre ausente. Las plantillas de Vue y Angular producen el mismo resultado, porque el árbol solo ve el DOM renderizado.

Un div clicable sin rol de botón

// Before
<div className="btn" onClick={save}>Save</div>

// After
<button type="button" onClick={save}>Save</button>
# Before (illustrative)
- text: Save
# After
- button "Save"

Un <div> con un manejador de clic no tiene rol de botón en el árbol de accesibilidad. El lector de pantalla no lo anuncia como control, y un usuario de teclado no puede llegar a él con Tab ni activarlo con Enter o Espacio. Las grabaciones de sesión (session replays) de este error muestran la brecha con claridad: los usuarios de ratón hacen clic en el control sin problemas, mientras que los usuarios de teclado pasan con Tab de largo por algo que parece un botón pero que no existe como tal en el árbol.

Un botón de icono sin nombre

// Before
<button onClick={close}><svg aria-hidden="true">{/* icon */}</svg></button>

// After
<button aria-label="Close dialog" onClick={close}>
  <svg aria-hidden="true">{/* icon */}</svg>
</button>
# Before (illustrative)
- button
# After
- button "Close dialog"

Un botón que solo contiene un icono, sin texto y sin aria-label, aparece como un botón con el nombre vacío, por lo que el lector de pantalla no tiene nada que anunciar salvo “botón”.

Pruebas del árbol de accesibilidad con Playwright

El localizador getByRole de Playwright encuentra elementos por rol ARIA, atributos ARIA y nombre accesible, siguiendo las especificaciones del W3C, y por defecto solo coincide con elementos no ocultos. Por tanto, una prueba que localiza un control por rol y nombre también comprueba que el control expone ese rol y ese nombre. Las ARIA snapshots van un paso más allá: locator.ariaSnapshot() y page.ariaSnapshot() devuelven una vista YAML del árbol de accesibilidad, y expect(locator).toMatchAriaSnapshot() realiza aserciones contra ella.

import { test, expect } from '@playwright/test';

test('save control is a real button', async ({ page }) => {
  await page.goto('/settings');
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Save"`);
  await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Close dialog"`);
});

Si ejecutas esta prueba contra el marcado “antes”, la llamada a getByRole falla, por el mismo motivo por el que un usuario de lector de pantalla se queda atascado. Una plantilla solo necesita coincidir con una parte del árbol, y una plantilla de un único nodo como estas coincide a cualquier profundidad. Si una plantilla enumera varios nodos en el nivel superior, estos deben compartir el mismo padre y aparecer en el mismo orden que en el árbol. Cuando un localizador falle, registra await page.ariaSnapshot() para ver qué contiene realmente el árbol. Estos son los nombres de la API de JavaScript; los bindings para otros lenguajes tienen equivalentes. La documentación de Playwright también indica que los localizadores basados en roles no sustituyen a las auditorías de accesibilidad ni a las pruebas de conformidad, así que trátalos como una fuente de retroalimentación temprana.

Los datos de rol y nombre importan también más allá de los ejecutores de pruebas. Algunas herramientas de automatización basadas en IA leen la estructura semántica de la página, que es uno de los motivos por los que los navegadores agénticos funcionan mejor con marcado semántico.

Conclusión

El árbol de accesibilidad es la versión de tu interfaz que realmente reciben las tecnologías de asistencia, y un rol ausente o un nombre vacío en él significa que el control no funciona para esos usuarios. Abre la pestaña Accessibility en tu componente personalizado más utilizado, comprueba su rol y su nombre, y convierte esa comprobación en una aserción con getByRole para que el problema no vuelva a aparecer.

Preguntas frecuentes

¿Añadir role='button' a un div lo corrige en el árbol de accesibilidad?

Solo en parte. Añadir role='button' da al div un nodo de botón en el árbol de accesibilidad, de modo que los lectores de pantalla lo anuncian como botón, pero no le añade ningún comportamiento de botón. El div sigue necesitando tabindex='0' para entrar en el orden de tabulación y un manejador keydown que ejecute la acción con Enter y Espacio. Un elemento button nativo proporciona el foco y la activación por teclado de forma predeterminada.

¿aria-hidden='true' impide que los usuarios de teclado enfoquen un elemento?

No. aria-hidden='true' elimina un elemento y sus descendientes del árbol de accesibilidad, pero no tiene ningún efecto sobre el foco del teclado. Un enlace, botón o campo de entrada dentro de un contenedor con aria-hidden puede seguir recibiendo el foco con Tab, por lo que los usuarios de teclado llegan a un control que la tecnología de asistencia no puede nombrar. Establecer aria-hidden='false' en un hijo no vuelve a exponerlo. Para ocultar contenido interactivo a todos los usuarios, utiliza display: none o el atributo hidden.

¿Cómo puedo leer el rol calculado y el nombre accesible de un elemento en pruebas automatizadas?

Utiliza comandos de automatización en lugar de scripts de página. La especificación WebDriver del W3C define los comandos Get Computed Role y Get Computed Label, que ChromeDriver implementa y WebdriverIO expone como getComputedRole() y getComputedLabel(). Playwright ofrece las aserciones toHaveRole() y toHaveAccessibleName() para un único elemento, además de ariaSnapshot() para obtener una vista YAML de un subárbol completo. Todos ellos informan del rol y el nombre que recibe la tecnología de asistencia.

¿Por qué cambiaron las coincidencias de nombre de getByRole tras actualizar a Playwright 1.65?

Playwright 1.65 dejó de tener en cuenta el texto que el navegador no renderiza al calcular los nombres accesibles y las ARIA snapshots. El texto que no está asignado a un slot, o que se encuentra directamente dentro de un elemento details cerrado, ya no cuenta. Esto puede cambiar los resultados de getByRole() con la opción name, la salida de ariaSnapshot() y las aserciones de toMatchAriaSnapshot(), por lo que los nombres esperados deben coincidir únicamente con el texto que el navegador renderiza realmente.

Open-source session replay

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.