Saltar al contenido principal

ByRole

[Traducción Beta No Oficial]

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

getByRole, queryByRole, getAllByRole, queryAllByRole, findByRole, findAllByRole

API​

getByRole(
  // If you're using `screen`, then skip the container argument:
  container: HTMLElement,
  role: string,
  options?: {
    hidden?: boolean = false,
    name?: TextMatch,
    description?: TextMatch,
    selected?: boolean,
    busy?: boolean,
    checked?: boolean,
    pressed?: boolean,
    suggest?: boolean,
    current?: boolean | string,
    expanded?: boolean,
    queryFallbacks?: boolean,
    level?: number,
    value?: {
      min?: number,
      max?: number,
      now?: number,
      text?: TextMatch,
    }
  }): HTMLElement

Realiza consultas de elementos con el rol especificado (y también acepta un TextMatch). Se consideran los roles predeterminados, por ejemplo <button /> tiene el rol button sin establecer explícitamente el atributo role. Aquí puedes consultar una tabla de elementos HTML con sus roles predeterminados y deseados.

Ten en cuenta que establecer un atributo role y/o aria-* que coincida con la semántica ARIA implícita es innecesario y no se recomienda, ya que estas propiedades ya están configuradas por el navegador. No debemos usar los atributos role y aria-* de manera que entren en conflicto con la semántica descrita. Por ejemplo, un elemento button no puede tener el atributo role como heading, porque el elemento button tiene características predeterminadas que entran en conflicto con el rol heading.

Los roles coinciden literalmente por igualdad de cadena, sin heredar de la jerarquía de roles ARIA. Como resultado, consultar un rol superclase como checkbox no incluirá elementos con un rol subclase como switch.

Puedes consultar el/los elemento(s) devuelto(s) por su nombre o descripción accesible. El nombre accesible en casos simples equivale, por ejemplo, a la etiqueta de un elemento de formulario, el contenido de texto de un botón o el valor del atributo aria-label. Se puede usar para consultar un elemento específico si hay múltiples elementos con el mismo rol en el contenido renderizado. Para una guía detallada, consulta "¿Qué es un nombre accesible?" de TPGi. Si solo consultas un único elemento con getByText('The name'), muchas veces es mejor usar getByRole(expectedRole, { name: 'The name' }). La consulta por nombre accesible no reemplaza otras consultas como *ByAlt o *ByTitle. Aunque el nombre accesible puede ser igual a estos atributos, no reemplaza su funcionalidad. Por ejemplo, <img aria-label="fancy image" src="fancy.jpg" /> será devuelta por getByRole('img', { name: 'fancy image' }). Sin embargo, la imagen no mostrará su descripción si fancy.jpg no pudo cargarse. Si deseas verificar esta funcionalidad en tu prueba, dependerá de tus necesidades.

[input type password]

Lamentablemente, la especificación define que <input type="password" /> no tiene rol implícito. Esto significa que para consultar este tipo de elemento debemos recurrir a consultas menos potentes como ByLabelText.

Opciones​

hidden​

Si estableces hidden como true, también se considerarán para la consulta elementos que normalmente están excluidos del árbol de accesibilidad. El comportamiento predeterminado sigue https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion con la excepción de role="none" y role="presentation", que siempre se consideran en la consulta. Por ejemplo, en

<body>
  <main aria-hidden="true">
    <button>Open dialog</button>
  </main>
  <div role="dialog">
    <button>Close dialog</button>
  </div>
</body>

getByRole('button') solo devolvería el botón Close dialog. Para realizar afirmaciones sobre el botón Open dialog, necesitarías usar getAllByRole('button', { hidden: true }).

El valor predeterminado de hidden puede configurarse.

selected​

Puedes filtrar los elementos devueltos por su estado de selección estableciendo selected: true o selected: false.

Por ejemplo, en

<body>
  <div role="tablist">
    <button role="tab" aria-selected="true">Native</button>
    <button role="tab" aria-selected="false">React</button>
    <button role="tab" aria-selected="false">Cypress</button>
  </div>
</body>

puedes obtener la pestaña "Native" llamando a getByRole('tab', { selected: true }). Para aprender más sobre el estado seleccionado y qué elementos pueden tener este estado, consulta ARIA aria-selected.

busy​

Puedes filtrar los elementos devueltos por su estado de ocupado configurando busy: true o busy: false.

Por ejemplo, en

