╔╗╔╔═╗╔═╗╦  ╦
║║║║╣ ╠╦╝╚╗╔╝
╝╚╝╚═╝╩╚═ ╚╝

Autonomous QA Agent for Web Applications

Observe → Decide → Act → Detect

What is Nerv?

Nerv is a CLI tool that autonomously explores web applications and finds bugs. Point it at a URL — it launches a browser, navigates pages, clicks buttons, fills forms, and reports every issue it finds.

Two exploration modes:

• AI-guided (via Ollama) — an LLM decides what to click, type, and explore
• Systematic (fallback) — BFS crawl of all links, buttons, and forms

Bug detection covers:

• 🔴 Console errors & unhandled JS exceptions
• 🌐 Network failures (4xx, 5xx, timeouts)
• 🖼️ Broken images
• ♿ Accessibility issues (missing alt text, unlabeled inputs)
• ⚡ Performance problems (slow TTFB, slow DOM load)
• 🔒 Security red flags (HTTP forms, inline handlers)
• 📐 UI issues (horizontal overflow)

Quick Start

# Install dependencies
npm install

# Install Playwright browser
npx playwright install chromium

# Run a scan
node bin/nerv.js run https://example.com

Global install (optional)

npm link
nerv run https://example.com

Usage

nerv run <url> [options]

Options:
  --headed             Run browser visibly (not headless)
  --max-actions <n>    Maximum actions to perform (default: 30)
  --max-time <s>       Maximum time in seconds (default: 700)
  --model <name>       Ollama model to use (default: mistral)
  --no-ai              Disable AI, use systematic exploration only
  -o, --output <dir>   Output directory for reports (default: ./reports)
  -v, --verbose        Enable verbose debug logging

Examples

# Quick scan with defaults
nerv run https://myapp.com

# Thorough scan with visible browser
nerv run https://myapp.com --headed --max-actions 50 --max-time 700

# Systematic scan (no Ollama needed)
nerv run https://myapp.com --no-ai --max-actions 40

# Use deepseek-coder instead of mistral
nerv run https://myapp.com --model deepseek-coder

AI Mode (Ollama)

For AI-guided exploration, install and start Ollama:

# Install Ollama (macOS)
brew install ollama

# Pull a model
ollama pull mistral

# Start the server
ollama serve

Nerv auto-detects Ollama. If it's not running, Nerv falls back to systematic mode.

Report Format

Reports are saved as JSON in ./reports/:

{
  "meta": {
    "tool": "Nerv QA Agent",
    "version": "1.3.0",
    "timestamp": "2026-04-13T...",
    "targetUrl": "https://example.com"
  },
  "summary": {
    "totalBugs": 5,
    "critical": 0,
    "high": 2,
    "medium": 2,
    "low": 1,
    "byType": {
      "console_error": 2,
      "network_error": 1,
      "accessibility": 2
    },
    "pagesVisited": 8,
    "actionsPerformed": 30,
    "durationSeconds": 45
  },
  "bugs": [ ... ],
  "visitedUrls": [ ... ]
}

Architecture

bin/nerv.js          CLI entry point (Commander.js)
src/
├── index.js         Main orchestrator
├── agent.js         Agent loop (observe → decide → act → detect)
├── crawler.js       Playwright browser control
├── ollama.js        Ollama LLM integration
├── detector.js      Bug detection (console, network, DOM, perf, security)
├── reporter.js      JSON report generation
└── logger.js        ANSI-colored console output

Requirements

• Node.js ≥ 18
• Playwright (auto-installed)
• Ollama (optional, for AI mode)
  • Recommended models: mistral, deepseek-coder
  • Works on 8GB Mac

License

MIT