bookhoard/SCREENSHOT_AUTOMATION.md

Screenshot Automation Plan for Bookhoard Documentation

Status: Ready to implement when frontend is complete
Last Updated: 2026-02-03

This document outlines the complete plan for automatically generating screenshots for Bookhoard documentation using Playwright.

Overview

Playwright will be used to:

1. Navigate the running Bookhoard server
2. Perform key user/admin workflows
3. Capture screenshots at each step
4. Save to docs/images/ organized by documentation section
5. Generate/update markdown files with proper image references

Prerequisites (To Verify When Ready)

Frontend Pages Complete

Verify these pages are fully functional before starting:

• / - Login page
• /register - Registration page
• /dashboard - Main dashboard with library browsing
• /collections - Collections management
• /devices - Device management and registration
• /conflicts - Sync conflict resolution
• /progress - Reading progress tracking
• /analytics - Usage analytics
• /queue - Sync queue monitoring
• /admin - Admin dashboard
• /admin/profile - Profile settings
• /admin/library - Library management
• /api-explorer - API testing interface

Test Environment Ready

• Bookhoard server running on http://localhost:8765
• Test database seeded with sample data (books, collections, devices)
• Test admin account ready (username, password, role=admin)
• Test regular user account ready (username, password, role=user)

Installation & Setup

# Install Playwright (run in project root)
npm init -y
npm install -D @playwright/test
npx playwright install chromium

Project structure after setup:

bookhoard/
├── docs/
│   ├── images/           # Screenshots will be stored here
│   │   ├── user/
│   │   ├── admin/
│   │   ├── devices/
│   │   └── sync/
│   └── *.md              # Existing markdown files
├── screenshots/          # Playwright test files
│   ├── auth.spec.ts
│   ├── user-workflows.spec.ts
│   ├── admin-workflows.spec.ts
│   ├── device-workflows.spec.ts
│   ├── sync-workflows.spec.ts
│   └── config.ts
├── .env.screenshots      # Environment configuration
└── ...

Environment Setup

Create .env.screenshots in the project root:

# Bookhoard Server
BASE_URL=http://localhost:8765

# Admin Account (for admin guide screenshots)
ADMIN_EMAIL=admin@example.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=SecureAdminPass123!

# Regular User Account (for user guide screenshots)
USER_EMAIL=user@example.com
USER_USERNAME=user
USER_PASSWORD=SecureUserPass456!

Questions to Ask When Ready

Before running the screenshot automation, ask the user:

1. Server Access

Q: Where is the Bookhoard server running?

• localhost:8765 (default)
• Custom port: ________
• Remote URL: ________

2. Test Credentials

Q: What credentials should Playwright use?

Admin Account (for admin guide screenshots):

• Username: ________
• Password: ________

Regular User Account (for user guide screenshots):

• Username: ________
• Password: ________

3. Screenshot Format

Q: What format for screenshots?

• WebP (recommended - modern, good compression)
• PNG (highest quality, larger files)
• JPEG (smaller files, compression artifacts)

4. Screenshot Dimensions

Q: What viewport sizes for screenshots?

• Desktop: 1920x1080 (full-width screenshots)
• Tablet: 768x1024 (responsive documentation)
• Mobile: 375x667 (mobile documentation)
• All three sizes (comprehensive coverage)

5. Theme

Q: What theme should screenshots use?

• Default (Tokyo Night theme as seen in templates)
• Light theme (if implemented)
• Multiple themes (document theme switching)

6. Language

Q: What language/region for the UI?

• English (default)
• Other: ________

Screenshot Plan by Documentation Section

1. User Guide Screenshots

File: docs/user/user-guide.md

Screenshots Needed:

Screenshot Name	Description	Page/Action
login-page.webp	Login form with filled credentials	/ - Login page
dashboard-overview.webp	Main dashboard showing libraries	/dashboard
library-grid.webp	Media items grid view	/dashboard → Click library
book-detail.webp	Book detail view with metadata	/dashboard → Click book
search-results.webp	Search in action	/dashboard → Type in search
filter-panel.webp	Filter options expanded	/dashboard → Open filters
collections-list.webp	Collections grid view	/collections
create-collection.webp	New collection modal	/collections → Click "New Collection"
reading-progress.webp	Progress tracking view	/progress
analytics-view.webp	User analytics dashboard	/analytics

