Aprenda como buscar elementos da forma como os seus usuários os percebem, sem plugin nenhum.

🇺🇸 Este conteúdo também foi escrito em inglês, na DEV Community.

Durante anos, quando alguém me perguntava como encontrar elementos pelo seu papel (role, em inglês) no Cypress, a minha resposta era sempre a mesma: instale a Cypress Testing Library.

Isso não é mais necessário. Desde a versão 16.2.0, o cy.getByRole() vem com o próprio Cypress.

E aí você se pergunta: por que eu buscaria um elemento pelo seu papel?

Porque é assim que os seus usuários o encontram. Ninguém vê [data-test="save-button"] numa página. Quem enxerga vê um botão escrito “Salvar”, e quem usa um leitor de tela ouve “Salvar, botão”. Quando o teste busca a mesma coisa, ele também te avisa quando tal botão deixa de ser um botão, ou deixa de ter um nome, o que é um bug de acessibilidade de verdade.

É exatamente isso que vou demonstrar nesta pitada de Cypress. Vem comigo!

A página

Imagine a seguinte página de configurações.

<h1>Configurações</h1>

<nav aria-label="Configurações">
  <a href="/perfil">Perfil</a>
  <a href="/pagamento" aria-current="page">Pagamento</a>
</nav>

<form>
  <label for="email">E-mail</label>
  <input id="email" type="email" />

  <label>
    <input type="checkbox" />
    Quero receber a newsletter
  </label>

  <button type="submit">Salvar</button>
</form>

<div role="alert"></div>

Quando o formulário é salvo, o alerta exibe “Alterações salvas”.

O teste

describe('Configurações', () => {
  beforeEach(() => {
    cy.visit('/configuracoes')
  })

  it('salva o e-mail e a preferência da newsletter', () => {
    cy.getByRole('textbox', { name: 'E-mail' })
      .type('walmyr@example.com')
    cy.getByRole('checkbox', { name: 'Quero receber a newsletter' })
      .check()
    cy.getByRole('button', { name: 'Salvar' })
      .click()

    cy.getByRole('alert')
      .should('have.text', 'Alterações salvas')
  })
})

Agora, vamos entender o que este código faz.

Primeiro, cy.getByRole('textbox', { name: 'E-mail' }) encontra o campo de e-mail. Um <input type="email"> tem o papel textbox, e o seu nome acessível vem do <label> que aponta para ele.

Depois, o checkbox é encontrado da mesma forma. O seu nome vem do texto dentro do <label> que o envolve.

Em seguida, clicamos no botão de nome “Salvar”. O seu nome é o seu próprio conteúdo.

Por fim, cy.getByRole('alert') encontra a mensagem de status, e o .should() aguarda até que ela tenha o texto esperado. Assim como o cy.get(), o cy.getByRole() é uma query, ou seja, o Cypress o tenta novamente até que o elemento exista e todas as asserções encadeadas passem, respeitando o defaultCommandTimeout.

Perceba que não há um único seletor CSS no teste.

Obs.: Eu continuo gostando dos atributos data-test, e não estou te dizendo para substituir todos eles. Porém, quando o que importa é como o elemento é exposto para o usuário, um papel e um nome dizem muito mais do que um atributo que só existe por causa do teste.

Tudo certo até aqui? Então vamos aos detalhes.

Como o nome é comparado

A opção name aceita uma string, um número, uma expressão regular ou uma função.

Uma string precisa corresponder ao nome acessível inteiro, e a comparação diferencia maiúsculas de minúsculas (os espaços em branco são agrupados e aparados antes). Dessa forma, { name: 'Salvar' } não encontra um botão de nome “Salvar alterações”.

Quando você quiser uma correspondência parcial, use uma expressão regular.

cy.getByRole('button', { name: /^excluir/i })
  .should('have.length', 2)

O nome acessível vem do conteúdo do elemento, de um <label>, do aria-label, do aria-labelledby, do alt de uma imagem ou do title. Conteúdo marcado com aria-hidden="true" e o conteúdo gerado via CSS com ::before e ::after ficam de fora.

Limitando a busca

Você pode encadear o cy.getByRole() a qualquer comando que retorne elementos do DOM. Nesse caso, ele busca apenas dentro de tal elemento.

