Operaciones de Playwright (Actions)

Este capítulo presenta las operaciones de navegación y clic en Playwright, así como el mecanismo de espera automática subyacente a las operaciones.


¿Qué es Action?

Action (operación) se utiliza en Playwright parasimular el comportamiento del usuariocomo hacer clic en botones, escribir texto o seleccionar listas desplegables.

Antes de ejecutar cada Action, Playwright espera automáticamente a que el elemento objetivo se vuelvaun estado operable。


Comprobación de Actionability (accionabilidad)

Antes de ejecutar cada operación, Playwright realiza una serie de comprobaciones sobre el elemento objetivo:

PasoCondición de comprobaciónDescripción
1. AttachedEl elemento está montado en el árbol DOMEl elemento existe en la página
2. VisibleEl elemento es visible (nodisplay:noneovisibility:hidden)El usuario puede ver el elemento
3. StableLa posición del elemento es estable (fin de la animación)Evitar operaciones accidentales durante la animación
4. Receives EventsEl elemento no está cubierto por otros elementosAsegurar que el clic pueda ser recibido por el elemento
5. EnabledEl elemento no está deshabilitado (nodisabled)El usuario puede interactuar con él

Si no se supera cualquiera de los pasos, Playwright esperará y reintentará hasta que se agote el tiempo de espera.

Estas 5 comprobaciones las realiza Playwright automáticamente; no es necesario escribir ningún código de espera adicional. Esta es también la razón fundamental por la que Playwright puede reducir drásticamente las pruebas inestables.


Operación forzada { force: true }

A veces necesitas omitir las comprobaciones de accionabilidad, por ejemplo, hacer clic en un botón oculto por un overlay o probar el estado de un elemento invisible.

Ejemplo

// Clic forzado, omitir todas las comprobaciones de operabilidad
await page.getByRole('button', { name: 'Enviar' }).click({ force: true });

force: truees una operación que los usuarios reales no pueden realizar y, en la gran mayoría de los casos, no debe usarse. Si tu prueba necesitaforce: true, primero verifica si hay un problema de diseño de interacción.


Operaciones de navegación

page.goto() Navegación de página

Ejemplo

// Navegación básica
await page.goto('https://www.example.com/');

// Esperar DOMContentLoaded (estructura de la página cargada)
await page.goto('https://www.example.com/', { waitUntil: 'domcontentloaded' });

// Esperar a que la red esté inactiva (todos los datos asíncronos cargados)
await page.goto('https://www.example.com/', {
  waitUntil: 'networkidle',    // Red inactiva
  timeout: 60000,              // Tiempo de espera 60 segundos
  referer: 'https://google.com', // Origen del Referer
});

page.goBack() / goForward() / reload()

Ejemplo

// Retroceder una página
await page.goBack();

// Avanzar una página
await page.goForward();

// Recargar la página
await page.reload();

Operaciones de clic

locator.click() Clic simple

Ejemplo

// Clic básico
await page.getByRole('button', { name: 'Iniciar sesión' }).click();

// Clic con opciones
await page.getByRole('button', { name: 'Iniciar sesión' }).click({
  button: 'left',     // Botón del ratón: 'left' | 'right' | 'middle'
  clickCount: 1,      // Número de clics
  delay: 100,         // Retraso entre pulsar y soltar (milisegundos)
  timeout: 5000,      // Tiempo de espera
  modifiers: [],      // Teclas modificadoras: ['Alt', 'Control', 'Meta', 'Shift']
});

locator.dblclick() Doble clic

Ejemplo

// Doble clic en el elemento
await page.getByText('Doble clic para editar').dblclick();

Clic derecho

Ejemplo

// Clic derecho (abre el menú contextual)
await page.getByText('Menú contextual').click({ button: 'right' });

Clic con teclas combinadas

Ejemplo

// Ctrl + clic (selección múltiple)
await page.getByRole('option').click({ modifiers: ['Control'] });

// Shift + clic (selección de rango / abrir en ventana nueva)
await page.getByRole('link').click({ modifiers: ['Shift'] });