Estimated Screenshots: ~10

2. Admin Guide Screenshots

File: docs/user/admin-guide.md

Screenshots Needed:

Screenshot Name	Description	Page/Action
admin-dashboard.webp	Admin overview panel	/admin
user-management.webp	User list with actions	/admin → Users section
add-user.webp	Add new user form	/admin → Click "Add User"
library-settings.webp	Library configuration	/admin/library
add-library.webp	Create new library form	/admin/library → Click "Add Library"
analytics-admin.webp	Admin analytics view	/analytics (admin view)
sync-queue.webp	Sync queue monitoring	/queue
theme-settings.webp	Theme selection interface	/admin/profile → Theme section
user-profile-edit.webp	Edit user profile	/admin/profile

Estimated Screenshots: ~9

3. Device Setup Screenshots

File: docs/user/devices/kobo-setup.md and koreader-setup.md

Screenshots Needed:

Screenshot Name	Description	Page/Action
device-list.webp	Device management page	/devices
add-device-modal.webp	Add new device modal	/devices → Click "Add New Device"
device-form-kobo.webp	Kobo device registration form	/devices → Select Kobo type
device-form-koreader.webp	KOReader device registration form	/devices → Select KOReader type
device-qr-code.webp	QR code for device approval	After device registration
device-approved.webp	Device approved confirmation	After approving device
device-sync-settings.webp	Sync configuration for device	/devices → Click device settings
shelf-mapping.webp	Collection to shelf mapping	/devices → Click shelf mapping
sync-queue-item.webp	Device sync in queue	/queue (device specific)

Estimated Screenshots: ~9

4. Sync Guide Screenshots

File: docs/user/sync-guide.md

Screenshots Needed:

Screenshot Name	Description	Page/Action
sync-conflicts.webp	Conflicts list view	/conflicts
conflict-resolution.webp	Resolve conflict dialog	/conflicts → Click resolve
unlinked-books.webp	Unlinked books list	/unlinked-books
book-linking.webp	Link book to metadata	/unlinked-books → Click link
sync-success.webp	Successful sync indicator	Any page after sync

Estimated Screenshots: ~5

5. Settings Guide Screenshots

File: docs/user/settings-guide.md

Screenshots Needed:

Screenshot Name	Description	Page/Action
profile-overview.webp	Profile settings page	/admin/profile
update-username.webp	Username change form	/admin/profile
update-email.webp	Email change form	/admin/profile
change-password.webp	Password change form	/admin/profile
theme-selector.webp	Theme selection dropdown	/admin/profile (if implemented)

Estimated Screenshots: ~5

Playwright Test Files

screenshots/config.ts - Playwright Configuration

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./",
  fullyParallel: false,
  retries: 1,
  reporter: "list",
  use: {
    baseURL: process.env.BASE_URL || "http://localhost:8765",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    {
      name: "chromium-desktop",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 1920, height: 1080 },
      },
    },
  ],
});

screenshots/auth.spec.ts - Authentication Screenshots

import { test, expect } from "@playwright/test";

test.describe("Authentication Screenshots", () => {
  test("Login page", async ({ page }) => {
    await page.goto("/");

    await page.screenshot({
      path: "docs/images/user/login-page.webp",
      fullPage: true,
    });
  });

  test("User login flow", async ({ page }) => {
    await page.goto("/");

    await page.fill('input[name="login"]', process.env.USER_USERNAME || "user");
    await page.fill(
      'input[name="password"]',
      process.env.USER_PASSWORD || "password",
    );

    await page.screenshot({
      path: "docs/images/user/login-form-filled.webp",
      fullPage: true,
    });

    await page.click('button[type="submit"]');
    await page.waitForURL("/dashboard", { timeout: 5000 });

    await page.screenshot({
      path: "docs/images/user/dashboard-after-login.webp",
      fullPage: true,
    });
  });

  test("Admin login flow", async ({ page }) => {
    await page.goto("/");

    await page.fill(
      'input[name="login"]',
      process.env.ADMIN_USERNAME || "admin",
    );
    await page.fill(
      'input[name="password"]',
      process.env.ADMIN_PASSWORD || "password",
    );

    await page.click('button[type="submit"]');
    await page.waitForURL("/dashboard", { timeout: 5000 });

    await page.goto("/admin");

    await page.screenshot({
      path: "docs/images/admin/admin-dashboard.webp",
      fullPage: true,
    });
  });

  test("Registration page", async ({ page }) => {
    await page.goto("/register");

    await page.screenshot({
      path: "docs/images/user/registration-page.webp",
      fullPage: true,
    });

    await page.fill('input[name="email"]', "newuser@example.com");
    await page.fill('input[name="username"]', "newuser");
    await page.fill('input[name="password"]', "SecurePass123!");

    await page.screenshot({
      path: "docs/images/user/registration-form-filled.webp",
      fullPage: true,
    });
  });
});

