Descrevendo suítes, subsuítes e casos de teste

Descrições claras de suítes de teste, subsuítes e casos de teste são a base de uma suíte de testes de fácil manutenção. Quando as descrições são claras, você não precisa ler os detalhes de implementação para entender o que está sendo testado e qual é o resultado esperado.

Boas descrições também transformam os seus testes em documentação viva de como o sistema deve se comportar.

✅ O que fazer

Use descrições claras e específicas. Cada suíte e subsuíte deve ter um nome que reflita a área do sistema ou a funcionalidade sob teste. Cada caso de teste deve deixar imediatamente claro o que está sendo testado e qual é o resultado esperado.

Foque em comportamentos. Casos de teste que focam em comportamentos específicos são úteis tanto para validação quanto como documentação de como o sistema deve funcionar.

Um exemplo bem estruturado:

describe('User Authentication', () => {
  context('Login', () => {
    it('redirects to the dashboard when logging in with valid credentials', () => { /* ... */ })
    it('shows an error message when logging in with an incorrect password', () => { /* ... */ })
  })

  context('Registration', () => {
    it('creates an account and sends a confirmation email when registering with valid information', () => { /* ... */ })
    it('shows an error message when registering with an email already in use', () => { /* ... */ })
  })
})

👨‍🏫 No Cypress, describe nomeia a suíte (a funcionalidade sob teste), context nomeia uma subsuíte (uma subfuncionalidade) e it nomeia cada caso de teste. context é um alias de describe, então se comporta de forma idêntica; usá-lo para subfuncionalidades é puramente uma convenção de legibilidade que torna os dois níveis distinguíveis num relance. Lido de cima para baixo, cada it forma uma frase com os seus pais: "User Authentication, Login, redirects to the dashboard when logging in with valid credentials."

❌ O que não fazer

Evite descrições genéricas ou vagas. Nomes vagos de suíte, subsuíte e caso de teste dificultam entender o que está sendo testado e por quê. Isso reduz o valor dos testes como documentação e torna as falhas mais difíceis de diagnosticar.

Evite a falta de foco nos resultados esperados. Casos de teste sem um resultado esperado claro, ou que tentam cobrir muitos comportamentos de uma vez, são menos eficazes e mais difíceis de manter.

Um exemplo do que evitar:

describe('Site tests', () => {
  context('Frontend tests', () => {
    it('test login', () => { /* ... */ })
    it('test registration', () => { /* ... */ })
  })

  context('Miscellaneous', () => {
    it('click all the buttons', () => { /* ... */ })
    it('submit random forms', () => { /* ... */ })
  })
})

👨‍🏫 Compare os dois exemplos lidos como frases. "Site tests, Frontend tests, test login" não diz quase nada: qual login? logando como? esperando o quê? "Miscellaneous" já é um sinal de alerta por si só, um balde para testes que nunca receberam um lar de verdade. Nomes vagos como esses falham como documentação e, quando um deles quebra, não dizem nada sobre o que de fato parou de funcionar.

Testes não devem mentir

A descrição de um teste é uma promessa. Quando a promessa e a implementação discordam, o teste se torna documentação não confiável e engana quem o lê.

✅ O que fazer: descrição corresponde exatamente à implementação

Torne a descrição tão específica quanto a implementação.

Exemplo:

// Description is precise and matches implementation exactly
it("redirects to the dashboard when logging in with valid credentials", () => {
  cy.get('[data-testid="email"]').type("user@example.com")
  cy.get('[data-testid="password"]').type("password123")
  cy.get('[data-testid="login-button"]').click()

  // Implementation checks only what the description promises
  cy.url().should("include", "/dashboard")
})

A verdade: A descrição diz exatamente o que o teste faz. Sem asserções ocultas, sem comportamentos faltando.

❌ O que não fazer: descrição diz mais do que a implementação

Se a descrição promete algo que o teste não verifica de fato, os leitores presumem que o comportamento está testado quando não está.

Exemplo:

// Description promises both redirect AND welcome message
it("redirects to the dashboard and displays a welcome message when logging in with valid credentials", () => {
  cy.get('[data-testid="email"]').type("user@example.com")
  cy.get('[data-testid="password"]').type("password123")
  cy.get('[data-testid="login-button"]').click()

  // Only verifies the redirect; never checks for the welcome message
  cy.url().should("include", "/dashboard")
})

A mentira: A descrição diz que a mensagem de boas-vindas é exibida, mas a implementação nunca a verifica. A próxima pessoa desenvolvedora pode pular a adição dessa asserção, achando que já está testada.

❌ O que não fazer: descrição diz menos do que a implementação

Se a descrição é vaga enquanto a implementação testa muitos comportamentos, os leitores não sabem o que está realmente coberto.

Exemplo:

// Description is vague
it("logs in with valid credentials", () => {
  cy.get('[data-testid="email"]').type("user@example.com")
  cy.get('[data-testid="password"]').type("password123")
  cy.get('[data-testid="login-button"]').click()

  // Implementation actually checks redirect, welcome message, session token, AND email
  cy.url().should("include", "/dashboard")
  cy.get('[data-testid="welcome-message"]').should("be.visible")
  cy.window().its("localStorage.sessionToken").should("exist")
  cy.get('[data-testid="user-email"]').should("contain", "user@example.com")
})

A mentira: A descrição não diz o que está de fato sendo testado. Alguém que mantenha este teste pode não perceber que os quatro comportamentos estão cobertos, ou acidentalmente remover uma asserção específica de comportamento achando que é redundante.

Resumo

Descrições de teste claras e específicas que correspondem à implementação são a base de uma suíte de testes de fácil manutenção e confiável. Quando as descrições são precisas e alinhadas com o que o teste de fato verifica (sem prometer demais nem de menos), elas se tornam documentação viva que reflete com precisão o comportamento do sistema. Isso torna os testes uma ferramenta confiável para entender como o software deve funcionar, ajuda os times a manter a suíte sem surpresas e garante que as falhas sejam mais fáceis de diagnosticar e resolver.

Mostre ao mundo o que você aprendeu 🌎

Para mostrar à sua rede profissional o que você aprendeu nesta aula, publique o seguinte no LinkedIn.

Estou fazendo o curso "Elementos de Design de Testes Automatizados" com @Walmyr Lima e Silva Filho na @Talking About Testing School, onde aprendi a escrever descrições de teste claras e específicas que servem como documentação viva. #TalkingAboutTesting #TATSchool #ElementsOfAutomatedTestDesign #TestAutomation #TestDesign

👨‍🏫 Lembre-se de me marcar na sua publicação. Aqui está o meu perfil no LinkedIn.