Bug Hunter Replay

简体中文

Bug Hunter Replay is a local-first Playwright CLI for checking authorized local or owned web apps. It performs bounded same-origin exploration, captures browser/runtime/network evidence, writes shareable reports, generates editable repro specs, runs route smoke checks, and compares saved runs offline.

In 30 seconds: point it at a local demo or owned app, let it explore within explicit safety limits, and get a reviewable evidence package: report.json, report.md, report.html, screenshots, optional trace, repro.spec.ts, and diff summaries between runs. It is not a hosted scanner, security product, exploit tool, or public crawling service.

Why This Project Exists

AI-generated pages and fast-moving demos often fail in small but costly ways: console errors, blank pages, broken routes, slow endpoints, failed network calls, or UI actions that regress after a prompt or code change. Bug Hunter Replay turns those failures into local, auditable artifacts that can be reviewed by a developer, interviewer, or project owner.

The project is designed to show practical engineering signals:

• browser automation with Playwright;
• bounded crawl design and same-origin safety;
• action filtering for destructive or risky UI elements;
• browser/page/network evidence capture;
• report generation in machine-readable and human-readable formats;
• reproducible Playwright specs;
• smoke testing for key routes;
• offline diffing between saved report JSON files;
• Vitest coverage and staged project documentation.

What It Can Do

Capability	What it proves	Output
run / scan	Bounded same-origin exploration with safe action execution	JSON, Markdown, HTML, screenshots, repro spec
Safety filters	Skips external origins, hash loops, destructive actions, password/file inputs, and unknown risky submits	Action timeline with skip reasons
Evidence capture	Console errors, page errors, request failures, HTTP 4xx/5xx, slow requests, blank pages	Normalized issues and screenshots
smoke	Fast route health checks without clicking discovered actions	Same report format plus smoke summary
diff	Offline comparison of two saved runs	New, resolved, persistent issue groups
Demo site	Deterministic local showcase routes	Reproducible sample reports

Portfolio Evidence

Verified local evidence is committed in this repository:

• Full showcase page
• Sample HTML report
• Sample Markdown report
• Sample JSON report
• Generated Playwright repro spec
• Diff baseline JSON
• Sample diff JSON
• Sample diff Markdown
• Showcase page screenshot
• Report overview screenshot
• Report Viewer screenshot
• Architecture notes
• Report format notes
• Report schema and run index notes
• Report viewer notes
• Limitations and non-goals
• Safety boundary
• Repository audit

These are local-first examples committed in the repository. This project does not currently claim an npm release, hosted public demo, GitHub Pages, Vercel, Cloudflare deployment, or public scanning service.

Full Showcase Page

The repository includes a homepage-style project showcase at reports/showcase/index.html. It is the curated page used for local portfolio presentation, separate from generated scan output.

Preview it locally from the repository root:

corepack pnpm showcase

Then open:

http://127.0.0.1:4172/reports/showcase/

If port 4172 is already in use, Vite prints the alternate local URL. The 127.0.0.1 address is intentionally local-only; the committed HTML and screenshot are the portable evidence for GitHub review.

Report Preview

Open the Report Viewer

The Report Viewer is a local-only interface for saved Bug Hunter Replay artifacts. It defaults to the committed sample run index at reports/index.json, falls back to committed sample reports, and lets you select local report.json or diff-report.json files in the browser. Files are read locally; they are not uploaded.

Start it from the repository root:

corepack pnpm viewer

Then open:

http://127.0.0.1:4174/viewer/

The viewer does not run hosted scans, crawl public sites, deploy anything, or publish an npm package.

Tech Stack

• Node.js 20+
• TypeScript
• pnpm / Corepack
• Commander
• Playwright
• Vitest
• ESLint

Quick Start

For a practical local walkthrough, see Usage Guide. For learning and interview prep, also see Value Proposition, Interview Notes, Usage Checklist, and Usage Walkthrough.

Install dependencies and build:

corepack pnpm install
corepack pnpm exec playwright install chromium --only-shell
corepack pnpm build

Start the deterministic demo site in one terminal:

corepack pnpm demo-site -- --port 4173

Optional: start the repository showcase page in another terminal:

corepack pnpm showcase

Run bounded exploration from another terminal:

corepack pnpm dev -- run http://127.0.0.1:4173/ --max-depth 2 --max-actions 16 --slow-threshold 100 --no-trace

The CLI prints the generated report.json path under reports/<run-id>/ and updates the local reports/index.json run registry.

Command Reference

run / scan

run explores a target URL with bounded same-origin crawl and safe action execution. scan is an alias for authorized local validation.

corepack pnpm dev -- run http://127.0.0.1:4173/ --max-depth 2 --max-actions 16 --slow-threshold 100 --no-trace
corepack pnpm dev -- scan http://127.0.0.1:4173/ --max-depth 1 --max-actions 2 --slow-threshold 100 --no-trace

Common options:

• --max-depth: limits crawl depth.
• --max-actions: limits executed safe actions.
• --same-origin-only: keeps cross-origin targets skipped by default. The integrated explorer never executes cross-origin navigation; external targets are recorded as skipped evidence.
• --slow-threshold: marks slow requests.
• --output: chooses the report output root.
• --no-trace: disables Playwright trace collection for lightweight runs.

smoke

smoke opens explicit routes and captures passive browser/page/network evidence. It does not click discovered page actions.

corepack pnpm dev -- smoke http://127.0.0.1:4173/ --routes /,/console-error,/page-error --slow-threshold 100 --no-trace

Route input accepts / paths, full same-origin URLs, repeated routes, and empty entries. Repeated and empty routes are normalized. Cross-origin routes are skipped by default and recorded in the smoke summary.

diff

diff compares two saved Bug Hunter Replay JSON reports without opening a browser.