screenshots/user-workflows.spec.ts - User Guide Screenshots

import { test, expect } from "@playwright/test";

test.describe("User Guide Screenshots", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto("/");
    await page.fill('input[name="login"]', process.env.USER_USERNAME || "user");
    await page.fill(
      'input[name="password"]',
      process.env.USER_PASSWORD || "password",
    );
    await page.click('button[type="submit"]');
    await page.waitForURL("/dashboard", { timeout: 5000 });
  });

  test("Dashboard overview", async ({ page }) => {
    await page.goto("/dashboard");

    await page.screenshot({
      path: "docs/images/user/dashboard-overview.webp",
      fullPage: true,
    });
  });

  test("Library grid view", async ({ page }) => {
    await page.goto("/dashboard");

    await page.waitForSelector("#libraries-container", { timeout: 5000 });

    const firstLibrary = page.locator("[data-library]").first();
    if (await firstLibrary.isVisible()) {
      await firstLibrary.click();
      await page.waitForURL(/\/dashboard/, { timeout: 5000 });

      await page.screenshot({
        path: "docs/images/user/library-grid.webp",
        fullPage: true,
      });
    }
  });

  test("Search functionality", async ({ page }) => {
    await page.goto("/dashboard");

    await page.waitForSelector("#search-input", { timeout: 5000 });

    await page.fill("#search-input", "science");
    await page.waitForTimeout(1000);

    await page.screenshot({
      path: "docs/images/user/search-results.webp",
      fullPage: true,
    });
  });

  test("Filter panel", async ({ page }) => {
    await page.goto("/dashboard");

    const filterPanel = page.locator(".filter-panel details");
    if (await filterPanel.isVisible()) {
      await filterPanel.click();
      await page.waitForTimeout(500);

      await page.screenshot({
        path: "docs/images/user/filter-panel-open.webp",
        fullPage: true,
      });
    }
  });

  test("Collections list", async ({ page }) => {
    await page.goto("/collections");

    await page.screenshot({
      path: "docs/images/user/collections-list.webp",
      fullPage: true,
    });
  });

  test("Create collection modal", async ({ page }) => {
    await page.goto("/collections");

    await page.click(
      'button:has-text("New Collection"), button:has-text("Create Your First Collection")',
    );

    await page.waitForSelector("#create-modal", {
      state: "visible",
      timeout: 5000,
    });

    await page.fill("#collection-name", "My Reading List");
    await page.fill("#collection-description", "Books I want to read");

    await page.screenshot({
      path: "docs/images/user/create-collection-modal.webp",
      fullPage: true,
    });
  });

  test("Reading progress view", async ({ page }) => {
    await page.goto("/progress");

    await page.screenshot({
      path: "docs/images/user/reading-progress.webp",
      fullPage: true,
    });
  });

  test("Analytics view", async ({ page }) => {
    await page.goto("/analytics");

    await page.screenshot({
      path: "docs/images/user/analytics-view.webp",
      fullPage: true,
    });
  });
});

screenshots/admin-workflows.spec.ts - Admin Guide Screenshots

import { test, expect } from "@playwright/test";

