Skip to content

README.md

Latest commit

 

History

History
297 lines (248 loc) · 9.49 KB

README.md

File metadata and controls

297 lines (248 loc) · 9.49 KB

scrns

npm version

Automated screenshots and screencasts (GIF/video) with Puppeteer or Playwright — wait for selectors, configurable viewports, scroll positioning, action timelines, and downloads.

Also available on GitLab. Reusable CI integrations: GitHub Action (v1 branch), GitLab CI component.

Install

pnpm add scrns
# or
npm install scrns

Puppeteer is included by default. To use Playwright instead (or alongside):

pnpm add playwright

CLI Usage

scrns [options]

Options

Flag Description
-c, --config <path> Config file path (default: scrns.config.{ts,js,json})
-d, --download-sleep <ms> Sleep while waiting for downloads (default: 1000)
-E, --engine <name> Browser engine: puppeteer or playwright (default: auto-detect)
-h, --host <host> Hostname or port (numeric port maps to 127.0.0.1:port)
-i, --include <regex> Only generate screenshots matching this regex
-l, --load-timeout <ms> Timeout waiting for selector (default: 30000)
-o, --output <dir> Output directory (default: ./screenshots)
-s, --selector <css> Default CSS selector to wait for
--https Use HTTPS instead of HTTP

Example

# Auto-detect config, use localhost:3000
scrns

# Specify port and config
scrns -h 8080 -c my-config.ts

# Filter to specific screenshots
scrns -i "home|about"

# Use Playwright instead of Puppeteer
scrns -E playwright

Preview Mode

scrns preview (aliased record) opens a headful browser for interactively composing screenshots. Adjust the view and resize the window, then capture with Enter (terminal) or Ctrl+Shift+S (browser):

# Preview a specific config entry
scrns preview <name>

# Preview an arbitrary URL (no config needed)
scrns preview --url 'http://localhost:3000/?view=map'

On capture, prints the resulting state as a config snippet:

Captured "og":
  query: '?view=map&zoom=12'
  width: 1200
  height: 800

Config File

Create scrns.config.ts (or .js/.json). The config can be a flat Screens map:

export default {
  'home': {
    query: '',
    width: 1200,
    height: 800,
  },
  'about': {
    query: 'about',
    selector: '.main-content',
  },
  'footer': {
    query: '',
    scrollTo: 'footer',
    scrollOffset: 20,
  },
}

Or a Config with top-level options and a screenshots key, so that host, output, etc. live in the config file instead of CLI flags:

import { Config } from 'scrns'

const config: Config = {
  engine: 'playwright',  // or 'puppeteer' (default: auto-detect)
  host: 3456,
  output: 'public/img/screenshots',
  selector: '.app',
  screenshots: {
    'home': { query: '' },
    'about': { query: 'about' },
  },
}

export default config

Top-level config options (engine, host, https, output, selector, loadTimeout, downloadSleep) are overridden by their corresponding CLI flags when both are specified.

Config Options

Option Type Default Description
path string {name}.png Output path (relative to outputDir, or absolute)
query string '' URL path/query (appended to baseUrl)
width number 800 Viewport width
height number 560 Viewport height
selector string - CSS selector to wait for before capturing
loadTimeout number 30000 Timeout in ms for selector wait
preScreenshotSleep number 0 Sleep in ms before taking screenshot
scrollY number 0 Scroll Y pixels before screenshot
scrollTo string - CSS selector to scroll into view
scrollOffset number 0 Offset pixels above scrollTo element
download boolean false Set download behavior instead of screenshot
downloadSleep number 1000 Sleep in ms while waiting for download

Screencast Options

Adding an actions array to a config entry turns it into a screencast. The output defaults to .gif.

Option Type Default Description
actions ScreencastAction[] - Action timeline (presence triggers screencast mode)
fps number 15 Frames per second for GIF capture
gifQuality number 10 GIF quality: 1-30, lower = better
loop boolean true Whether the GIF should loop
videoCrf number 23 CRF quality for video output (lower = better, requires ffmpeg)

