argus-testing 0.1.0

AI-powered exploratory testing agent that discovers bugs like a real user

Argus

AI-powered exploratory QA agent. Give it a URL, it explores your app like a real user — clicking buttons, filling forms, trying edge cases — and finds bugs that scripted tests miss.

Unlike Playwright or Cypress, you don't write test scripts. Argus discovers bugs you didn't think to test for.

What It Catches

Traditional test tools only catch what you explicitly script. Argus catches:

• Console errors & crashes — JS exceptions, unhandled promises
• Broken API calls — HTTP 4xx/5xx responses
• Fake success operations — "Saved!" toast shown but server returned 500
• Silent data loss — delete says "Deleted!" but item still exists on refresh
• Broken date formatting — "1.52 days ago" instead of "2 days ago"
• Count mismatches — dashboard says "7 tasks" but there are actually 8
• Dead links — navigation links pointing to 404 pages
• XSS vulnerabilities — unsanitized user input reflected in HTML

Quick Start (MCP Server for Claude Code)

The recommended way to use Argus. Claude Code becomes the AI brain — no API key needed.

pip install argus-testing
playwright install chromium
claude mcp add argus -- argus-mcp

Then in Claude Code:

"Test my app at http://localhost:3000, focus on the checkout flow"

Claude Code will explore your app using Argus tools, try edge cases, verify that actions actually persist, and generate an HTML bug report.

MCP Tools

Tool	What it does
start_session(url)	Launch browser, navigate to URL
get_page_state()	See all interactive elements + page content + counts + toasts
click(index)	Click an element
type_text(index, text)	Type into an input field
navigate(url)	Go to a URL
screenshot(name)	Capture the current page
get_errors()	Get console/network errors + smart detection (broken dates, count mismatches, misleading toasts)
verify_action(type, text, url)	Verify a delete/edit actually persisted by navigating and checking
end_session()	Close browser, generate HTML report

Alternative: Standalone CLI

Bring your own LLM API key. Argus has a built-in AI planner that decides what to explore.

pip install argus-testing
playwright install chromium

export DEEPSEEK_API_KEY=sk-...   # or OPENAI_API_KEY, ANTHROPIC_API_KEY

argus http://localhost:3000 --model deepseek/deepseek-chat -n 50
argus http://localhost:3000 -f "test login with edge cases" --headed

Supports 100+ models via LiteLLM: OpenAI, Anthropic, DeepSeek, Gemini, Ollama (free/local), etc.

Smart Detection

Argus goes beyond console errors. It extracts page content and analyzes it:

Detection	How it works	Example bug found
State verification	After delete/edit, navigates back and checks if the change persisted	"Deleted!" shown but item reappears on refresh
Toast + error cross-check	Correlates success toasts with HTTP 500 responses	Settings shows "Saved!" but server crashed
Text anomaly scanning	Regex patterns on visible page text	"NaN", "1.52 days ago", eternal "Loading..."
Count consistency	Compares displayed counts against actual rendered items	Header says "7 tasks" but 8 items visible
CSS state analysis	Checks semantic CSS classes for contradictory states	"0 remaining" shown in red (should be success)

Bug Report

Each session generates a self-contained HTML report with:

• Bug cards with severity, type, description, and reproduction steps
• Embedded screenshots (base64 — no external files needed)
• Testing timeline showing every page visited
• Console and network error logs

How It Works

You give a URL
  → Argus opens a real browser (Playwright)
  → AI explores: clicks, types, navigates, tries edge cases
  → Smart detection analyzes page content after every action
  → Generates HTML report with all bugs found

Architecture

argus/
├── browser.py       # Playwright driver + DOM extraction + page content analysis
├── detector.py      # Smart bug detection (5 detection methods)
├── mcp_server.py    # MCP server (12 tools) for Claude Code
├── explorer.py      # CLI exploration loop
├── planner.py       # LLM planner for CLI mode (LiteLLM)
├── reporter.py      # Self-contained HTML report generator
├── models.py        # Data models
├── config.py        # YAML config + focus areas
└── cli.py           # CLI entry point

Requirements

• Python 3.10+
• Chromium (auto-installed via playwright install chromium)

License

MIT