Ir para o conteúdo principal

ByRole

[Tradução Beta Não Oficial]

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? 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

Consulta elementos com a função (role) especificada (e também aceita um TextMatch). Funções padrão são consideradas, por exemplo, <button /> tem a função button sem definir explicitamente o atributo role. Aqui você pode ver uma tabela de elementos HTML com suas funções padrão e desejadas.

Note que definir um atributo role e/ou aria-* que corresponda à semântica implícita da ARIA é desnecessário e não recomendado, pois essas propriedades já são definidas pelo navegador. Não devemos usar atributos role e aria-* de forma conflitante com as semânticas descritas. Por exemplo, um elemento button não pode ter o atributo role como heading, pois o elemento button tem características padrão que conflitam com a função heading.

As funções são comparadas literalmente por igualdade de string, sem herdar da hierarquia de funções da ARIA. Portanto, consultar uma função superclasse como checkbox não incluirá elementos com uma subclasse de função como switch.

Você pode consultar o(s) elemento(s) retornado(s) pelo seu nome ou descrição acessível. O nome acessível, em casos simples, equivale ao rótulo de um elemento de formulário, ao conteúdo de texto de um botão ou ao valor do atributo aria-label. Isso permite consultar um elemento específico quando múltiplos elementos com mesma função estão presentes. Para um guia detalhado, consulte "O que é um nome acessível?" da TPGi. Se você busca apenas um elemento com getByText('The name'), frequentemente é melhor usar getByRole(expectedRole, { name: 'The name' }). A consulta por nome acessível não substitui outras como *ByAlt ou *ByTitle. Embora o nome acessível possa ser igual a esses atributos, ele não substitui sua funcionalidade. Por exemplo, <img aria-label="fancy image" src="fancy.jpg" /> será retornado por getByRole('img', { name: 'fancy image' }). Contudo, a imagem não exibirá sua descrição se fancy.jpg não carregar. Cabe a você decidir se deseja verificar essa funcionalidade em seu teste.

[tipo de input password]

Infelizmente, a especificação define que <input type="password" /> não tem função implícita. Isso significa que para consultar esse tipo de elemento precisamos recorrer a uma consulta menos poderosa como ByLabelText.

Opções​

hidden​

Se você definir hidden como true, elementos normalmente excluídos da árvore de acessibilidade também serão considerados na consulta. O comportamento padrão segue https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion, exceto para role="none" e role="presentation", que sempre são considerados na consulta. Por exemplo, em

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

getByRole('button') retornaria apenas o botão Close dialog. Para verificar o botão Open dialog, você precisaria usar getAllByRole('button', { hidden: true }).

O valor padrão de hidden pode ser configurado.

selected​

Você pode filtrar os elementos retornados pelo estado de seleção usando selected: true ou selected: false.

Por exemplo em

<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>

você pode obter a aba "Nativa" chamando getByRole('tab', { selected: true }). Para saber mais sobre o estado selecionado e quais elementos podem ter esse estado, veja ARIA aria-selected.

busy​

Você pode filtrar os elementos retornados pelo estado de ocupação definindo busy: true ou busy: false.

Por exemplo em

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

você pode obter o alerta "Falha no login" chamando getByRole('alert', { busy: false }). Para saber mais sobre o estado de ocupação, veja ARIA aria-busy e o atributo aria-busy na MDN.

checked​

Você pode filtrar os elementos retornados pelo estado de seleção definindo checked: true ou checked: false.

Por exemplo em

<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>

você pode obter a opção "Açúcar" chamando getByRole('checkbox', { checked: true }). Para saber mais sobre o estado de seleção e quais elementos podem ter esse estado, veja ARIA aria-checked.

Nota

Checkboxes têm um estado "misto", que não é considerado selecionado nem não selecionado (detalhes aqui).

current​

Você pode filtrar os elementos retornados pelo estado atual definindo current: boolean | string. Note que nenhum atributo aria-current corresponderá a current: false, já que false é o valor padrão para aria-current.

Por exemplo em

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

você pode obter o link "👍" chamando getByRole('link', { current: 'page' }) e o "👎" chamando getByRole('link', { current: false }). Para saber mais sobre o estado atual, veja ARIA aria-current.

pressed​

Botões podem ter um estado de pressionado. Você pode filtrar os elementos retornados por esse estado definindo pressed: true ou pressed: false.

Por exemplo em

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

você pode obter o botão "👍" chamando getByRole('button', { pressed: true }). Para saber mais sobre o estado de pressionado, veja ARIA aria-pressed.

