home / skills / athola / claude-night-market / browser-recording

browser-recording skill

safe

This skill records browser sessions with Playwright to create tutorial videos and streamlines converting them to GIFs for documentation.

npx playbooks add skill athola/claude-night-market --skill browser-recording

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

6.2 KB

---
name: browser-recording
description: Record browser sessions using Playwright for web UI tutorials, converts
  video to GIF.
category: media-generation
tags:
- playwright
- browser
- recording
- video
- web
- tutorial
tools:
- Read
- Write
- Bash
complexity: medium
estimated_tokens: 500
progressive_loading: true
modules:
- spec-execution
- video-capture
dependencies:
- scry:gif-generation
---
## Table of Contents

- [Overview](#overview)
- [Required TodoWrite Items](#required-todowrite-items)
- [Process](#process)
- [Step 1: Validate Playwright Installation](#step-1:-validate-playwright-installation)
- [Step 2: Check Spec File](#step-2:-check-spec-file)
- [Step 3: Execute Recording](#step-3:-execute-recording)
- [Step 4: Convert to GIF](#step-4:-convert-to-gif)
- [Example Playwright Spec](#example-playwright-spec)
- [Playwright Configuration](#playwright-configuration)
- [Exit Criteria](#exit-criteria)
- [Error Handling](#error-handling)
- [Output Locations](#output-locations)
- [See Also](#see-also)


# Browser Recording Skill

Record browser sessions using Playwright to create video captures of web UI interactions for tutorials and documentation.


## When To Use

- Recording browser sessions with Playwright
- Creating web application demo recordings

## When NOT To Use

- Terminal-only workflows - use scry:vhs-recording instead
- Static screenshots - use standard screenshot tools

## Overview

This skill uses Playwright's built-in video recording to capture browser interactions. The workflow:

1. Validate Playwright installation
2. Execute a Playwright spec with video recording enabled
3. Retrieve the recorded video (WebM format)
4. Convert to GIF using the gif-generation skill

> **💡 Note**: Claude Code 2.0.72+ includes native Chrome integration for interactive browser control. This skill (Playwright) is designed for **automated recording workflows, CI/CD, and cross-browser support**. For interactive debugging and live testing, consider using native Chrome integration. Both approaches complement each other - develop interactively with Chrome, then automate with Playwright specs.

## Required TodoWrite Items

When invoking this skill, create todos for:

```
- [ ] Validate Playwright is installed and configured
- [ ] Check spec file exists at specified path
- [ ] Execute Playwright spec with video recording
- [ ] Locate and verify video output
- [ ] Convert video to GIF using gif-generation skill
```
**Verification:** Run the command with `--help` flag to verify availability.

## Process

### Step 1: Validate Playwright Installation

Check that Playwright is available:

```bash
npx playwright --version
```
**Verification:** Run the command with `--help` flag to verify availability.

If not installed, the user should run:
```bash
npm install -D @playwright/test
npx playwright install chromium
```
**Verification:** Run `pytest -v` to verify tests pass.

### Step 2: Check Spec File

Verify the Playwright spec file exists. Spec files should:
- Be located in a `specs/` or `tests/` directory
- Have `.spec.ts` or `.spec.js` extension
- Include video configuration (see spec-execution module)

### Step 3: Execute Recording

Run the spec with video enabled:

```bash
npx playwright test <spec-file> --config=playwright.config.ts
```
**Verification:** Run `pytest -v` to verify tests pass.

The config must enable video recording. See the spec-execution module for configuration details.

### Step 4: Convert to GIF

After recording completes, use the gif-generation skill to convert the WebM video to an optimized GIF:

```
**Verification:** Run the command with `--help` flag to verify availability.
Invoke scry:gif-generation with:
- input: <path-to-webm>
- output: <desired-gif-path>
- fps: 10 (recommended for tutorials)
- width: 800 (adjust based on content)
```
**Verification:** Run the command with `--help` flag to verify availability.

## Example Playwright Spec

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

test('demo workflow', async ({ page }) => {
  // Navigate to the application
  await page.goto('http://localhost:3000');

  // Wait for page to be ready
  await page.waitForLoadState('networkidle');

  // Perform demo actions
  await page.click('button[data-testid="start"]');
  await page.waitForTimeout(500); // Allow animation to complete

  await page.fill('input[name="query"]', 'example search');
  await page.waitForTimeout(300);

  await page.click('button[type="submit"]');
  await page.waitForSelector('.results');

  // Final pause to show results
  await page.waitForTimeout(1000);
});
```
**Verification:** Run `pytest -v` to verify tests pass.

## Playwright Configuration

Create or update `playwright.config.ts`:

```typescript
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    video: {
      mode: 'on',
      size: { width: 1280, height: 720 }
    },
    viewport: { width: 1280, height: 720 },
    launchOptions: {
      slowMo: 100 // Slow down actions for visibility
    }
  },
  outputDir: './test-results',
});
```
**Verification:** Run `pytest -v` to verify tests pass.

## Exit Criteria

- Playwright spec executed successfully (exit code 0)
- Video file exists in output directory
- Video has non-zero file size
- GIF conversion completed (if requested)

## Error Handling

| Error | Resolution |
|-------|------------|
| Playwright not installed | Run `npm install -D @playwright/test` |
| Browser not installed | Run `npx playwright install chromium` |
| Spec file not found | Verify path and file extension |
| Video not created | Check Playwright config has video enabled |
| Empty video file | validate spec actions complete before test ends |

## Output Locations

Default output paths:
- Videos: `./test-results/<test-name>/video.webm`
- Screenshots: `./test-results/<test-name>/screenshot.png`

## Module Reference

- See `modules/spec-execution.md` for detailed Playwright execution options
- See `modules/video-capture.md` for video format and quality settings

## See Also

- scry:gif-generation: Convert video to optimized GIF
## Troubleshooting

### Common Issues

**Command not found**
Ensure all dependencies are installed and in PATH

**Permission errors**
Check file permissions and run with appropriate privileges

**Unexpected behavior**
Enable verbose logging with `--verbose` flag

Overview

This skill records browser sessions using Playwright to produce WebM video captures and optionally converts them to optimized GIFs for tutorials and documentation. It focuses on automated, repeatable recording workflows suitable for CI/CD, cross-browser runs, and demo generation. It is designed to fit into scripted test pipelines and to hand off video output to a gif-generation step.

How this skill works

The skill validates that Playwright and the target browsers are installed, verifies the Playwright spec file, runs the spec with Playwright video recording enabled, and retrieves the resulting WebM video from the test output directory. Optionally, it invokes a GIF conversion step (gif-generation) to produce an optimized GIF with configurable fps and width for sharing or embedding.

When to use it

You need reproducible browser demo recordings from automated tests.
Creating short animated GIFs of UI flows for documentation or PRs.
CI/CD pipelines that must capture UI behavior across environments.
Cross-browser demo generation where Playwright manages browsers and recorders.

Best practices

Enable video in playwright.config (use.video.mode='on' and set size to match target output).
Keep demo actions deterministic and include pauses to ensure animations finish before test exit.
Record at reasonable fps (10 recommended) and resize to target width (e.g., 800) before GIF conversion.
Verify Playwright and browser installs with npx playwright --version and npx playwright install chromium if missing.
Store outputs in a predictable outputDir (e.g., ./test-results) so post-processing can find files.

Example use cases

Run a Playwright spec that walks through a signup flow and convert the resulting WebM to a 10 fps GIF for the product docs.
Automate nightly UI smoke tests that record failures for debugging and attach videos to CI artifacts.
Generate short marketing-ready GIFs from demo specs by recording desktop-sized video and converting with optimized settings.
Capture cross-browser comparisons by running the same spec on multiple browsers and collecting WebM outputs for side-by-side review.

FAQ

What if Playwright or browsers are not installed?

Run npm install -D @playwright/test and then npx playwright install chromium (or other browsers) and re-run validation.

Where are recordings stored?

By default Playwright writes videos to the configured outputDir (commonly ./test-results/<test-name>/video.webm); ensure your config sets outputDir.

How do I avoid empty or truncated videos?

Make actions deterministic and include final waits (page.waitForTimeout or networkidle) so the test does not exit before the demo completes.