test.describe("Admin Guide Screenshots", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto("/");
    await page.fill(
      'input[name="login"]',
      process.env.ADMIN_USERNAME || "admin",
    );
    await page.fill(
      'input[name="password"]',
      process.env.ADMIN_PASSWORD || "password",
    );
    await page.click('button[type="submit"]');
    await page.waitForURL("/dashboard", { timeout: 5000 });
  });

  test("Admin dashboard", async ({ page }) => {
    await page.goto("/admin");

    await page.screenshot({
      path: "docs/images/admin/admin-dashboard.webp",
      fullPage: true,
    });
  });

  test("User management", async ({ page }) => {
    await page.goto("/admin");

    const userSection = page.locator('[data-section="users"], text="Users"');
    if (await userSection.isVisible()) {
      await page.screenshot({
        path: "docs/images/admin/user-management.webp",
        fullPage: true,
      });
    }
  });

  test("Library management", async ({ page }) => {
    await page.goto("/admin/library");

    await page.screenshot({
      path: "docs/images/admin/library-management.webp",
      fullPage: true,
    });
  });

  test("Add library form", async ({ page }) => {
    await page.goto("/admin/library");

    const addLibraryBtn = page.locator(
      'button:has-text("Add Library"), button:has-text("Create Library")',
    );
    if (await addLibraryBtn.isVisible()) {
      await addLibraryBtn.click();
      await page.waitForTimeout(500);

      await page.screenshot({
        path: "docs/images/admin/add-library-form.webp",
        fullPage: true,
      });
    }
  });

  test("Profile settings", async ({ page }) => {
    await page.goto("/admin/profile");

    await page.screenshot({
      path: "docs/images/admin/profile-settings.webp",
      fullPage: true,
    });
  });

  test("Theme selector", async ({ page }) => {
    await page.goto("/admin/profile");

    const themeSelect = page.locator(
      'select[name="theme"], [data-theme-selector]',
    );
    if (await themeSelect.isVisible()) {
      await themeSelect.click();
      await page.waitForTimeout(500);

      await page.screenshot({
        path: "docs/images/admin/theme-selector.webp",
        fullPage: true,
      });
    }
  });
});

screenshots/device-workflows.spec.ts - Device Setup Screenshots

import { test, expect } from "@playwright/test";

test.describe("Device Setup Screenshots", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto("/");
    await page.fill('input[name="login"]', process.env.USER_USERNAME || "user");
    await page.fill(
      'input[name="password"]',
      process.env.USER_PASSWORD || "password",
    );
    await page.click('button[type="submit"]');
    await page.waitForURL("/dashboard", { timeout: 5000 });
  });

  test("Device list page", async ({ page }) => {
    await page.goto("/devices");

    await page.screenshot({
      path: "docs/images/devices/device-list.webp",
      fullPage: true,
    });
  });

  test("Add device modal", async ({ page }) => {
    await page.goto("/devices");

    await page.click(
      'button:has-text("Add New Device"), button:has-text("Add Your First Device")',
    );

    await page.waitForSelector('[data-modal="add-device"], #add-device-modal', {
      state: "visible",
      timeout: 5000,
    });

    await page.screenshot({
      path: "docs/images/devices/add-device-modal.webp",
      fullPage: true,
    });
  });

  test("Kobo device form", async ({ page }) => {
    await page.goto("/devices");

    await page.click('button:has-text("Add New Device")');

    await page.waitForSelector('[data-modal="add-device"]', {
      state: "visible",
      timeout: 5000,
    });

    const deviceTypeSelect = page.locator('select[name="device_type"]');
    if (await deviceTypeSelect.isVisible()) {
      await deviceTypeSelect.selectOption("kobo");
      await page.waitForTimeout(500);

      await page.screenshot({
        path: "docs/images/devices/device-form-kobo.webp",
        fullPage: true,
      });
    }
  });

  test("KOReader device form", async ({ page }) => {
    await page.goto("/devices");

    await page.click('button:has-text("Add New Device")');

    await page.waitForSelector('[data-modal="add-device"]', {
      state: "visible",
      timeout: 5000,
    });

    const deviceTypeSelect = page.locator('select[name="device_type"]');
    if (await deviceTypeSelect.isVisible()) {
      await deviceTypeSelect.selectOption("koreader");
      await page.waitForTimeout(500);

      await page.screenshot({
        path: "docs/images/devices/device-form-koreader.webp",
        fullPage: true,
      });
    }
  });

  test("Sync queue", async ({ page }) => {
    await page.goto("/queue");

    await page.screenshot({
      path: "docs/images/devices/sync-queue.webp",
      fullPage: true,
    });
  });
});