Screencast Actions

Action Fields Description
wait duration Pause for duration ms
key key, duration Hold key(s) for duration ms (e.g. 'Shift+ArrowLeft')
keydown key Press and hold key(s)
keyup key Release key(s)
type text Type text
click x, y, button? Click at coordinates
drag from, to, duration, button? Drag between coordinates over duration ms
animate frames, eval, frameDelay? Deterministic frame-by-frame capture (see below)

The animate action calls eval as (frameIndex, totalFrames) => ... for each frame, capturing a screenshot after each call. This produces deterministic, idempotent GIF output.

Screencast Example

export default {
  // Screenshot (unchanged)
  'og': {
    query: '?view=default',
    width: 1200,
    height: 800,
    selector: '#root',
    path: 'og.png',
  },
  // Screencast: hold a key to rotate a 3D view
  'hero': {
    query: '?view=3d',
    width: 800,
    height: 500,
    selector: '#root',
    preScreenshotSleep: 3000,
    path: 'hero.gif',
    fps: 15,
    actions: [
      { type: 'wait', duration: 1000 },
      { type: 'key', key: 'Shift+ArrowLeft', duration: 4000 },
      { type: 'wait', duration: 1000 },
    ],
  },
  // Screencast: deterministic frame-by-frame animation
  'rotate': {
    query: '?view=3d',
    width: 800,
    height: 500,
    selector: '#root',
    preScreenshotSleep: 3000,
    path: 'rotate.gif',
    fps: 15,
    actions: [
      { type: 'wait', duration: 500 },
      { type: 'animate', frames: 60, eval: '(i, n) => { window.setBearing(i * 360 / n) }' },
      { type: 'wait', duration: 500 },
    ],
  },
}

Video Output

Set the output path to .mp4, .mkv, .mov, or .webm to produce video output via ffmpeg instead of GIF. This gives frame-accurate recordings with proper codec compression (H.264 or VP9).

Requires ffmpeg on $PATH.

export default {
  'demo': {
    query: '?view=demo',
    width: 800,
    height: 600,
    selector: '#root',
    path: 'demo.mp4',
    videoCrf: 18,  // lower = better quality
    actions: [
      { type: 'wait', duration: 1000 },
      { type: 'key', key: 'ArrowRight', duration: 3000 },
      { type: 'wait', duration: 1000 },
    ],
  },
}

Codec selection is based on extension: .webm → VP9 (libvpx-vp9), all others → H.264 (libx264).

To derive a GIF from video output:

ffmpeg -i demo.mp4 -vf "fps=15,scale=400:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" demo.gif

Programmatic Usage

import { takeScreenshots, resolveEngine, ScreencastConfig } from 'scrns'

// Optional: explicitly choose an engine (auto-detects if omitted)
const engine = await resolveEngine('playwright')

await takeScreenshots({
  'home': { query: '' },
  'about': { query: 'about', selector: '.content' },
  'demo': {
    query: 'demo',
    actions: [
      { type: 'wait', duration: 1000 },
      { type: 'key', key: 'Enter', duration: 100 },
      { type: 'wait', duration: 2000 },
    ],
    fps: 10,
  } satisfies ScreencastConfig,
}, {
  baseUrl: 'http://localhost:3000',
  outputDir: './screenshots',
  defaultSelector: '#app',
  include: /home|demo/,
  log: console.log,
  engine,  // omit to auto-detect
})

Used by

  • jc-taxes (usage) — Jersey City property tax map (deck.gl 3D visualization)
  • use-kbd (usage) — Omnibars, editable hotkeys, search, and keyboard-navigation for React apps
  • ctbk (usage) — Citi Bike trip data explorer
  • apvd (usage) — Area-proportional Venn diagrams