Skip to content

tarunag10/snapcrawl

BranchesTags

Repository files navigation

Snapcrawl — Universal Website Screenshot & Video Recorder

Plug-and-play toolkit to drop into any web app codebase and automatically capture multi-viewport screenshots and polished MP4 demo videos.

What it does:

  • Crawls internal pages via BFS link discovery
  • Captures screenshots at multiple viewports (desktop, tablet, mobile)
  • Runs polished visual interactions (hover, smooth scroll, smart click exploration)
  • Records the full journey as an MP4 video via Playwright
  • Generates markdown reports of visited pages and interactions
  • Avoids destructive actions (delete, logout, payment clicks) by default

Quick Start

1) Bootstrap Into Any Project

From this toolkit folder:

scripts/bootstrap-capture-kit.sh "/absolute/path/to/your-target-project"

This auto-installs everything in the target project:

  • playwright + ffmpeg-static
  • Chromium browser binaries
  • scripts/record-workflow.js (video recorder)
  • scripts/capture-from-config.js (screenshot capture)
  • lib/shared.js (shared utilities)
  • Config files + npm scripts

2) Edit Config In Target Project

open workflow-recorder.config.json   # for video recording
open capture-config.json             # for screenshots

Minimum fields to check:

  • baseUrl — your local app or hosted website URL
  • setupSteps — optional login/setup flow

3) Run

npm run workflow:record          # Record MP4 demo video (headless)
npm run workflow:record:headful  # Record MP4 with visible browser
npm run capture:screenshots      # Capture multi-viewport screenshots

Output