corepack pnpm dev -- diff examples/reports/diff-baseline-report.json examples/reports/sample-report.json --output reports/diff-check

Diff mode reads local JSON reports only. It reports:

• new issues in the current report;
• resolved issues that existed only in the baseline;
• persistent issues that appear in both reports;
• summary deltas for issue count, visited pages, executed actions, and smoke route status when available.

Issue matching uses a stable key derived from issue type, canonical URL, and normalized signal signature. It does not compare issues by array index or report-local id.

Future Agent Tooling

MCP tool mode is planned for a later phase and is not part of this Report Viewer milestone.

Demo Site

The demo site is a lightweight local Node.js HTTP server with stable routes for showcasing the capture pipeline:

• / - homepage with same-origin links and safe triggers.
• /console-error - button-triggered console.error.
• /page-error - button-triggered runtime exception.
• /network-error - failed request trigger.
• /server-error - HTTP 500 response.
• /slow-api - delayed API response.
• /blank - button-triggered blank page.
• /form - safe form controls for fill/select coverage.

Start it with:

corepack pnpm demo-site -- --port 4173

Report Output

Each run creates a directory under reports/ and updates a generated local run index:

reports/
  index.json
  <run-id>/
    report.json
    report.md
    report.html
    repro.spec.ts
    screenshots/
      initial.png
      step-001-before.png
      step-001-after.png
    traces/
      trace.zip

traces/trace.zip is only written when trace collection is enabled. It is enabled by default and disabled with --no-trace.

Artifact roles:

• report.json - structured run data for tools or deeper inspection.
• report.md - readable Markdown summary for GitHub issues, PR notes, or review handoff.
• report.html - offline HTML report with inline CSS and relative screenshot links.
• repro.spec.ts - editable Playwright spec with assertions for supported captured signals and test.step notes for unstable signals.
• screenshots/ - initial and before/after step screenshots.
• traces/trace.zip - Playwright trace for timeline-level debugging when enabled.
• reports/index.json - local run registry for run, scan, and smoke outputs. The repository commits a sanitized sample index for the viewer; generated run directories remain ignored by Git. diff does not write the index because diff compares saved files offline.

Repro Spec

Each scan and smoke run writes repro.spec.ts beside the reports. The generated spec uses Playwright Test and can be run while the target app is reachable at the same URL:

corepack pnpm exec playwright test reports/<run-id>/repro.spec.ts

The generator creates assertions for supported captured signals: console errors, page errors, failed requests, HTTP 4xx/5xx, slow requests, and blank pages. For issue types that are not stable enough for generated assertions, it writes a test.step note instead of a false passing assertion.

Safety Boundary

Use Bug Hunter Replay only on websites you own or have explicit permission to test.

This project is not a security scanner, vulnerability exploitation tool, attack framework, dashboard, cloud platform, or AI debugging product. It is a local debugging/demo utility for bounded browser exploration, runtime capture, network capture, screenshots, traces, and local report generation.

Default safety behavior:

• Same-origin exploration is enabled by default.
• External origins are skipped by default and are not executed by the integrated explorer.
• mailto:, tel:, javascript:, data:, blob:, and other non-HTTP(S) URLs are skipped.
• Hash-only links are skipped to avoid same-document crawl loops.
• Dangerous English and Chinese keywords are skipped.
• Destructive-looking href, form action, button text, aria-label, name, and id values are treated as risk signals.
• input[type=submit], button[type=submit], default submit buttons inside forms, password inputs, and file inputs are skipped by default.
• Unknown form submission is not performed.

See docs/safety-boundary.md for the detailed safety boundary.

Architecture

flowchart TD
  CLI[CLI: bug-hunter run] --> Config[Run config]
  Smoke[CLI: bug-hunter smoke] --> Config
  Diff[CLI: bug-hunter diff] --> Saved[Saved report.json files]
  Config --> Browser[Playwright browser context]
  Browser --> Trace[Optional trace.zip]
  Browser --> Explorer[Queue-based bounded BFS explorer]
  Explorer --> Discovery[Action discovery]
  Discovery --> Safety[Safety filter]
  Safety --> Executor[Safe action execution]
  Browser --> Recorder[Console, page, and network capture]
  Executor --> Screenshots[Screenshot artifacts]
  Executor --> Blank[Blank-page checks]
  Recorder --> Analyzer[Issue analyzer]
  Blank --> Analyzer
  Analyzer --> Reports[JSON, Markdown, HTML, repro.spec.ts]
  Screenshots --> Reports
  Trace --> Reports
  Saved --> DiffReports[diff-report.json and diff-report.md]
  Demo[Built-in demo site] --> CLI

Loading

See docs/architecture.md for the full module map and data flow.

Quick Verification Flow

corepack pnpm install --frozen-lockfile
corepack pnpm build
corepack pnpm test
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm dev -- --help
corepack pnpm dev -- diff examples/reports/diff-baseline-report.json examples/reports/sample-report.json --output reports/diff-check

For browser-backed verification, start the demo site and run run or smoke from another terminal:

corepack pnpm demo-site -- --port 4173
corepack pnpm dev -- run http://127.0.0.1:4173/ --max-depth 2 --max-actions 16 --slow-threshold 100 --no-trace
corepack pnpm dev -- smoke http://127.0.0.1:4173/ --routes /,/console-error,/page-error --slow-threshold 100 --no-trace

Development Checks

corepack pnpm build
corepack pnpm test
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm audit

Project Status

This repository is a local-first toolkit, not a hosted service. The CLI, local Report Viewer, committed sample artifacts, report schema reader, run index writer, and diff mode are implemented in the repository. It has not been published to npm or deployed as a hosted public demo, scanner, crawler, or production QA platform.