cy.get('nav')
  .getByRole('link')
  .should('have.length', 2)

Ele também funciona dentro do .within(), o que fica muito legível com um diálogo.

cy.getByRole('dialog', { name: 'Excluir usuário' }).within(() => {
  cy.getByRole('button', { name: 'Excluir' }).click()
})

E o checked, selected ou level?

Se você vem da Testing Library, talvez tente { checked: true } ou { level: 2 }. O cy.getByRole() não as aceita. Qualquer opção que ele não conhece lança um erro.

Em vez disso, você filtra o resultado com o .filter().

cy.getByRole('link')
  .filter('[aria-current="page"]')
  .should('have.text', 'Pagamento')

cy.getByRole('checkbox')
  .filter(':checked')
  .should('have.length', 1)

No começo eu achei um pouco estranho, mas faz sentido. O cy.getByRole() retorna todos os elementos encontrados, na ordem do documento, e o resto é o Cypress que você já conhece.

Elementos nativos primeiro

Essa é a parte de que eu mais gosto.

Por padrão, para os papéis que têm um elemento correspondente no HTML, o cy.getByRole() só encontra o elemento nativo. Ou seja, uma <div role="button"> não é encontrada pelo cy.getByRole('button').

Se a sua aplicação (ou a sua biblioteca de componentes) realmente precisar disso, use a opção native.

cy.getByRole('button', { name: 'Cancelar', native: false })
  .click()

E por que eu gosto desse padrão? Porque uma <div> fingindo ser um botão costuma ser onde moram os bugs de teclado. Ter que escrever native: false te faz parar e pensar sobre isso.

Obs.: Os papéis que não têm um elemento no HTML, como tab ou alert, são encontrados pelo atributo role sem nenhuma opção extra. Por isso o cy.getByRole('alert') funcionou no teste acima.

Obs.2: Por padrão, os elementos escondidos da árvore de acessibilidade são ignorados (o atributo hidden, aria-hidden="true", display: none ou visibility: hidden). Para incluí-los, passe { hidden: true }.

Quando ele falha

Quando nada é encontrado, o erro te mostra o que o Cypress encontrou no lugar.

Timed out retrying after 4000ms: Expected to find an accessible native element with the role "button" and name "Slavar", but never did.

Abaixo dessa mensagem, ele lista os papéis e os nomes que encontrou na página. Um erro de digitação como o de cima se resolve em segundos.

Vindo da Cypress Testing Library?

O cy.getByRole() cobre o que o findByRole() e o findAllByRole() faziam nas buscas por papel. A migração gira basicamente em torno das opções de estado.

// Antes
cy.findByRole('tab', { selected: true })
  .should('have.text', 'Pagamento')

// Depois
cy.getByRole('tab')
  .filter('[aria-selected="true"]')
  .should('have.text', 'Pagamento')

Se não sobrar nenhuma outra query da Testing Library no seu projeto, você pode remover o @testing-library/cypress das dependências, o seu import do arquivo de suporte e os seus tipos do tsconfig.json. Uma dependência a menos. 🎉

Observação: Se o seu projeto já tem um comando customizado chamado getByRole, ele agora gera um erro. Renomeie-o.

É isso aí!

Resumindo:

  • Atualize para o Cypress 16.2.0 ou superior.
  • Encontre os elementos pelo papel e pelo nome acessível, do jeito que os seus usuários os encontram.
  • Use o .filter() para os estados.
  • Prefira os elementos nativos, e use native: false apenas quando precisar.

Para todas as opções, confira a documentação oficial do cy.getByRole().

Espero que tenha gostado do conteúdo e tenha aprendido algo novo. E aí, o que achou desta pitada de Cypress? Deixa um comentário.

Quer se aprofundar?

Na Talking About Testing School, você encontra cursos práticos, em que você aprende escrevendo testes de verdade, e não assistindo tutoriais passivos.

E é Black November! Até 30 de novembro, todos os cursos e pacotes estão com 40% de desconto. Pagando com Pix, o preço já vem com o desconto, sem precisar de cupom.

Todo curso pago tem uma aula de degustação gratuita e garantia de 14 dias para reembolso, então você pode experimentar sem risco.

👉 Vem aprender com a gente na TAT School!

👋 Até a próxima e bons testes!

Deixe um comentário