Command Output
workflow:record output/workflow-recorder/*.mp4, artifacts/WORKFLOW_REPORT.md, artifacts/crawl.json
capture:screenshots output/social/*.png, WORKFLOW.md

CLI Help

npx snapcrawl --help
npx snapcrawl capture --config capture-config.json
npx snapcrawl capture --config capture-config.json --parallel 4
npx snapcrawl capture --config capture-config.json --ai-analyze --ai-limit 10
npx snapcrawl record --config workflow-recorder.config.json --allow-clicks
npx snapcrawl baseline save --dir output/social
npx snapcrawl diff --dir output/social --visual
npx snapcrawl storybook http://localhost:6006 --output output/storybook
npx snapcrawl watch --config capture-config.json --dir src

Initialize Configs (Interactive)

npx snapcrawl-init          # standalone command
npx snapcrawl init           # subcommand
node dist/create-snapcrawl.js  # direct

Answers 5 questions and generates capture-config.json (and optionally workflow-recorder.config.json) with sensible defaults.

Core Files

lib/shared.js                              # Shared utilities (browser, crawl, steps)
scripts/record-workflow.js                 # MP4 workflow recorder
scripts/capture-from-config.js             # Multi-viewport screenshot capture
scripts/bootstrap-capture-kit.sh           # One-command project setup
templates/workflow-recorder.template.json  # Video recorder config template
templates/capture-config.template.json     # Screenshot config template
CAPTURE_CONFIG_GUIDE.md                    # Full config schema reference

Supported Setup Step Types

Both scripts support these step types in setupSteps / scenarios[].steps:

Type Description Example
goto Navigate to URL { "type": "goto", "url": "https://..." }
fill Fill input field { "type": "fill", "selector": "#email", "value": "demo@test.com" }
click Click element { "type": "click", "selector": "button[type='submit']" }
press Press keyboard key { "type": "press", "selector": "#input", "key": "Enter" }
check Toggle checkbox { "type": "check", "selector": "#agree", "value": true }
scroll Scroll to position { "type": "scroll", "x": 0, "y": 500 }
wait Wait milliseconds { "type": "wait", "ms": 1000 }
waitForSelector Wait for element { "type": "waitForSelector", "selector": ".loaded" }
evaluate Run JS in page { "type": "evaluate", "script": "document.title" }
call Call window function { "type": "call", "fn": "initApp", "args": [] }
setById Set element value by ID { "type": "setById", "id": "name", "value": "Test" }

Safety

  • allowRiskyActions: false (default) avoids destructive or payment-like clicks
  • Automatic click exploration is off unless --allow-clicks or workflow.allowClicks is enabled
  • evaluate and call setup steps require --allow-script-steps
  • Excludes paths like /logout, /signout, /delete, /remove, /destroy
  • Filters button text containing: delete, remove, pay, purchase, checkout, etc.
  • Set allowRiskyActions: true only when you explicitly want deep workflow traversal

MCP Server (AI Tool Integration)

Snapcrawl includes an MCP (Model Context Protocol) server so AI tools like Claude Code and Cursor can trigger captures directly.

Setup with Claude Code

claude mcp add snapcrawl node dist/mcp-server.js

Setup with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "snapcrawl": {
      "command": "npx",
      "args": ["snapcrawl-mcp"]
    }
  }
}

Available Tools

Tool Description
snapcrawl_init Generate config files programmatically (baseUrl, viewports, video)
snapcrawl_capture Run screenshot capture using a config file
snapcrawl_record Run video workflow recording using a config file
snapcrawl_status Check which configs exist and summarize their settings

New Product Features

Shareable HTML Reports

Every capture writes report.html by default. The report includes:

  • Search across pages and URLs
  • Viewport filters
  • A compare-viewports mode
  • Embedded workflow video when recording
  • Visual diff and AI finding sections when those features are enabled

Visual Diff Reports

npx snapcrawl baseline save --dir output/social
npx snapcrawl capture --config capture-config.json
npx snapcrawl diff --dir output/social --visual

baseline save stores hashes and a copy of baseline image assets. diff --visual compares the latest PNG captures against that saved baseline, writes red overlay PNGs into output/social/diff/, and generates output/social/diff-report.html.

AI Screenshot Analysis

OPENAI_API_KEY=... npx snapcrawl capture --config capture-config.json --ai-analyze --ai-limit 12

The analyzer sends screenshots to a vision model and writes analysis.json plus an AI findings section in report.html. Use --ai-model <id> to override the default model.

Storybook Capture

npx snapcrawl storybook http://localhost:6006 --output output/storybook

Snapcrawl reads Storybook index.json or stories.json, builds iframe scenarios for each story, and captures desktop/mobile screenshots without hand-maintaining a URL list.

Watch Mode

npx snapcrawl watch --config capture-config.json --dir src
npx snapcrawl watch --record --config workflow-recorder.config.json --dir app

Watch mode runs once immediately, then re-runs capture or record after source changes. It ignores generated output, dist/, .git/, and node_modules/.

GitHub Action

jobs:
  snapcrawl:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run dev &
      - uses: ./
        with:
          url: http://localhost:3000
          command: capture
          output: output/social
          args: --parallel 4
      - uses: actions/upload-artifact@v4
        with:
          name: snapcrawl-report
          path: output/

For Storybook, set command: storybook and url: http://localhost:6006.

Roadmap: Planned Features

Zero-Install Distribution

Goal: npx snapcrawl works instantly with no pre-install steps.

Feature Status Description
System Chrome fallback Done Use channel: 'chrome' to skip Chromium download — uses already-installed Chrome/Edge
Single-file bundle Done Bundled with esbuild — each CLI entry point is a single self-contained JS file in dist/
snapcrawl init scaffolder Done Interactive scaffolder (npx snapcrawl-init) to set up configs in any project
GitHub Action Planned uses: snapcrawl/action@v1 for CI screenshot capture on every PR
Docker image Planned docker run snapcrawl with Playwright + Chrome pre-installed
Homebrew tap Planned brew install snapcrawl for macOS users

AI-Powered Screenshot Analysis

Goal: After capturing screenshots, optionally analyze them with vision AI to detect issues, generate descriptions, and audit accessibility — all from the CLI.

Feature Status Description
--ai-analyze flag Planned Send each screenshot to a vision LLM (Claude, GPT-4o, Gemini) for automated analysis
UI issue detection Planned AI identifies broken layouts, overlapping elements, truncated text, missing images
Auto-generated alt text Planned AI writes descriptive alt text for every captured page
Accessibility audit Planned AI detects contrast issues, missing labels, keyboard traps, WCAG violations
Page descriptions Planned AI generates human-readable summaries of what each page shows
ARIA snapshot capture Planned Capture Playwright accessibility tree snapshots alongside screenshots for semantic regression testing

AI Visual Regression Testing

Goal: Replace brittle pixel-diff with AI-powered visual comparison that understands intent.

Feature Status Description
--diff baseline comparison Planned Compare current screenshots against a saved baseline
AI-powered diff Planned Vision AI determines if changes are intentional (button moved 2px = OK) vs broken (checkout button missing = critical)
Baseline management Planned snapcrawl baseline save / snapcrawl baseline update workflow
CI integration Planned Fail PR checks when AI detects visual regressions

AI Smart Crawling

Goal: Go beyond BFS link discovery — use AI to understand SPAs, trigger interactive states, and capture more of the app.

Feature Status Description
SPA-aware navigation Planned Detect React Router, Next.js, and framework-specific navigation that doesn't use <a> tags
Auto-detect interactive states Planned AI identifies dropdowns, modals, accordions, tabs and captures each state
Auto-generate setup steps Planned AI observes page structure and generates config steps for login flows, form fills, etc.
Playwright Test Agents Planned Leverage Playwright 1.56+ AI test agents for autonomous navigation with planner/generator/healer loops

AI Video Enhancements

Goal: Transform raw screen recordings into polished demo videos.

Feature Status Description
AI highlight reel Planned Auto-trim boring scroll sections, keep key interactions
Auto-generated timestamps Planned AI creates chapter markers for each page/interaction in the video
Text summary of demo Planned AI generates a written walkthrough from the video content

Reporting & Output

Feature Status Description
HTML report with thumbnails Planned Visual gallery report instead of markdown list
Playwright trace capture Planned Capture Playwright trace files alongside video for deep debugging
JSON + HTML diff reports Planned Structured output for CI pipelines and dashboards

Developer Experience

Feature Status Description
Config validation with schema Planned JSON Schema validation with clear error messages for bad configs
Structured/colored CLI output Planned Progress bars, phase markers, colored summaries
Parallel page capture Planned Capture multiple pages concurrently for faster runs
Global timeout Planned --timeout flag to prevent infinite crawls on large sites
Windows support Planned Cross-platform bootstrap (replace bash-only script with Node.js)

Competitive Positioning

Capability Percy ($199/mo) Chromatic ($149/mo) Applitools (Enterprise) Snapcrawl (Free)
Auto-crawl discovery No No No Yes
Multi-viewport screenshots Yes Yes Yes Yes
MP4 video recording No No No Yes
AI screenshot analysis No No Partial Planned
AI visual regression No No Yes Planned
Accessibility audit (AI+ARIA) No No Partial Planned
Zero-install CLI (npx) No No No Planned
Self-hosted / free No No No Yes
Config-driven, no code No No No Yes

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages