127 lines
3.6 KiB
Markdown
127 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|