Clic por coordenadas

Ejemplo

// Clic en una posición específica del elemento (relativa a la esquina superior izquierda)
await page.locator('canvas').click({
  position: { x: 100, y: 50 },
});

locator.hover() Hover (pasar el cursor)

Ejemplo

// Pasar el ratón (activa el efecto hover o el menú desplegable)
await page.getByRole('link', { name: 'Tutorial' }).hover();

// Tras pasar el ratón, haga clic en el submenú emergente
await page.getByRole('link', { name: 'Tutorial de Playwright' }).click();

Diferencias de escenario entre clic y hover

OperaciónEscenario aplicable
click()Clic en botones, navegación de enlaces, conmutación de casillas de verificación
dblclick()Entrar en modo de edición, doble clic para seleccionar texto
click({ button: 'right' })Abrir el menú contextual nativo del navegador
hover()Activar menús desplegables al pasar el cursor, información sobre herramientas (tooltip)
click({ position })Operaciones en Canvas, interacción con gráficos personalizados

Operaciones de entrada de texto

locator.fill() Rellenar después de limpiar

fill()Primero limpia el campo de entrada y luego rellena el nuevo valor; es el método más común y recomendado para operaciones de entrada.

Ejemplo

// Vaciar el campo de entrada y escribir un nuevo valor
await page.getByLabel('nombre de usuario').fill('ejemplo_user');
await page.getByLabel('contraseña').fill('secure_password');
await page.getByPlaceholder('Buscar tutorial de EJEMPLO').fill('Playwright');

locator.type() Escritura carácter a carácter

type()Introduce caracteres uno a uno, simulando pulsaciones de teclado reales; se puede configurar un intervalo entre cada tecla.

Ejemplo

// Escribir carácter por carácter (con un retraso de 100 ms entre caracteres)
await page.getByLabel('Buscar').type('Playwright', { delay: 100 });

Diferencias entre fill y type

MétodoComportamientoEscenario aplicable
fill()Rellenar de una sola vez después de limpiarLa mayoría de los escenarios (recomendado)
type()Escritura carácter a carácter, activando cada evento de teclaCuando se necesita activar autocompletado de entrada o búsqueda en tiempo real

Se usa en la mayoría de los casos.fill()Eso es todo. Solo es necesario usarlo cuando el campo de entrada tiene búsqueda en tiempo real (eventos keydown/keyup).type()。

locator.clear() Limpiar

Ejemplo

// Limpiar el contenido del campo de entrada
await page.getByLabel('nombre de usuario').clear();

Operaciones de selección

locator.check() / uncheck() Casilla de verificación

Ejemplo

// Marcar la casilla de verificación
await page.getByLabel('Acepto el acuerdo de servicio').check();

// Desmarcar
await page.getByLabel('Recibir notificaciones por correo').uncheck();

// Establecer el estado de marcado
await page.getByLabel('Recuérdame').setChecked(true);   // Confirmar como marcado
await page.getByLabel('Recuérdame').setChecked(false);  // Confirmar como desmarcado

locator.selectOption() Selección en lista desplegable

Ejemplo

// Seleccionar mediante el atributo value
await page.getByLabel('ciudad').selectOption('beijing');

// Seleccionar mediante el texto visible
await page.getByLabel('ciudad').selectOption({ label: 'Shanghái' });

// Lista desplegable de selección múltiple
await page.getByLabel('etiquetas de interés').selectOption([
  { label: 'programación' },
  { value: 'design' },
]);

// Seleccionar por índice (elemento 0, elemento 2)
await page.getByLabel('ciudad').selectOption({ index: 0 });

Operaciones de teclado

page.keyboard.press() Pulsar tecla

Ejemplo

// Pulsar y soltar Enter
await page.keyboard.press('Enter');

// Seleccionar todo (Control + A)
await page.keyboard.press('Control+A');

// Copiar y pegar
await page.keyboard.press('Control+C');
await page.keyboard.press('Control+V');

