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: falseapenas 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.
- Está começando com Cypress? Comece pelo Cypress Básico, que é gratuito.
- Quer encontrar problemas de acessibilidade com Cypress? O Bruno Pulis te ensina como no curso As 6 Falhas de Acessibilidade Mais Comuns, com Cypress e axe-core, e passa pela norma nos cursos WCAG 2.2 Nível A e Nível AA. Os três estão no Pacote de Acessibilidade.
- Quer dominar o Cypress? O Pacote Cypress Mastery tem seis cursos de Cypress, dos fundamentos aos testes agênticos com Cypress Tap.
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!