feat: Page DOM and Screenshot Capture for UA Testing

[younglim]

feat: Page DOM and Screenshot Capture for UA Testing

Summary

• Adds OOBEE_SAVE_DOM env var to save the full-page DOM HTML for each scanned page
• Adds OOBEE_SAVE_PAGE_SCREENSHOT env var to save full-page desktop and mobile viewport screenshots for each scanned page
• Generates a domManifest.json mapping each page URL to its hash, saved file paths, and any errors encountered during capture
• Supported across all scan types: Website, Sitemap, Intelligent, LocalFile, and Custom

How it works

Env Variable	Effect
OOBEE_SAVE_DOM=1	Saves full DOM to <results>/pageDOMs/<hash>-<truncated_path>.html
OOBEE_SAVE_PAGE_SCREENSHOT=1	Saves desktop PNG to pageDOMs/desktopPageScreenshots/ and mobile PNG to pageDOMs/mobilePageScreenshots/

• Hash: 7-character SHA-256 of the page URL (consistent, like git short hashes)
• Truncated path: URL pathname with / replaced by _, max 80 chars, for human readability
• Filename collisions: Resolved by appending -2, -3, etc. before the file extension
• Mobile viewport: Width derived programmatically from Playwright's devices['iPhone 11'] profile. The viewport is resized in-place (no separate tab), then restored to the original desktop size
• Manifest: pageDOMs/domManifest.json is written when either env var is enabled

Output structure

results/<token>/pageDOMs/
├── <hash>-<truncated_path>.html              # Full DOM (OOBEE_SAVE_DOM)
├── domManifest.json                         # URL → file path mapping
├── desktopPageScreenshots/
│   └── <hash>-<truncated_path>.png
└── mobilePageScreenshots/
    └── <hash>-<truncated_path>.png

Example domManifest.json

{
  "generatedAt": "2026-07-06T13:22:06.000Z",
  "pages": [
    {
      "url": "https://example.com/about",
      "hash": "a1b2c3d",
      "domFile": "pageDOMs/a1b2c3d-about.html",
      "desktopScreenshot": "pageDOMs/desktopPageScreenshots/a1b2c3d-about.png",
      "mobileScreenshot": "pageDOMs/mobilePageScreenshots/a1b2c3d-about.png",
      "errors": []
    }
  ]
}

Files changed

File	Change
src/crawlers/pageCapture.ts	New — core module for DOM/screenshot capture and manifest generation
src/crawlers/crawlDomain.ts	Calls capturePageData() after axe scan
src/crawlers/crawlSitemap.ts	Calls capturePageData() after axe scan
src/crawlers/crawlLocalFile.ts	Calls capturePageData() after axe scan
src/crawlers/custom/utils.ts	Calls capturePageData() after axe scan
src/combine.ts	Calls writeManifest() + resetCaptureEntries() post-crawl
README.md	Documents new env vars
AGENTS.md	Documents new env vars and output structure

Test plan

• Run sitemap scan with OOBEE_SAVE_DOM=1 — verify .html files appear in pageDOMs/
• Run website scan with OOBEE_SAVE_PAGE_SCREENSHOT=1 — verify desktop and mobile PNGs
• Run with both env vars set — verify domManifest.json contains all entries
• Verify filenames are flat (no nested subdirectories under pageDOMs/)
• Verify mobile screenshots use iPhone 11 width (375px)
• Verify desktop viewport is restored after mobile screenshot
• Run without env vars set — verify no pageDOMs/ directory is created
• Test URL with long path (>80 chars) — verify truncation
• Test filename collision scenario — verify -2 suffix applied