Describir suites, subsuites y casos de prueba

Las descripciones claras de suites, subsuites y casos de prueba son la base de una suite de pruebas fácil de mantener. Cuando las descripciones son claras, no necesitas leer los detalles de la implementación para entender qué se está probando y cuál es el resultado esperado.

Las buenas descripciones también convierten tus pruebas en documentación viva de cómo se supone que debe comportarse el sistema.

✅ Qué hacer

Usa descripciones claras y específicas. Cada suite y subsuite debería tener un nombre que refleje el área del sistema o la funcionalidad bajo prueba. Cada caso de prueba debería dejar inmediatamente claro qué se está probando y cuál es el resultado esperado.

Enfócate en los comportamientos. Los casos de prueba enfocados en comportamientos específicos son útiles tanto para la validación como en calidad de documentación de cómo debería funcionar el sistema.

Un ejemplo bien estructurado:

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', () => { /* ... */ })
  })
})

👨‍🏫 En Cypress, describe nombra la suite (la funcionalidad bajo prueba), context nombra una subsuite (una subfuncionalidad) e it nombra cada caso de prueba. context es un alias de describe, así que se comporta de forma idéntica; usarlo para las subfuncionalidades es puramente una convención de legibilidad que hace que los dos niveles se distingan de un vistazo. Leído de arriba abajo, cada it forma una frase con sus padres: "User Authentication, Login, redirects to the dashboard when logging in with valid credentials."

❌ Qué no hacer

Evita las descripciones genéricas o vagas. Los nombres vagos de suites, subsuites y casos de prueba dificultan entender qué se está probando y por qué. Eso reduce el valor de las pruebas como documentación y hace que los fallos sean más difíciles de diagnosticar.

Evita la falta de foco en los resultados esperados. Los casos de prueba sin un resultado esperado claro, o que intentan cubrir muchos comportamientos a la vez, son menos eficaces y más difíciles de mantener.

Un ejemplo de lo que hay 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', () => { /* ... */ })
  })
})

👨‍🏫 Compara los dos ejemplos leídos como frases. "Site tests, Frontend tests, test login" no dice casi nada: ¿qué login? ¿iniciando sesión cómo? ¿esperando qué? "Miscellaneous" ya es una señal de alerta por sí sola, un cajón de sastre para las pruebas que nunca tuvieron un lugar propio. Los nombres vagos como estos fallan como documentación y, cuando uno se rompe, no te dicen nada sobre qué dejó de funcionar realmente.

Las pruebas no deben mentir

La descripción de una prueba es una promesa. Cuando la promesa y la implementación no coinciden, la prueba se vuelve documentación poco confiable y engaña a quien la lee.

✅ Qué hacer: la descripción coincide exactamente con la implementación

Haz que la descripción sea tan específica como la implementación.

Ejemplo:

// La descripción es precisa y coincide exactamente con la implementación
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()

  // La implementación verifica solo lo que la descripción promete
  cy.url().should("include", "/dashboard")
})

La verdad: La descripción dice exactamente lo que hace la prueba. Sin aserciones ocultas ni comportamientos faltantes.

❌ Qué no hacer: la descripción dice más que la implementación

Si la descripción promete algo que la prueba en realidad no verifica, quienes la lean asumirán que el comportamiento está probado cuando no lo está.

Ejemplo:

// La descripción promete tanto la redirección COMO el mensaje de bienvenida
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()

  // Solo verifica la redirección; nunca comprueba el mensaje de bienvenida
  cy.url().should("include", "/dashboard")
})

La mentira: La descripción dice que se muestra el mensaje de bienvenida, pero la implementación nunca lo verifica. La próxima persona que desarrolle puede saltarse esa aserción, pensando que ya está probada.

❌ Qué no hacer: la descripción dice menos que la implementación

Si la descripción es vaga mientras la implementación prueba muchos comportamientos, quien lee no sabe qué está realmente cubierto.

Ejemplo:

// La descripción es vaga
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()

  // La implementación en realidad verifica la redirección, el mensaje de bienvenida,
  // el token de sesión Y el correo electrónico
  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")
})

La mentira: La descripción no dice qué se está probando realmente. Alguien que mantenga esta prueba puede no darse cuenta de que los cuatro comportamientos están cubiertos, o quitar por accidente una aserción específica de un comportamiento pensando que es redundante.

Resumen

Las descripciones de prueba claras y específicas que coinciden con la implementación son la base de una suite de pruebas confiable y fácil de mantener. Cuando las descripciones son precisas y están alineadas con lo que la prueba verifica de verdad (sin prometer de más ni quedarse cortas), se convierten en documentación viva que refleja con exactitud el comportamiento del sistema. Eso hace de las pruebas una herramienta confiable para entender cómo debería funcionar el software, ayuda a los equipos a mantener la suite sin sorpresas y asegura que los fallos sean más fáciles de diagnosticar y de resolver.

Muéstrale al mundo lo que aprendiste 🌎

Para mostrarle a tu red profesional lo que aprendiste en esta lección, publica lo siguiente en LinkedIn.

Estoy haciendo el curso "Elementos de Diseño de Pruebas Automatizadas" con @Walmyr Lima e Silva Filho en la escuela @Talking About Testing, donde aprendí a escribir descripciones de prueba claras y específicas que además funcionan como documentación viva. #TalkingAboutTesting #TATSchool #ElementsOfAutomatedTestDesign #TestAutomation #TestDesign

👨‍🏫 No olvides mencionarme en tu publicación. Aquí está mi perfil de LinkedIn.