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:
| Paso | Condición de comprobación | Descripción |
|---|---|---|
| 1. Attached | El elemento está montado en el árbol DOM | El elemento existe en la página |
| 2. Visible | El elemento es visible (nodisplay:noneovisibility:hidden) | El usuario puede ver el elemento |
| 3. Stable | La posición del elemento es estable (fin de la animación) | Evitar operaciones accidentales durante la animación |
| 4. Receives Events | El elemento no está cubierto por otros elementos | Asegurar que el clic pueda ser recibido por el elemento |
| 5. Enabled | El 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
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
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
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
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
await page.getByText('Doble clic para editar').dblclick();
Clic derecho
Ejemplo
await page.getByText('Menú contextual').click({ button: 'right' });
Clic con teclas combinadas
Ejemplo
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
await page.locator('canvas').click({
position: { x: 100, y: 50 },
});
locator.hover() Hover (pasar el cursor)
Ejemplo
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ón | Escenario 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
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
await page.getByLabel('Buscar').type('Playwright', { delay: 100 });
Diferencias entre fill y type
| Método | Comportamiento | Escenario aplicable |
|---|---|---|
fill() | Rellenar de una sola vez después de limpiar | La mayoría de los escenarios (recomendado) |
type() | Escritura carácter a carácter, activando cada evento de tecla | Cuando 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
await page.getByLabel('nombre de usuario').clear();
Operaciones de selección
locator.check() / uncheck() Casilla de verificación
Ejemplo
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
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
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
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 tecla | Tecla correspondiente |
|---|---|
Enter | Enter |
Escape | Esc Salir |
Tab | Tab Cambiar el foco |
Backspace | Retroceso Borrar |
Delete | Tecla Suprimir |
ArrowUp/Down/Left/Right | Teclas de dirección |
PageUp/PageDown | Teclas de avance de página |
Home/End | Inicio / Fin de línea |
Control/Alt/Shift/Meta | Teclas modificadoras |
page.keyboard.type() Escribir texto con el teclado
Ejemplo
await page.keyboard.type('Tutorial de EJEMPLO', { delay: 50 });
page.keyboard.insertText() Insertar directamente
Ejemplo
await page.keyboard.insertText('Texto insertado rápidamente');
Operaciones de ratón
Clic por coordenadas y movimiento
Ejemplo
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
await page.mouse.wheel(0, 500);
// Desplazarse hacia la izquierda 200px
await page.mouse.wheel(200, 0);
locator.dragTo() Arrastrar
Ejemplo
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étodo | Escenario 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
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
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');