Playwright Assertions

Este capítulo presenta de forma exhaustiva el sistema de aserciones de Playwright, incluyendo el uso de aserciones de reintento automático, aserciones generales y aserciones suaves.


Qué son las aserciones

Una aserción (Assertion) se utiliza para verificar si el resultado esperado de una prueba coincide con el resultado real.

Playwright ofrece dos tipos de aserciones:Aserciones generales(basadas en Jest) yAserciones de reintento automático(exclusivas de Playwright).


Aserciones de reintento automático vs aserciones generales

Aserciones de reintento automático (Async Matchers)

Las aserciones específicas de web de Playwright se reintentan automáticamente hasta que la condición se cumpla o se agote el tiempo de espera; se debe usarawait。

Ejemplo

// Aserción de reintento automático: espera a que se cumpla la condición
await expect(page.getByText('EJEMPLO')).toBeVisible();

Aserciones generales

Se utilizan para comparar valores no específicos de web; no se reintentan automáticamente.

Ejemplo

// Aserción general: se ejecuta inmediatamente, sin esperar
expect(1 + 1).toBe(2);
expect('hello').toContain('ell');
expect(true).toBeTruthy();
TipoReintento automático¿Requiere await?Casos de uso
Aserciones de reintento automáticoSíObligatorioawaitElementos de página, URL, títulos y otro contenido específico de la web
Aserciones generalesnoNoValores de JavaScript como variables comunes, arrays, objetos, etc.

Aserciones a nivel de página

Ejemplo

// Aserción del título de la página
await expect(page).toHaveTitle('EJEMPLO: no solo tecnología, ¡también sueños!');
await expect(page).toHaveTitle(/EJEMPLO/);

// Aserción de la URL de la página
await expect(page).toHaveURL('https://www.example.com/');
await expect(page).toHaveURL(/ejemplo\.com/);

Aserciones de visibilidad

Ejemplo

const btn = page.getByRole('button', { name: 'Enviar' });

// El elemento es visible
await expect(btn).toBeVisible();

// El elemento no es visible
await expect(btn).toBeHidden();

// El elemento existe en el DOM (pero no necesariamente visible)
await expect(btn).toBeAttached();

// El elemento es visible dentro del viewport
await expect(btn).toBeInViewport();

Aserciones de texto y valor

Ejemplo

const heading = page.getByRole('heading', { name: 'EJEMPLO' });

// El contenido de texto del elemento coincide exactamente
await expect(heading).toHaveText('Aprender no es solo tecnología, ¡también sueños!');

// El contenido de texto del elemento contiene una subcadena
await expect(heading).toContainText('tecnología');

// El valor actual del input
await expect(page.getByLabel('nombre de usuario')).toHaveValue('ejemplo_user');

// El contenido del elemento está vacío
await expect(page.getByTestId('error-msg')).toBeEmpty();

Aserciones de estado

Ejemplo

const checkbox = page.getByLabel('Acepto los términos');
const input = page.getByLabel('correo electrónico');

// El elemento está habilitado
await expect(input).toBeEnabled();

// El elemento está deshabilitado
await expect(input).toBeDisabled();

// El elemento es editable
await expect(input).toBeEditable();

// La casilla de verificación está marcada
await expect(checkbox).toBeChecked();

// El elemento tiene el foco
await expect(input).toBeFocused();

Aserciones de atributos

Ejemplo

const element = page.locator('.ejemplo-logo');

// Aserción de atributos del DOM
await expect(element).toHaveAttribute('src', '/static/images/logo.png');

// Solo se verifica que el atributo exista
await expect(element).toHaveAttribute('alt');

// Aserción de clase CSS
await expect(element).toHaveClass('logo-primary');

// Aserción de valor de propiedad CSS
await expect(element).toHaveCSS('display', 'block');

// Aserción del ID del elemento
await expect(element).toHaveId('main-logo');

// Nombre accesible (accessible name)
await expect(page.getByRole('button')).toHaveAccessibleName('Enviar');

Aserciones de cantidad

Ejemplo

// Número de elementos coincidentes
const items = page.getByRole('listitem');
await expect(items).toHaveCount(5);

// Usado junto con filter
const activeItems = page.getByRole('listitem').filter({ hasText: 'Activado' });
await expect(activeItems).toHaveCount(3);

Referencia rápida de aserciones generales

MétodoDescripciónEjemplo
toBe(value)Igualdad estricta (===)expect(x).toBe(42)
toEqual(value)Igualdad profundaexpect(obj).toEqual({ a: 1 })
toContain(item)Inclusión en array/cadenaexpect(arr).toContain('a')
toBeTruthy()El valor es verdadero (truthy)expect(x).toBeTruthy()
toBeFalsy()El valor es falso (falsy)expect(x).toBeFalsy()
toBeNull()El valor es nullexpect(x).toBeNull()
toBeGreaterThan(n)Mayor que nexpect(x).toBeGreaterThan(10)
toBeLessThan(n)Menor que nexpect(x).toBeLessThan(100)
toHaveLength(n)Longitud del arrayexpect(arr).toHaveLength(3)

Aserciones suaves con expect.soft()

Cuando una aserción normal falla, la prueba se detiene inmediatamente.

Aserciones suavesNo se detienen tras un fallo; continúan ejecutando el código posterior y al final de la prueba se informan todos los fallos de forma conjunta.

Ejemplo

test('Verificación de múltiples campos en el formulario', async ({ page }) => {
  await page.goto('https://example.com/form');

  // Aserción suave: un fallo no detiene la prueba
  await expect.soft(page.getByLabel('nombre de usuario')).toBeVisible();
  await expect.soft(page.getByLabel('contraseña')).toBeVisible();
  await expect.soft(page.getByLabel('correo electrónico')).toBeVisible();
  await expect.soft(page.getByRole('button', { name: 'Registrarse' })).toBeEnabled();

  // Si alguna de las aserciones anteriores falla, se continúa verificando y al final se informa de forma conjunta
});

Se usa al probar páginas de formulariosexpect.soft()Permite detectar todos los campos faltantes de una sola vez, sin tener que corregir uno para ver el siguiente problema. Esto mejora considerablemente la eficiencia de la depuración.


Tiempo de espera de las aserciones

Las aserciones de reintento automático tienen un tiempo de espera predeterminado de 5 segundos; se puede personalizar en el archivo de configuración o en una aserción individual:

Ejemplo

// Tiempo de espera para una sola aserción (en milisegundos)
await expect(page.getByText('Cargando...')).toBeHidden({ timeout: 10000 });

// Configuración global en el archivo de configuración
// playwright.config.ts:
// export default defineConfig({
//   expect: { timeout: 10000 },
// });
Otras extensiones