<body>
  <section>
    <div role="alert" aria-busy="false">Login failed</div>
    <div role="alert" aria-busy="true">Error: Loading message...</div>
  </section>
</body>

puedes obtener la alerta "Login failed" llamando a getByRole('alert', { busy: false }). Para aprender más sobre el estado de ocupado, consulta ARIA aria-busy y MDN aria-busy attribute.

checked​

Puedes filtrar los elementos devueltos por su estado de marcado configurando checked: true o checked: false.

Por ejemplo, en

<body>
  <section>
    <button role="checkbox" aria-checked="true">Sugar</button>
    <button role="checkbox" aria-checked="false">Gummy bears</button>
    <button role="checkbox" aria-checked="false">Whipped cream</button>
  </section>
</body>

puedes obtener la opción "Sugar" llamando a getByRole('checkbox', { checked: true }). Para aprender más sobre el estado de marcado y qué elementos pueden tener este estado, consulta ARIA aria-checked.

Nota

Las casillas de verificación tienen un estado "mixto", que no se considera marcado ni desmarcado (detalles aquí).

current​

Puedes filtrar los elementos devueltos por su estado actual configurando current: boolean | string. Ten en cuenta que ningún atributo aria-current coincidirá con current: false ya que false es el valor predeterminado para aria-current.

Por ejemplo, en

<body>
  <nav>
    <a href="current/page" aria-current="page">👍</a>
    <a href="another/page">👎</a>
  </nav>
</body>

puedes obtener el enlace "👍" llamando a getByRole('link', { current: 'page' }) y el "👎" llamando a getByRole('link', { current: false }). Para aprender más sobre el estado actual, consulta ARIA aria-current.

pressed​

Los botones pueden tener un estado de presionado. Puedes filtrar los elementos devueltos por su estado de presionado configurando pressed: true o pressed: false.

Por ejemplo, en

<body>
  <section>
    <button aria-pressed="true">👍</button>
    <button aria-pressed="false">👎</button>
  </section>
</body>

puedes obtener el botón "👍" llamando a getByRole('button', { pressed: true }). Para aprender más sobre el estado de presionado, consulta ARIA aria-pressed.

suggest​

Puedes deshabilitar la capacidad de lanzar sugerencias para una consulta específica configurando este valor en false.
Configurar este valor en true lanzará sugerencias para la consulta específica.

expanded​

Puedes filtrar los elementos devueltos por su estado expandido configurando expanded: true o expanded: false.

Por ejemplo, en

<body>
  <nav>
    <ul>
      <li>
        <a aria-expanded="false" aria-haspopup="true" href="..."
          >Expandable Menu Item</a
        >
        <ul>
          <li><a href="#">Submenu Item 1</a></li>
          <li><a href="#">Submenu Item 1</a></li>
        </ul>
      </li>
      <li><a href="#">Regular Menu Item</a></li>
    </ul>
  </nav>
</body>

puedes obtener el enlace "Expandable Menu Item" llamando a getByRole('link', { expanded: false }). Para aprender más sobre el estado expandido y qué elementos pueden tener este estado, consulta ARIA aria-expanded.

<div role="dialog">...</div>
import {screen} from '@testing-library/dom'

const dialogContainer = screen.getByRole('dialog')

queryFallbacks​

Por defecto, se asume que se admite el primer rol de cada elemento, por lo que solo se puede consultar el primer rol. Si necesitas consultar un elemento por cualquiera de sus roles alternativos, puedes usar queryFallbacks: true.

Por ejemplo, getByRole('switch') siempre coincidiría con <div role="switch checkbox" /> porque es el primer rol, mientras que getByRole('checkbox') no lo haría. Sin embargo, getByRole('checkbox', { queryFallbacks: true }) habilitaría todos los roles alternativos y por lo tanto coincidiría con el mismo elemento.

Un elemento no tiene múltiples roles en un entorno dado. Tiene un único rol. Los múltiples roles en el atributo se evalúan de izquierda a derecha hasta que el entorno encuentra el primer rol que comprende. Esto es útil cuando se introducen nuevos roles y deseas comenzar a admitirlos junto con entornos más antiguos que aún no entienden ese rol.

level​

Un elemento con el rol heading puede consultarse por cualquier nivel de encabezado getByRole('heading') o por un nivel específico usando la opción level getByRole('heading', { level: 2 }).

