Conceptos básicos de operaciones de página de Playwright

En este capítulo, conoceremos cómo Playwright interactúa realmente con las páginas web y las API de operaciones de página más utilizadas.

Navegación de página

La navegación de página es la operación más común. Playwright proporciona varias API para abrir, actualizar y controlar la transición de páginas.

1. Abrir página web (page.goto）

await page.goto('https://example.com');

Parámetros comunes:

  • url: la dirección a visitar
  • timeout: tiempo de espera, por defecto 30 segundos

  • waitUntil: condición de espera para la carga de la página

    • 'load': esperarloadevento (cuando la página y todos los recursos se han cargado por completo)
    • 'domcontentloaded': esperar a que el contenido del DOM se cargue por completo
    • 'networkidle': esperar a que la red esté inactiva

Ejemplo

await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

2. Actualizar página (page.reload）

Actualiza la página actual.

await page.reload({ waitUntil: 'networkidle' });

3. Adelante / Atrás (page.goBack / page.goForward）

Simula los botones de adelante y atrás del navegador.

await page.goto('https://example.com');
await page.goto('https://playwright.dev');

await page.goBack();   // 返回 example.com
await page.goForward(); // 前进到 playwright.dev

4. Esperar la carga de la página

A veces es necesario esperar explícitamente a que la página cargue un elemento. Playwright proporciona un mecanismo de espera inteligente.

await page.waitForLoadState('networkidle'); // 等待网络空闲
await page.waitForSelector('#main-content'); // 等待元素出现

Localización de elementos

Para interactuar con la página, primero hay que localizar el elemento objetivo. Playwright ofrece una variedad de selectores.

1. Selector CSS

Es el método de localización más utilizado y es coherente con el desarrollo frontend.

await page.click('#login-button');     // 通过 id
await page.click('.btn-primary');      // 通过 class
await page.click('form > button');     // 通过层级关系

2. Selector XPath

Localiza elementos mediante expresiones XPath.

await page.click('//button[text()="登录"]');
await page.click('//input[@name="username"]');

XPath es más flexible, pero menos legible, por lo que no se recomienda como primera opción.

3. Localización por contenido de texto

Localiza mediante el texto visible del elemento.

await page.click('text=登录');
await page.click('button:has-text("提交")');

4. Localización por atributo

Selecciona directamente usando atributos.

await page.fill('input[name="email"]', '[email protected]');
await page.click('[data-test="submit-button"]');

5. Mejores prácticas para estrategias de localización

  • Prioriza el uso de selectores únicos y estables(comodata-testid、data-testatributo)
  • Evita depender de ids o nombres de clase dinámicos
  • Usapage.getByRole、page.getByTexty otros métodos con mejor legibilidad (recomendado en Playwright 5.x)

Ejemplo


await page.getByRole('button', { name: 'Enviar' }).click();
await page.getByPlaceholder('Ingrese el nombre de usuario').fill('admin');

Interacciones básicas

Playwright admite múltiples formas de interactuar con los elementos, cubriendo clic, entrada de texto, teclado y ratón.

1. Operación de clic (page.click）

await page.click('#submit');

Parámetros opcionales:

  • button：'left' | 'right' | 'middle'(botón izquierdo por defecto)
  • clickCount: número de clics (establecer en 2 para doble clic)
  • modifiers: combinación de teclas (por ejemplo,['Control']）

Ejemplo

await page.click('#submit', { button: 'right' }); // clic derecho
await page.dblclick('#submit'); // doble clic

2. Ingresar texto (fill vs type）

  • fill(selector, value): limpia el campo de entrada e ingresa el nuevo valor (recomendado, se usa en la mayoría de los casos)
  • type(selector, text): simula la entrada carácter por carácter (con retraso, más parecida a un usuario real)

Ejemplo

await page.fill('input[name="username"]', 'test_user');
await page.type('input[name="search"]', 'playwright', { delay: 200 });

3. Operaciones de teclado

  • press: simula la pulsación de teclas
  • keyboard.type: ingresa texto de forma continua
  • keyboard.press: presiona una tecla (puede incluir combinaciones de teclas)

Ejemplo

await page.press('input[name="username"]', 'Enter');
await page.keyboard.type('Hello World!');
await page.keyboard.press('Control+A'); // seleccionar todo
await page.keyboard.press('Backspace'); // eliminar

4. Operaciones de ratón

Playwright proporciona un control completo del ratón:

  • hover: pasar el ratón por encima
  • mouse.move(x, y): mover a coordenadas
  • mouse.click(x, y): hacer clic en coordenadas
  • mouse.down / mouse.up: presionar/soltar el botón del ratón
  • dragAndDrop: arrastrar un elemento (Playwright 1.18+)

Ejemplo

await page.hover('#menu'); // pasar el ratón por encima
await page.mouse.move(100, 200); // mover a coordenadas
await page.mouse.click(120, 220); // hacer clic en coordenadas
await page.dragAndDrop('#item1', '#dropzone'); // arrastrar hasta el área de destino

Ejemplo completo: simular inicio de sesión y tomar captura de pantalla

A continuación se muestra un script completo de Playwright que demuestra operaciones básicas como navegación, localización, ingreso de texto y clic.

Ejemplo

const { chromium } = require('playwright');

(async () => {
  // 1. Iniciar el navegador y crear una nueva página
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  // 2. Navegar a la página de inicio de sesión
  await page.goto('https://github.com/login');
  console.log(`Título de la página actual: ${await page.title()}`);

  // 3. Localización de elementos e ingreso de texto
  // Localizar el campo de entrada de nombre de usuario e ingresar el nombre de usuario
  await page.locator('#login_field').fill('your_username');
  // Localizar el campo de entrada de contraseña e ingresar la contraseña
  await page.locator('#password').fill('your_password');

  // 4. Hacer clic en el botón de inicio de sesión
  // Usar .getByRole() es una forma de localización más robusta
  await page.getByRole('button', { name: 'Sign in' }).click();

  // 5. Esperar a que la navegación de la página se complete para asegurar el inicio de sesión exitoso
  await page.waitForURL('https://github.com/');

  // 6. Tomar y guardar una captura de pantalla para confirmar el estado de inicio de sesión
  await page.screenshot({ path: 'github_homepage.png' });
  console.log('Inicio de sesión exitoso, y se ha tomado captura de pantalla');

  // 7. Cerrar el navegador
  await browser.close();
})();

Método de ejecución:

  • Guarda el código en el directorio del proyecto comogithub_login.js。
  • Ejecútalo en la terminalnode github_login.js。

Tabla resumen de API comunes

Categoría Método / Propiedad Descripción
Navegación de página page.goto(url[, options]) Abrir página
page.reload([options]) Actualizar página
page.goBack([options]) Atrás
page.goForward([options]) Adelante
page.waitForLoadState([state]) Esperar el estado de carga de la página
Localización de elementos page.locator(selector) Localizador genérico
page.getByRole(role, options) Localizar por rol
page.getByText(text) Localizar por texto
page.getByPlaceholder(text) Localizar por placeholder
page.getByLabel(text) Localizar por label
Interacciones básicas page.click(selector[, options]) Hacer clic en un elemento
page.dblclick(selector) Doble clic
page.fill(selector, value) Ingresar texto (limpiar y luego llenar)
page.type(selector, text[, options]) Simular entrada carácter por carácter
page.press(selector, key) Pulsar una tecla sobre un elemento
page.keyboard.type(text) Entrada de teclado
page.keyboard.press(key) Pulsación de teclas (incluye combinaciones)
page.hover(selector) Pasar el ratón
page.mouse.move(x, y) Mover el ratón
page.mouse.click(x, y[, options]) Clic en coordenadas
page.dragAndDrop(src, dest) Arrastrar elementos
Otras extensiones