// Deshacer
await page.keyboard.press('Control+Z');

page.keyboard.down() / up() Presionar / soltar

Ejemplo

// Mantener presionada la tecla Shift sin soltar
await page.keyboard.down('Shift');

// Durante este tiempo presionar otras teclas (equivale a mantener Shift y presionar otras teclas)
await page.keyboard.press('ArrowRight');  // Shift + flecha derecha (seleccionar texto)
await page.keyboard.press('ArrowRight');

// Soltar Shift
await page.keyboard.up('Shift');

Nombres de teclas especiales

Nombre de teclaTecla correspondiente
EnterEnter
EscapeEsc Salir
TabTab Cambiar el foco
BackspaceRetroceso Borrar
DeleteTecla Suprimir
ArrowUp/Down/Left/RightTeclas de dirección
PageUp/PageDownTeclas de avance de página
Home/EndInicio / Fin de línea
Control/Alt/Shift/MetaTeclas modificadoras

page.keyboard.type() Escribir texto con el teclado

Ejemplo

// Escribir texto en el elemento enfocado
await page.keyboard.type('Tutorial de EJEMPLO', { delay: 50 });

page.keyboard.insertText() Insertar directamente

Ejemplo

// Insertar texto directamente en la posición enfocada (sin simular eventos de teclado, es lo más rápido)
await page.keyboard.insertText('Texto insertado rápidamente');

Operaciones de ratón

Clic por coordenadas y movimiento

Ejemplo

// Hacer clic en las coordenadas de la ventana (100, 200)
await page.mouse.click(100, 200);

// Hacer doble clic en las coordenadas
await page.mouse.dblclick(100, 200);

// Mover el mouse a las coordenadas
await page.mouse.move(100, 200);

// Presionar / soltar
await page.mouse.down();
await page.mouse.up();

Rueda del ratón

Ejemplo

// Desplazarse hacia abajo 500px
await page.mouse.wheel(0, 500);

// Desplazarse hacia la izquierda 200px
await page.mouse.wheel(200, 0);

locator.dragTo() Arrastrar

Ejemplo

// Arrastrar el elemento A hasta el elemento B
const source = page.getByText('Arrástrame');
const target = page.getByTestId('drop-zone');
await source.dragTo(target);

// Arrastre con opciones
await source.dragTo(target, {
  sourcePosition: { x: 0, y: 0 },   // Punto de inicio del arrastre (relativo al elemento de origen)
  targetPosition: { x: 10, y: 10 }, // Punto de destino del arrastre (relativo al elemento de destino)
});

Elección entre page.mouse y locator.click

MétodoEscenario aplicable
locator.click()Hacer clic en elementos de la página (la gran mayoría de escenarios)
page.mouse.click()Hacer clic en coordenadas específicas (escenarios sin DOM como Canvas, gráficos, etc.)

Subida de archivos

locator.setInputFiles() Archivo único / múltiples archivos

Ejemplo

// Subir un solo archivo
await page
  .getByLabel('Seleccionar archivo')
  .setInputFiles('path/to/document.pdf');

// Subir múltiples archivos
await page
  .getByLabel('Seleccionar archivos')
  .setInputFiles([
    'path/to/file1.png',
    'path/to/file2.png',
  ]);

// Limpiar archivos seleccionados
await page.getByLabel('Seleccionar archivo').setInputFiles([]);

La ruta del archivo es relativa al directorio de trabajo actual (raíz del proyecto).


Descarga de archivos

Ejemplo

// Comenzar a esperar el evento de descarga (debe llamarse antes de la operación que activa la descarga)
const downloadPromise = page.waitForEvent('download');

// Ejecutar la operación que activa la descarga
await page.getByRole('button', { name: 'Descargar informe' }).click();

// Esperar a que se complete la descarga
const download = await downloadPromise;

// Obtener el nombre de archivo sugerido
console.log(download.suggestedFilename());

// Guardar en la ruta especificada
await download.saveAs('downloads/report.pdf');
Otras extensiones