Pawprint

Automated screenshot generation for web applications across themes, color palettes, and viewport sizes.

Pawprint uses Playwright to capture screenshots of your app in every combination of route, mode (light/dark), palette, and viewport you configure. It handles SPA authentication, organizes output into timestamped folders, and generates metadata for each run.

Installation

npm install
npx playwright install chromium
npm run build

To make the pawprint command available globally:

npm link

Quick Start

# 1. Generate a config file in your app directory
pawprint init /path/to/your-app

# 2. Edit the generated pawprint.config.json with your app's details

# 3. Start your app, then generate screenshots
pawprint generate /path/to/your-app

CLI Commands

pawprint generate <app-path>

Takes screenshots across all configured theme/palette/viewport combinations.

pawprint generate /path/to/app
pawprint generate /path/to/app --config ./custom-config.json
pawprint generate /path/to/app --output ./my-screenshots
pawprint generate /path/to/app --debug

| Option | Description | |---|---| | -c, --config <path> | Custom config file path (default: <app-path>/pawprint.config.json) | | -o, --output <dir> | Override output directory | | --debug | Enable debug mode with extra error output |

pawprint init [app-path]

Creates a sample pawprint.config.json at the given path (defaults to .).

pawprint init
pawprint init /path/to/app
pawprint init . --force   # overwrite existing config

pawprint list <app-path>

Lists previous screenshot runs organized by date.

pawprint list /path/to/app
pawprint list /path/to/app --output ./my-screenshots

Configuration

Create a pawprint.config.json in your app directory or pass a custom path with --config.

Full Example

{
  "baseUrl": "http://localhost:3000",
  "routes": ["/", "/dashboard", "/settings", "/profile"],
  "modes": ["light", "dark"],
  "palettes": ["default", "high-contrast"],
  "viewports": [
    { "name": "desktop", "width": 1440, "height": 900 },
    { "name": "mobile", "width": 390, "height": 844 },
    { "name": "tablet", "width": 768, "height": 1024 }
  ],
  "appearance": {
    "strategy": "localStorage",
    "modeKey": "theme",
    "paletteKey": "palette"
  },
  "outputDir": "pawprint-output",
  "auth": {
    "strategy": "form",
    "loginUrl": "/login",
    "credentials": {
      "username": "[email protected]",
      "password": "password123"
    },
    "selectors": {
      "username": "input[type=email]",
      "password": "input[type=password]",
      "submit": "button[type=submit]"
    }
  },
  "screenshotOptions": {
    "fullPage": false,
    "waitForTimeout": 500,
    "waitUntil": "networkidle"
  }
}

Required Fields

