ReproCase

Automated website fault detection & reproduction. ReproCase scans a website in a real browser, finds faults that have objective evidence, independently re-verifies every fault, and emits reproducible Playwright regression tests plus reports written for humans and AI coding assistants.

• 中文文档：README.zh-CN.md

What it detects

Fault	Evidence collected	Default severity
Uncaught JS exceptions (incl. unhandled promise rejections)	message, stack, exact click path, screenshot, browser trace	high
Page load failures (HTTP ≥ 400 or navigation error)	status code / error text, screenshot	high
First-party resource failures (scripts, images, CSS, ...)	resource URL, status / net error, screenshot	medium
Broken internal links	target URL, status, all linking pages	medium
Horizontal overflow (desktop + mobile viewports)	scrollWidth vs clientWidth, offending elements, screenshot	low
Console errors	message, page, reproducibility	suspected (informational)

Every finding is labelled verified (reproduced in independent browser runs) or suspected (observed once but not proven reproducible). ReproCase never invents results, never judges business logic, and always lists what it did not check.

Quick start

# Try it in ~30 seconds — scans the bundled demo site (4 planted faults):
git clone https://github.com/geyutu6755/ReproCase.git
cd ReproCase && npm install && npx playwright install chromium   # npm install auto-builds dist/
npx reprocase demo            # writes reprocase-demo-report/report.html and opens it

Start a real project:

npx reprocase init            # writes a starter reprocase.config.json (refuses to overwrite)
npx reprocase doctor          # environment check: Node, Chromium, config, target, writability
npx reprocase scan            # scan the configured entry, write the full report bundle
npx reprocase scan --url http://localhost:3000/ --out my-report
npx reprocase compare before/result.json after/result.json   # new / resolved / persistent

Exit codes: 0 no findings at/above threshold · 1 findings exist · 2 scan failed (bad config, entry unreachable). CI-friendly — see docs/cli.md.

Live demo report — generated by the CI pipeline against the bundled demo site on every push to main.

What a scan produces

my-report/
├── report.html            self-contained offline HTML report (also index.html)
├── result.json            machine-readable scan result
├── issues.md              GitHub-Issue markdown covering all findings
├── issues/<id>.md         one ready-to-paste issue per finding
├── generated-tests/       runnable Playwright reproduction tests + config + README
└── artifacts/
    ├── screenshots/       evidence screenshots
    └── traces/            Playwright traces (playwright show-trace)

The generated Playwright tests assert the fault is still present: they pass while the bug exists (proving stable reproduction) and fail once you fix it — the failure tells you to swap in the commented-out "after fix" assertion, turning the file into a permanent regression guard.

Comparison across scans

reprocase compare matches findings by stable fingerprint (type + URL path + error signature), so volatile ids, timestamps and query strings never create phantom diffs. A fault is only reported resolved when the current scan actually covered its page — shrunk coverage is marked unconfirmed, never claimed as a fix. Output: compare.json + a self-contained compare.html.

CI / GitHub Actions

Run ReproCase on every push or PR against your own site — clean passes, new faults gate the build, reports land as artifacts (traces stripped before upload):

- name: ReproCase scan
  uses: geyutu6755/ReproCase/.github/actions/reprocase-scan@v0.5.0
  with:
    url: http://localhost:3000/
    compare-with: .reprocase/baseline/result.json

Full inputs, exit-code semantics and the baseline flow: docs/github-actions.md.

FAQ & troubleshooting

• "Refusing to scan non-local host" — ReproCase only scans localhost unless you list the host in allowedDomains. That is the authorization gate, not a bug.
• npx playwright install chromium fails / browser missing — run npx reprocase doctor; it prints the exact path it looked at and the fix command.
• No buttons were explored — check the Exploration log section in the report: buttons matching risky keywords (pay, delete, run, ...) are skipped by the read-only-first policy. Precisely authorize test controls via exploration.allowSelectors in the config.
• A fault I fixed still shows as "unconfirmed resolved" — the comparison scan did not visit that page. Rerun with the same scope as the baseline, then compare again.
• SPA routes show up twice — a deep link re-renders the app; the same JS fault is reported under its own URL fingerprint by design.
• Node version — Node 22 or 24 (the current LTS lines; CI-tested on both). Node 18 and Node 20 reached End-of-Life (Apr 2025 / Mar 2026) and are no longer supported.

Safety & privacy by default

• Only localhost targets are allowed unless the host is explicitly listed in allowedDomains.
• Read-only-first exploration: no form filling, no submissions, dialogs are always dismissed, risky-looking buttons (pay / delete / submit / send / ...) are never clicked.
• Hard budgets: max pages, max depth, max actions per page, run timeout, request delay. No infinite crawling.
• URLs in reports are redacted (token / password / email / session query params masked).
• Traces are captured automatically for localhost targets only. Traces and screenshots may contain unredacted page content, URLs and query parameters — review them before sharing this report publicly.

See docs/architecture.md for the full model.

Documentation

• Installation
• CLI usage
• Configuration (example config)
• Architecture
• Test baselines · Compatibility matrix
• GitHub Actions integration
• npm publishing
• Contributing · Security policy · Changelog · License (MIT)

Development

npm install
npx playwright install chromium
npm run build      # tsc -> dist/
npm test           # unit tests
npm run test:all   # unit + integration (real browser) + CLI end-to-end

The test suite scans the bundled demo site and asserts that all four planted faults are detected, that the clean control pages produce zero findings, and that the generated tests reproduce every fault through the real Playwright runner.

Status

v0.5.0 — developer-workflow integration release (composite GitHub Action, baseline new-fault gating, honest CI exit semantics, cluster-aware issue markdown). See the changelog, the Actions guide and the compatibility matrix. npm i -g github:…#tag now works and the quick start drops the manual build), a reconciled Node baseline (22+, since Node 18/20 are End-of-Life; CI-tested on 22 & 24), the deprecated Vitest poolOptions config fixed, and refreshed real screenshots. Detection itself is unchanged from v0.3.x — cross-page fault clusters, adaptive async observation, shadow DOM + same-origin iframe detection, scan --compare-with, and the report/attachment security hardening of v0.3.2–v0.3.3. See the changelog, test baselines and the compatibility matrix. Known limitations are listed in the changelog and in the "Not checked" section of every report.

License

MIT © ReproCase contributors