Getting started

SuiteCut records a Playwright test or script into a validated manifest. Rendering is a separate step, so the browser does not need to stay open while FFmpeg creates the final video.

Requirements

• Node.js 22 or newer.
• playwright or @playwright/test 1.59 or newer.
• Chromium, Firefox, or WebKit installed through Playwright.
• FFmpeg and FFprobe on PATH.

Install for Playwright Test

npm install --save-dev suitecut @playwright/test
npx playwright install chromium

On macOS, install the media tools with brew install ffmpeg.

Configure Playwright

Import test and expect from suitecut inside recorded tests. Keep Playwright trace and video off because SuiteCut owns the page screencast.

import { defineConfig } from '@playwright/test'

export default defineConfig({
  projects: [{ name: 'chromium', use: { browserName: 'chromium' } }],
  reporter: [
    ['line'],
    ['suitecut/reporter', { outputFile: '.suitecut/latest-run.json' }],
  ],
  use: { trace: 'off', video: 'off' },
})

Record a test

This is the current examples/basic.spec.ts file. The site imports it directly, so the snippet changes when the runnable example changes.

import { expect, test } from 'suitecut'

test('records a narrated flow', async ({ page, suitecut }) => {
  test.setTimeout(120_000)
  await page.setContent(`
    <main>
      <h1>Example Domain</h1>
      <p>This page is local to the test.</p>
    </main>
  `)
  await suitecut.narrate('The example page is open.')
  await expect(page.getByRole('heading')).toHaveText('Example Domain')
  await suitecut.checkpoint('Example page loaded')
})

Run and render

suitecut test --manifest .suitecut/latest-run.json -- examples/basic.spec.ts

suitecut render \
  --manifest .suitecut/latest-run.json \
  --output .suitecut/videos/basic.mp4

suitecut test installs the line and SuiteCut reporters for that run. A normalnpx playwright test uses the reporter in the configuration above. Each render also writesbasic.mp4.suitecut.json with the selected attempt, diagnostics, FFmpeg arguments, process result, and output duration.

Use plain Playwright

Install suitecut and playwright, then import record ordefineSuiteCut from suitecut/playwright. SuiteCut launches and closes the browser, creates the context and page, writes one manifest attempt, and runs registered cleanup callbacks in reverse order. The examples page uses the actual repository scripts.

Render size and frame rate

The default source is a 1600 × 900 browser viewport recorded at 60 fps. The default delivery file is 3840 × 2160 at 60 fps. For an HD page composition with native 4K detail, set the viewport to 1920 × 1080 and the capture size to 3840 × 2160. SuiteCut runs the page on a 4K surface with a 2× layout scale instead of upscaling an HD recording.

test.use({
  suitecutCapture: {
    viewport: { width: 1920, height: 1080 },
    size: { width: 3840, height: 2160 },
    framesPerSecond: 60,
  },
})

suitecut render \
  --manifest .suitecut/latest-run.json \
  --output .suitecut/videos/basic-4k.mp4 \
  --width 3840 \
  --height 2160 \
  --fps 60