| Field | Type | Description | |---|---|---| | baseUrl | string | Base URL of the running app (e.g. http://localhost:3000) | | routes | string[] | Routes to screenshot (e.g. ["/", "/dashboard"]) | | modes | string[] | Theme modes (e.g. ["light", "dark"]) | | appearance | object | How themes are applied to the app |

Optional Fields

| Field | Type | Default | Description | |---|---|---|---| | palettes | string[] | ["default"] | Color palette names | | viewports | ViewportPreset[] | [{name:"default", width:1440, height:900}] | Viewport sizes | | outputDir | string | "pawprint-output" | Root output directory | | auth | AuthStrategy | undefined | Authentication config | | screenshotOptions | object | see below | Screenshot capture settings |

Appearance Strategies

localStorage -- For apps that store theme preferences in localStorage:

{
  "strategy": "localStorage",
  "modeKey": "theme",
  "paletteKey": "palette"
}

Pawprint sets the localStorage keys, then reloads the page so the app picks up the new values.

dom -- For apps that use CSS classes or DOM attributes (planned):

{
  "strategy": "dom",
  "modeClass": "dark",
  "paletteAttribute": "data-palette"
}

Authentication

Form-based login

Pawprint fills in a login form, submits it, and saves the browser state for reuse:

{
  "strategy": "form",
  "loginUrl": "/login",
  "credentials": {
    "username": "[email protected]",
    "password": "password"
  },
  "selectors": {
    "username": "input[type=email]",
    "password": "input[type=password]",
    "submit": "button[type=submit]",
    "authCheck": ".dashboard-header"
  }
}

The saved storageState.json is reused for up to 1 hour before re-authenticating.

Reusing storage state

If you already have a Playwright storage state file:

{
  "strategy": "storageState",
  "storageStatePath": "./storageState.json"
}

Output Structure

Each run creates a timestamped folder to avoid overwriting previous results:

pawprint-output/
  my-app/
    2026-02-16/
      2026-02-16_14-30-45/
        default/
          light/
            home-desktop.png
            home-mobile.png
            dashboard-desktop.png
          dark/
            home-desktop.png
            home-mobile.png
            dashboard-desktop.png
        high-contrast/
          light/
            ...
          dark/
            ...
        metadata.json

Screenshot Naming

| Route | File Name | |---|---| | / | home-{viewport}.png | | /dashboard | dashboard-{viewport}.png | | /user/profile | user_profile-{viewport}.png | | (auth error) | ERROR-{route}-{viewport}.png | | (redirect to login) | REDIRECTED-{route}-{viewport}.png |

Metadata

Each run writes a metadata.json with:

{
  "timestamp": "2026-02-16T14:30:45.000Z",
  "appPath": "/path/to/app",
  "config": { "baseUrl": "...", "routes": [...], "modes": [...] },
  "outputPath": "pawprint-output/my-app/2026-02-16/2026-02-16_14-30-45",
  "stats": {
    "totalScreenshots": 24,
    "successful": 24,
    "failed": 0
  }
}

Programmatic Usage

Pawprint can be imported and used from another Node.js application instead of the CLI.

Basic Usage

import { loadConfig } from "pawprint/dist/core/config.js";
import { prepareOutputFolders, takeScreenshots } from "pawprint/dist/core/engine.js";

const appPath = "/path/to/your-app";
const config = loadConfig(appPath);

const folderMap = prepareOutputFolders(config, appPath);
await takeScreenshots(config, appPath, folderMap);

With Inline Config

import type { PawprintConfig } from "pawprint/dist/types/config.js";
import { prepareOutputFolders, takeScreenshots } from "pawprint/dist/core/engine.js";

const config: PawprintConfig = {
  baseUrl: "http://localhost:3000",
  routes: ["/", "/dashboard"],
  modes: ["light", "dark"],
  appearance: {
    strategy: "localStorage",
    modeKey: "theme",
  },
};

const appPath = "/path/to/your-app";
const folderMap = prepareOutputFolders(config, appPath);
await takeScreenshots(config, appPath, folderMap);

Available Exports

| Module | Exports | Description | |---|---|---| | core/config.js | loadConfig(appPath) | Load and validate pawprint.config.json from a directory | | core/engine.js | prepareOutputFolders(config, appPath) | Create the timestamped output folder structure, returns a folder map | | core/engine.js | takeScreenshots(config, appPath, folderMap) | Launch Chromium and capture all screenshots | | core/auth.js | setupAuth(context, page, config) | Run authentication against a Playwright browser context | | types/config.js | PawprintConfig, AuthStrategy, AppearanceStrategy, ViewportPreset, ScreenshotMetadata, FolderMap | TypeScript interfaces |

Linking as a Local Dependency

From another project:

# In the pawprint directory
npm link

# In your other project
npm link pawprint

Then import as shown above.

Development

# Run CLI directly (no build needed)
npm start -- generate /path/to/app

# Watch mode
npm run dev -- generate /path/to/app

# Build TypeScript
npm run build

Tech Stack

• TypeScript -- ES2022 target, NodeNext modules
• Playwright -- Chromium browser automation
• Commander -- CLI argument parsing
• Chalk -- Terminal colors

License

ISC