screenshots/sync-workflows.spec.ts - Sync Guide Screenshots

import { test, expect } from "@playwright/test";

test.describe("Sync Guide Screenshots", () => {
  test.beforeEach(async ({ page }) => {
    await page.goto("/");
    await page.fill('input[name="login"]', process.env.USER_USERNAME || "user");
    await page.fill(
      'input[name="password"]',
      process.env.USER_PASSWORD || "password",
    );
    await page.click('button[type="submit"]');
    await page.waitForURL("/dashboard", { timeout: 5000 });
  });

  test("Sync conflicts page", async ({ page }) => {
    await page.goto("/conflicts");

    await page.screenshot({
      path: "docs/images/sync/sync-conflicts.webp",
      fullPage: true,
    });
  });

  test("Unlinked books page", async ({ page }) => {
    await page.goto("/unlinked-books");

    await page.screenshot({
      path: "docs/images/sync/unlinked-books.webp",
      fullPage: true,
    });
  });
});

Running the Tests

Run all tests

npx playwright test

Run specific test file

npx playwright test auth.spec.ts

Run in headed mode (see browser)

npx playwright test --headed

Run with debug mode

npx playwright test --debug

Markdown Update Strategy

Option 1: Create New Markdown

Generate fresh markdown files with embedded screenshots.

Option 2: Update Existing Markdown

Update existing markdown files by:

1. Finding section headers
2. Inserting screenshot references after relevant steps
3. Using alt text to describe what's shown

Example Markdown Update:

### Step 1: Log In to Bookhoard

1. Open your browser and navigate to `http://localhost:8765`
2. Enter your username and password
3. Click the **Login** button

![Login page showing username and password fields](../images/user/login-page.webp)

Workflow When Ready

Step 1: Verify Frontend Complete

• Check all pages listed in "Prerequisites" are working
• Confirm no TODO placeholders in templates

Step 2: Seed Test Data

# Add sample books, collections, devices
# Create test admin and user accounts

Step 3: Set Up Playwright

npm install -D @playwright/test
npx playwright install chromium

Step 4: Create Environment File

Create .env.screenshots with the test credentials

Step 5: Run Screenshot Scripts

# Run all screenshot workflows
npx playwright test

# Or run specific suites
npx playwright test auth.spec.ts
npx playwright test user-workflows.spec.ts

Step 6: Review and Adjust

• Manually review screenshots
• Retake any that need adjustment
• Update markdown files if needed

Customizing for Your Implementation

When you're ready to run these, you may need to update:

1. Selectors: Update CSS selectors to match your actual HTML structure
2. Routes: Ensure all routes match your router configuration
3. Wait conditions: Adjust timeouts based on your app's performance
4. Modal IDs: Update modal selectors to match your implementation

Tips for Better Screenshots

1. Wait for animations: Add page.waitForTimeout(500) after clicking to let animations complete
2. Full page vs viewport: Use fullPage: true for complete page screenshots
3. Hide scrollbars: Use page.evaluate(() => document.body.style.overflow = 'hidden') for cleaner screenshots
4. Dark theme: Most screenshots will use the default Tokyo Night theme
5. Clean test data: Use consistent test data for reproducible screenshots

Estimated Time Investment

Task	Time
Install & configure Playwright	15 min
Seed test database	30 min
Write Playwright scripts	2-3 hours
Run screenshot automation	10 min
Review & retake screenshots	30-60 min
Update markdown files	30-60 min
Total	4-6 hours

Future Enhancements

• Visual Regression Testing: Use Playwright to detect UI changes
• Multi-theme Screenshots: Automatically capture all theme variations
• Multi-language Screenshots: Capture screenshots in different locales
• Auto-update on Deploy: Run screenshots as part of CI/CD on documentation updates

References

• Playwright Documentation
• Playwright Screenshots API
• Bookhoard Frontend Templates
• Bookhoard API Documentation

---

Created by: GLM (OpenCode)
Version: 1.0
Ready for Implementation: When frontend development is complete