Metadata-Version: 2.4
Name: argus-testing
Version: 0.1.0
Summary: AI-powered exploratory testing agent that discovers bugs like a real user
Project-URL: Homepage, https://github.com/chriswu727/argus
Project-URL: Repository, https://github.com/chriswu727/argus
Author-email: Yichen Wu <yichenwujob@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,ai,claude-code,exploratory-testing,mcp,playwright,qa,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: litellm>=1.40.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Description-Content-Type: text/markdown

# 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.

```bash
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.

```bash
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](https://github.com/BerriAI/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