suggest​

Você pode desativar a capacidade de lançar sugestões para uma consulta específica definindo este valor como false.
Definir como true lançará sugestões para a consulta específica.

expanded​

Você pode filtrar os elementos retornados pelo estado expandido definindo expanded: true ou expanded: false.

Por exemplo em

<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>

você pode obter o link "Item de Menu Expansível" chamando getByRole('link', { expanded: false }). Para saber mais sobre o estado expandido e quais elementos podem ter esse estado, veja ARIA aria-expanded.

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

const dialogContainer = screen.getByRole('dialog')

queryFallbacks​

Por padrão, assume-se que a primeira função (role) de cada elemento é suportada, então apenas a primeira função pode ser consultada. Se você precisar consultar um elemento por qualquer uma de suas funções alternativas, pode usar queryFallbacks: true.

Por exemplo, getByRole('switch') sempre corresponderia a <div role="switch checkbox" /> porque é a primeira função, enquanto getByRole('checkbox') não corresponderia. Porém, getByRole('checkbox', { queryFallbacks: true }) habilitaria todas as funções alternativas e assim corresponderia ao mesmo elemento.

Um elemento não tem múltiplas funções em um determinado ambiente. Ele tem uma única função. Múltiplas funções no atributo são avaliadas da esquerda para a direita até que o ambiente encontre a primeira função que ele entende. Isso é útil quando novas funções são introduzidas e você quer suportá-las enquanto mantém compatibilidade com ambientes antigos que ainda não entendem essa função.

level​

Um elemento com a função heading pode ser consultado por qualquer nível de cabeçalho usando getByRole('heading') ou por um nível específico usando a opção level: getByRole('heading', { level: 2 }).

A opção level consulta elemento(s) com a função heading que correspondam ao nível indicado, determinado pelos elementos semânticos HTML <h1>-<h6> ou pelo atributo aria-level.

Dado o exemplo abaixo,

<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>

você pode consultar o cabeçalho 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>
// ]

Embora seja possível definir explicitamente role="heading" e o atributo aria-level em um elemento, é altamente recomendado usar os cabeçalhos semânticos HTML <h1>-<h6>.

Para saber mais sobre a propriedade aria-level, consulte ARIA aria-level.

A opção level é aplicável apenas à função heading. Um erro será lançado se usada com qualquer outra função.

value​

Um widget de intervalo pode ser consultado por qualquer valor com getByRole('spinbutton') ou por um valor específico usando a opção level: getByRole('spinbutton', { value: { now: 5, min: 0, max: 10, text: 'medium' } }).

Note que você não precisa especificar todas as propriedades em value. Um subconjunto é suficiente, por exemplo: getByRole('spinbutton', { value: { now: 5, text: 'medium' } }).

Dado o exemplo abaixo,

<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>

você pode consultar spinbutton(s) específicos com as seguintes consultas:

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

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

Toda propriedade especificada em value deve corresponder. Por exemplo, se você consultar {value: {min: 0, now: 3}}, aria-valuemin deve ser igual a 0 E aria-valuenow deve ser igual a 3.

A opção value é aplicável apenas a certas funções (verifique as páginas da MDN vinculadas abaixo). Um erro será lançado se usada com qualquer outra função.

Para saber mais sobre as propriedades aria-value*, consulte:
MDN aria-valuemin,
MDN aria-valuemax,
MDN aria-valuenow,
MDN aria-valuetext.

description​

Você pode filtrar os elementos retornados por sua descrição acessível para casos onde existem vários elementos com a mesma função que não possuem um nome acessível, mas têm uma descrição.
Isso ocorre com elementos que usam a função alertdialog, onde o atributo aria-describedby é usado para descrever o conteúdo do elemento.

Por exemplo em

<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>

Você pode consultar um elemento específico assim

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

Desempenho​

getByRole é a consulta mais recomendada por se assemelhar mais à experiência do usuário, porém os cálculos necessários para fornecer essa confiança podem ser custosos (especialmente com grandes árvores DOM).

Quando o desempenho dos testes é crítico, pode ser vantajoso trocar parte dessa confiança por melhor desempenho.

O desempenho do getByRole pode ser melhorado definindo a opção hidden como true, evitando assim verificações de visibilidade custosas. Note que isso incluirá elementos inacessíveis no resultado.

Outra alternativa é substituir getByRole por consultas mais simples como getByLabelText e getByText, que podem ser significativamente mais rápidas, embora sejam alternativas menos robustas.