Grabación de video en Playwright CLI: grabación, capítulos, overlays y compromisos de depuración

Wed, 15 Apr 2026 08:22:45 +0800

Si quieres grabar sesiones de automatización de navegador como video para depuración, documentación o prueba de trabajo, Playwright CLI ya ofrece un flujo bastante directo. Produce video WebM usando el códec VP8/VP9.

Este artículo sigue la referencia oficial video-recording y se centra en las partes más importantes en la práctica: flujo básico de grabación, marcadores de capítulo, grabación completa de hero scripts, Overlay API y la diferencia entre video y tracing. Se conservan las líneas de comando, snippets de código y detalles de parámetros de la referencia.

01 Flujo básico de grabación

El patrón básico es simple: abrir el navegador, iniciar grabación, realizar acciones y luego detener y guardar.

# Open browser first
playwright-cli open

# Start recording
playwright-cli video-start demo.webm

# Add a chapter marker for section transitions
playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000

# Navigate and perform actions
playwright-cli goto https://example.com
playwright-cli snapshot
playwright-cli click e1
# Add another chapter
playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
playwright-cli fill e2 "test input"

# Stop and save
playwright-cli video-stop

Estos comandos ya cubren el flujo de grabación más común. video-chapter es útil para insertar tarjetas de capítulo entre etapas, de modo que el video final sea más fácil de seguir.

02 Buenas prácticas

1. Usar nombres de archivo descriptivos

Si el video es para otras personas o para revisarlo más tarde, el nombre del archivo debería incluir suficiente contexto para entenderlo de un vistazo.

1
2
3

# Include context in filename
playwright-cli video-start recordings/login-flow-2024-01-15.webm
playwright-cli video-start recordings/checkout-test-run-42.webm

2. Grabar hero scripts completos

La recomendación oficial es que, cuando un video sea para un usuario o sirva como prueba de trabajo, lo mejor es convertir el escenario en un snippet de código y ejecutarlo con run-code. Eso da mejor control sobre ritmo, pausas y anotaciones en el video. La referencia también señala que Playwright ahora incluye APIs diseñadas específicamente para este tipo de flujo de grabación.

El proceso sugerido es:

Primero realiza el escenario con la CLI y anota todos los locators y acciones. Necesitarás esos locators más tarde si quieres sus bounding boxes para overlays de resaltado.
Crea un archivo de script dedicado para el video y escríbelo con el estilo mostrado abajo. Usa pressSequentially con delay para una escritura más suave, y añade pausas donde resulten naturales.
Usa playwright-cli run-code --filename your-script.js.

Importante: los overlays son pointer-events: none, así que no interfieren con las interacciones de la página. Puedes mantener overlays adhesivos visibles mientras haces clic, rellenas campos o realizas cualquier acción.

async page => {
  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
  await page.goto('https://demo.playwright.dev/todomvc');
  // Show a chapter card - blurs the page and shows a dialog.
  // Blocks until duration expires, then auto-removes.
  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
  // overlay via await page.screencast.showOverlay().
  await page.screencast.showChapter('Adding Todo Items', {
    description: 'We will add several items to the todo list.',
    duration: 2000,
  });
  // Perform action
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1000);

  // Show next chapter
  await page.screencast.showChapter('Verifying Results', {
    description: 'Checking the item appeared in the list.',
    duration: 2000,
  });
  // Add a sticky annotation that stays while you perform actions.
  // Overlays are pointer-events: none, so they won't block clicks.
  const annotation = await page.screencast.showOverlay(`
    <div style="position: absolute; top: 8px; right: 8px;
      padding: 6px 12px; background: rgba(0,0,0,0.7);
      border-radius: 8px; font-size: 13px; color: white;">
      Item added successfully
    </div>
  `);
  // Perform more actions while the annotation is visible
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1500);

  // Remove the annotation when done
  await annotation.dispose();
  // You can also highlight relevant locators and provide contextual annotations.
  const bounds = await page.getByText('Walk the dog').boundingBox();
  await page.screencast.showOverlay(`
    <div style="position: absolute;
      top: ${bounds.y}px;
      left: ${bounds.x}px;
      width: ${bounds.width}px;
      height: ${bounds.height}px;
      border: 1px solid red;">
    </div>
    <div style="position: absolute;
      top: ${bounds.y + bounds.height + 5}px;
      left: ${bounds.x + bounds.width / 2}px;
      transform: translateX(-50%);
      padding: 6px;
      background: #808080;
      border-radius: 10px;
      font-size: 14px;
      color: white;">Check it out, it is right above this text
    </div>
  `, { duration: 2000 });
  await page.screencast.stop();
}

El valor de este script no está solo en que graba el flujo, sino en que vuelve el video más fácil de entender: las tarjetas de capítulo gestionan transiciones, pressSequentially hace que la escritura se vea natural y showOverlay añade explicación, resaltado y contexto.

La referencia cierra esta sección con un recordatorio breve: abraza la creatividad; los overlays son potentes.

03 Resumen de Overlay API

Al grabar video, la Overlay API es especialmente útil para transiciones de sección, llamadas locales y anotaciones adhesivas. El resumen oficial es:

Method	Use Case
`page.screencast.showChapter(title, { description?, duration?, styleSheet? })`	Tarjeta de capítulo a pantalla completa con fondo desenfocado, ideal para transiciones de sección
`page.screencast.showOverlay(html, { duration? })`	Overlay HTML personalizado, útil para callouts, etiquetas y resaltados
`disposable.dispose()`	Elimina un overlay adhesivo añadido sin duración
`page.screencast.hideOverlays()` / `page.screencast.showOverlays()`	Oculta o muestra temporalmente todos los overlays

Si tu objetivo es convertir la automatización en un video cómodo de ver, este conjunto de APIs es una de las partes más valiosas que aprender primero.

04 Tracing vs video

La documentación oficial deja muy clara la diferencia entre ambos:

Feature	Video	Tracing
Output	WebM file	Trace file (viewable in Trace Viewer)
Shows	Visual recording	DOM snapshots, network, console, actions
Use case	Demos, documentation	Debugging, analysis
Size	Larger	Smaller

Una forma simple de pensarlo:

video es mejor para demos, entregas y revisar lo que vería un usuario
tracing es mejor para depurar, inspeccionar detalles de acciones y analizar contexto de ejecución

No se reemplazan entre sí. Cada uno sirve a un propósito diferente.

05 Limitaciones

La referencia también señala dos limitaciones prácticas:

La grabación añade una ligera sobrecarga a la automatización
Las grabaciones largas pueden consumir bastante espacio en disco

Así que, aunque la grabación de video es muy útil, añade cierta sobrecarga de runtime y las grabaciones largas pueden crecer mucho en disco.

06 Resumen rápido

Si solo quieres lo esencial, recuerda estos puntos:

video-start / video-stop son los comandos principales para grabar
video-chapter añade transiciones de sección y facilita seguir las demos
Los escenarios de grabación más avanzados se escriben mejor como scripts y se ejecutan con run-code
showOverlay y showChapter pueden mejorar mucho la legibilidad del video
video es mejor para demos, mientras tracing es mejor para depuración

Si tu flujo ya incluye demos de automatización, evidencia de aceptación o grabaciones de prueba de trabajo, video recording es una parte de Playwright CLI que vale mucho la pena añadir.

Referencias

Referencia video-recording de Playwright CLI: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md
Página principal de Playwright CLI: https://github.com/microsoft/playwright-cli

Debugging on KnightLi Blog