testreel

Programmatic video recordings for web apps. Define interactions in JSON, get polished screen recordings out.

demo-2026-04-07_03-41-40-332.webm

Demo video generated with testreel

• Let your LLM agent generate product videos - Just point your agent at this repo and ask it to generate a demo video for your product. Testreel integrates with Playwright, which allows your agent to create recordings with mocks and demo data easily.
• Repeatable editable video config - Instead of having to manually re-record a video because of a typo or a missed click, just edit the config and rerun the recording. Programmatically generate videos with polished background, and cursor and zoom animations.

Features

• Animated cursor — configurable style, size, and click ripple effects
• Window chrome — macOS-style title bar with traffic lights
• Background styling — padding, rounded corners, solid or gradient backgrounds
• Multiple auth methods — setup blocks, localStorage/cookies injection, storage state files, interactive login, Supabase provider
• Playwright integration — test fixture and recordPage() API for existing test suites
• Output formats — WebM (default), MP4, GIF

Install

npm install testreel playwright
npx playwright install chromium

Quick start

Create a recording definition (recording.json):

{
  "url": "https://example.com",
  "viewport": { "width": 1280, "height": 720 },
  "steps": [
    { "action": "click", "selector": "button.sign-in" },
    { "action": "fill", "selector": "#email", "text": "[email protected]" },
    { "action": "screenshot", "name": "filled-form" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "wait", "ms": 2000 }
  ]
}

Run it:

npx testreel recording.json

Output goes to ./testreel-output/ — a WebM video, PNG screenshots, and an output.json manifest.

CLI

npx testreel recording.json                       # basic recording
npx testreel recording.json --headed              # visible browser
npx testreel recording.json --format gif          # GIF output
npx testreel recording.json --setup login.json    # separate setup file
npx testreel validate recording.json              # validate without recording
npx testreel login https://app.com --save-state state.json  # interactive login
npx testreel init                                 # create a definition interactively

API

import { record, loadDefinition } from 'testreel'

const def = loadDefinition('recording.json')
const result = await record(def, { outputDir: './output' })

console.log(result.video)       // path to .webm file
console.log(result.screenshots) // array of .png paths

Playwright test fixture

Already have a Playwright test suite? Add recording to any test — just change test to recorded:

import { test, expect } from '@playwright/test'
import { testreelFixtures, type TestreelFixtures } from 'testreel/playwright'

const recorded = test.extend<TestreelFixtures>({
  ...testreelFixtures,
})

// This test is unchanged — no recording
test('health check', async ({ page }) => {
  await page.goto('/health')
  await expect(page.locator('.status')).toHaveText('OK')
})

// Just swap test → recorded — video is attached to the test report automatically
recorded('product demo', async ({ page }) => {
  await page.goto('https://myapp.com')
  await page.click('.login-button')
  await page.fill('#email', '[email protected]')
})

Recordings are captured regardless of test outcome — partial videos are attached to the report for debugging. See Playwright Integration for composing with custom fixtures, the PageRecorder API, and configuration options.

recordPage API

For manual control over recording within any Playwright script:

import { recordPage } from 'testreel'

// page must belong to a context created with recordVideo
const recorder = await recordPage(page, { chrome: true })
await recorder.click('.button')
await recorder.type('#search', 'hello')
const result = await recorder.stop() // finalizes video + post-processing
console.log(result.video)

Documentation

Guide	Description
Getting Started	Installation, first recording, output explanation
Recording Definitions	Full reference for the JSON format
Actions	All 13 step actions with examples
Authentication	Recording authenticated apps
CLI Reference	All commands and flags
Playwright Integration	Test fixture and recordPage() API
Examples	Common recording patterns

License

MIT