Playwright Screencast API Tutorial (v1.59+): Record Test Videos with Action Annotations

If you’re using Playwright for automation testing, there’s a new feature you should definitely know about. Released in version 1.59, the Screencast API is a game-changer for debugging and documentation.

👉 Playwright 1.59+ introduced the Screencast API, which allows you to record custom videos of your tests—with action annotations. In this guide, I’ll walk you through what's new, how to use it, and real use cases.

🧠 What is the Screencast API?

The Screencast API is a powerful new feature that gives you granular control over video recording during your automated tests. Unlike the older video recording options, the Screencast API lets you:

• Start and stop recording anytime during a test
• Record only specific parts or segments of your test
• Show visual action annotations (clicks, navigation, etc.)

💻 Example: Playwright Screencast Script

Here’s a simple working example to get you started with the Screencast API in your own tests:

import { test, expect } from '@playwright/test';

test('screencast demo', async ({ page }) => {

  // Start recording
  await page.screencast.start({
    path: 'screencast-demo.webm'
  });

  // Show action annotations
  const disposable = await page.screencast.showActions({
    position: 'top-right',
    duration: 1000,
    fontSize: 18
  });

  // Perform actions
  await page.goto('https://playwright.dev');
  await page.getByRole('link', { name: 'Testing documentation' }).click();

  // Stop annotations
  await disposable.dispose();

  // Assertion
  await expect(page).toHaveTitle('Installation | Playwright');

  // Optional delay for video visibility
  await page.waitForTimeout(3000);

  // Stop recording
  await page.screencast.stop();
});

🔍 Step-by-Step Explanation

1. Start Recording: await page.screencast.start({ path: 'file.webm' }); Begins recording and saves it as a high-quality .webm file.
2. Show Action Annotations: const disposable = await page.screencast.showActions({...}); Displays clicks and interactions visually on screen.
3. Perform Test Steps: Run your normal Playwright actions as you usually would.
4. Stop Annotations: await disposable.dispose(); Turns off the visual highlights (cleanup step).
5. Stop Recording: await page.screencast.stop(); Ends the session and finalizes the video file.

🧪 Real Use Cases

Why should you switch to the Screencast API? Here are a few professional scenarios:

• Precision Debugging: See exactly what happened during specific test failures without watching a 5-minute video.
• Dynamic Documentation: Create perfect video walkthroughs of your test flows for internal wikis.
• Team Collaboration: Share visual demos of new features instead of messy log files.
• Bug Reporting: Attach focused videos to Jira tickets that clearly highlight the issue.

⚠️ Pro Tips

To get the most out of this new API, keep these tips in mind:

• Add small waitForTimeout calls after key actions to make them easier to see in the recording.
• Use annotations only when needed to keep the video clean and professional.
• Integrate the output path with your CI pipeline artifacts for easy access.

📚 Official Documentation

For a complete list of options and more technical details, be sure to check out the official Playwright documentation:

• Playwright Screencast API Reference