ABE — Autonomous Bug Explorer

An open-source framework that autonomously explores web applications, provokes failures, and generates reproducible bug reports for developers and AI coding assistants.

Quick Start

# Install dependencies
npm install

# Install Playwright browser
npx playwright install chromium

# Run ABE against your app
npm run explore -- --url http://localhost:3000 --output ./reports

# Replay a discovered bug
npm run replay -- --report reports/<anomaly-id>/report.json

What ABE Does

1. Launches a headless browser and navigates to the target URL
2. Discovers interactive elements (links, buttons, inputs)
3. Executes actions deterministically using a seed
4. Observes HTTP responses, JS exceptions, and console errors
5. Detects anomalies using heuristic rules
6. Captures screenshots and DOM snapshots at anomaly moments
7. Generates a JSON + Markdown bug report with exact reproduction steps

Project Structure

src/
├── core/               # Interfaces, StateGraph, ExplorationEngine, AnomalyDetector
└── plugins/
    ├── agents/         # PlaywrightAgent
    ├── collectors/     # Screenshot, Network, DOMSnapshot
    ├── exporters/      # JSON, Markdown
    └── reproducers/    # PlaywrightReproducer

tests/                  # Unit and integration tests (mirrors src/)
reports/                # Generated bug reports (runtime)
logs/                   # Session logs in .jsonl format (runtime)

CLI Options

Option	Default	Description
--url	http://localhost:3000	Target URL
--output	./reports	Output directory
--seed	42	Random seed for determinism
--max-steps	100	Maximum exploration steps

Web UI (API Server + Dashboard)

ABE also ships a web dashboard for launching explorations and watching results in real time.

# Start both the API server (port 3001) and the React frontend (port 5173)
npm run dev:all

Then open http://localhost:5173 in your browser.

API Server only

npm run server

REST endpoints available at http://localhost:3001/api/:

Method	Path	Description
POST	/sessions	Start a new exploration
GET	/sessions	List all sessions
GET	/sessions/:id	Session detail
DELETE	/sessions/:id	Stop a running session
GET	/anomalies	List all anomalies
GET	/anomalies/:id	Anomaly detail
GET	/anomalies/:id/screenshot	Bug screenshot (PNG)
POST	/anomalies/:id/replay	Trigger anomaly replay

WebSocket events are emitted via socket.io (connect to http://localhost:3001).

Docker

Run the full stack (backend + frontend) with a single command:

docker-compose up --build

Service	Host port	Description
Backend	3001	Express API + socket.io
Frontend	5173	React dashboard (nginx)

Then open http://localhost:5173 in your browser.

Reports and logs are persisted via Docker volumes (./reports, ./logs).

Development

npm run build       # Compile TypeScript
npm test            # Run all tests
npm run typecheck   # Type-check without compiling

Architecture

frontend/ (React + Vite, port 5173)
    ↕ HTTP REST + WebSocket
src/server/ (Express + socket.io, port 3001)
    ↕ imports
src/core/ + src/plugins/ (ABE engine)

Core principles:

• Deterministic: all random choices are seeded and logged
• Plugin-oriented: core engine never imports concrete plugin classes
• Reproducible: every anomaly includes an exact action trace and replay script