La opción level consulta los elementos con el rol heading que coinciden con el nivel indicado determinado por los elementos semánticos HTML <h1>-<h6> o que coinciden con el atributo aria-level.

Dado el ejemplo siguiente,

<body>
  <section>
    <h1>Heading Level One</h1>
    <h2>First Heading Level Two</h2>
    <h3>Heading Level Three</h3>
    <div role="heading" aria-level="2">Second Heading Level Two</div>
  </section>
</body>

puedes consultar el encabezado Heading Level Three usando getByRole('heading', { level: 3 }).

getByRole('heading', {level: 1})
// <h1>Heading Level One</h1>

getAllByRole('heading', {level: 2})
// [
//   <h2>First Heading Level Two</h2>,
//   <div role="heading" aria-level="2">Second Heading Level Two</div>
// ]

Si bien es posible establecer explícitamente role="heading" y el atributo aria-level en un elemento, se recomienda encarecidamente usar los elementos semánticos HTML <h1>-<h6>.

Para aprender más sobre la propiedad aria-level, consulta ARIA aria-level.

La opción level es exclusivamente aplicable al rol heading. Se producirá un error si se usa con cualquier otro rol.

value​

Un widget de rango puede consultarse por cualquier valor getByRole('spinbutton') o por un valor específico usando la opción level getByRole('spinbutton', { value: { now: 5, min: 0, max: 10, text: 'medium' } }).

Nota que no necesitas especificar todas las propiedades en value. Un subconjunto es suficiente, p.ej. getByRole('spinbutton', { value: { now: 5, text: 'medium' } }).

Dado el ejemplo siguiente,

<body>
  <section>
    <button
      role="spinbutton"
      aria-valuenow="5"
      aria-valuemin="0"
      aria-valuemax="10"
      aria-valuetext="medium"
    >
      Volume
    </button>
    <button
      role="spinbutton"
      aria-valuenow="3"
      aria-valuemin="0"
      aria-valuemax="10"
      aria-valuetext="medium"
    >
      Pitch
    </button>
  </section>
</body>

puedes consultar spinbuttons específicos con las siguientes consultas:

getByRole('spinbutton', {value: {now: 5}})
// <button>Volume</button>

getAllByRole('spinbutton', {value: {min: 0}})
// [
//   <button>Volume</button>,
//   <button>Pitch</button>
// ]

Cada propiedad especificada en value debe coincidir. Por ejemplo, si consultas {value: {min: 0, now: 3}}, aria-valuemin debe ser igual a 0 Y aria-valuenow debe ser igual a 3.

La opción value es exclusivamente aplicable a ciertos roles (consulta las páginas MDN enlazadas a continuación para roles aplicables). Se producirá un error si se usa con cualquier otro rol.

Para aprender más sobre las propiedades aria-value*, consulta: MDN aria-valuemin, MDN aria-valuemax, MDN aria-valuenow, MDN aria-valuetext.

description​

Puedes filtrar los elementos devueltos por su descripción accesible para casos donde tengas varios elementos con el mismo rol que no poseen un nombre accesible pero sí una descripción.
Esto aplicaría para elementos con rol alertdialog, donde el atributo aria-describedby se usa para describir el contenido del elemento.

Por ejemplo, en

<body>
  <ul>
    <li role="alertdialog" aria-describedby="notification-id-1">
      <div><button>Close</button></div>
      <div id="notification-id-1">You have unread emails</div>
    </li>
    <li role="alertdialog" aria-describedby="notification-id-2">
      <div><button>Close</button></div>
      <div id="notification-id-2">Your session is about to expire</div>
    </li>
  </ul>
</body>

Puedes consultar un elemento específico así:

getByRole('alertdialog', {description: 'Your session is about to expire'})

Rendimiento​

getByRole es la consulta preferida por su cercanía a la experiencia de usuario, pero los cálculos que realiza para garantizar esta confianza pueden ser costosos (especialmente en árboles DOM grandes).

Cuando el rendimiento de pruebas es crítico, puede ser conveniente sacrificar parte de esta confianza a cambio de mejoras de rendimiento.

El rendimiento de getByRole puede optimizarse configurando la opción hidden como true, evitando así costosas comprobaciones de visibilidad. Ten en cuenta que esto incluirá elementos inaccesibles en los resultados.

Otra alternativa sería sustituir getByRole por consultas más simples como getByLabelText o getByText, que son significativamente más rápidas aunque menos robustas.