io.github.ironclawdevs27/argus

Official

by ironclawdevs27 · JavaScript

Automated web QA via Chrome DevTools MCP — a11y, security, visual, env diff, CI; Aegis redaction.

Automated web QA testing via Chrome DevTools with accessibility and security checks.

Topics

automationchrome-devtoolsmcp-servernpm-packageqatestingweb-testing

README.md19 KBView on GitHub

Argus — AI-Powered Automated QA

Argus catches the bugs your test suite misses — visual regressions, API loops, CSS drift, console noise, accessibility failures, and more — and delivers rich reports to Slack (or a local HTML dashboard).

Quick Start · Features · Setup · MCP Tools · CLI Commands · Troubleshooting · Full Reference

</div>

Quick Start

No install required. npx auto-downloads Argus on first run.

Step 1 — Add to .mcp.json in your project root:

json

{
  "mcpServers": {
    "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
    "argus":           { "command": "npx", "args": ["-y", "argusqa-os"] }
  }
}

Or via Claude Code CLI:

bash

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
claude mcp add argus -- npx -y argusqa-os

Step 2 — Start Chrome with remote debugging:

bash

# macOS
open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new

# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"

# Linux
google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox

Step 3 — Run an audit:

code

Run argus_audit on http://localhost:3000

Argus scans your app and either posts findings to Slack or opens a local report.html. That's it.

What Argus Catches

32 analysis engines, 149 distinct issue types, zero test-file maintenance:

Category	What it detects
JavaScript	Uncaught exceptions, unhandled promise rejections, `console.error` on critical routes
Network & API	HTTP 5xx, 401/403 auth failures, duplicate API calls (infinite loops), 4xx errors, broken links
Performance	LCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB
Accessibility	axe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy
SEO	Missing meta description, OG tags, canonical, viewport, h1
Security	Auth tokens in localStorage/URL, `eval()`, missing CSP/X-Frame-Options, CSP violations, missing SRI on external scripts, source map exposure, open redirects, npm CVEs
CSS	Cascade overrides, component style leaks, unused rules, React inline style conflicts
Content	`null`/`undefined` as visible text, lorem ipsum, broken images, empty data lists
Responsive	Horizontal overflow at 375px/768px, touch targets < 44×44px
Memory	Detached DOM nodes via V8 heap snapshot, heap growth across navigation
Visual	Pixel-level screenshot regression via pixelmatch (≥0.1% warning, ≥5% critical)
Figma	Design-to-implementation fidelity — 13 property types (color, spacing, typography, shadows, etc.)
Forms	Missing `required`, `autocomplete`, `aria-describedby`; unlabelled inputs
Fonts	FOIT, FOUT, missing fallbacks, slow loads > 1s, suboptimal formats
Motion	`prefers-reduced-motion` violations, `autoplay` without pause controls
Network baseline	New requests, missing requests, status-code regressions vs saved HAR baseline
Environment diff	Dev vs staging — screenshot diff, DOM changes, console/network regressions

And every finding is post-processed with:

Post-processor	What it adds
Intelligent baseline filtering	Findings that flip-flop across runs are tagged `noisy` and downgraded to info — pure cross-run heuristics, no API calls (`ARGUS_NOISE_FILTER=0` to disable)
Root cause linking	New findings are annotated with the recent git commits and files most likely to have caused them (`ARGUS_ROOT_CAUSE=0` to disable)

All findings are classified as critical / warning / info and routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, see REFERENCE.md.

Confidentiality — Aegis Egress Boundary

Default ON. Argus audits your app for secrets and vulnerabilities — so its findings are exactly the data you least want leaving your machine. Aegis redacts them at every external boundary before they cross.

A finding sent to an external sink — an MCP tool response (which lands in the calling agent's context window and transits to that agent's model provider), a Slack message, a GitHub PR comment + its ::error annotations, the hosted/CI HTML report, or CI logs — is reduced to a need-to-know projection: a sensitive finding crosses as its type + route + severity + a 🔒 marker, and never its raw payload (message, evidence, request/response bodies, headers, cookies, stack). URLs are projected with the query string stripped (tokens hide there). A benign finding keeps its message — but that message is still scrubbed for any accidentally-embedded secret or PII.

Principle	Behavior
Local fidelity preserved	The on-disk JSON report and the locally-opened HTML keep 100% detail — redaction only removes detail on the way out
Fail-closed	On any classifier error or unknown finding shape, Aegis redacts more, never less
Deny-by-default	Only an explicit allowlist of safe fields ever crosses; a new field leaks nothing until deliberately allowlisted
5-layer detection	Category rules ∪ 13 secret regexes ∪ statistical rarity (entropy / token-efficiency) ∪ 7 Luhn-validated PII rules ∪ context boosting
Opt-out	`ARGUS_REDACT_SENSITIVE=0` → output is byte-identical to pre-Aegis

This implements the OWASP LLM02:2025 — Sensitive Information Disclosure mitigations (data minimization, redaction, deny-by-default egress filtering) at Argus's own boundaries. An optional, local-only re-hydration vault (ARGUS_REDACT_VAULT=1) can mint reversible, information-free tokens for diff-stable artifacts — re-inflate locally with npm run report:rehydrate. Full behavior change is documented in CHANGELOG.md.

MCP Tools

Ask Claude (or any MCP client) — no terminal required:

Tool	Description
`argus_audit`	Fast pass — JS, network, accessibility, SEO, security, CSS, content
`argus_audit_full`	Deep pass — adds Lighthouse, responsive checks, memory leak detection, hover-state bugs
`argus_compare`	Diff dev vs staging — screenshots, findings delta, environment regressions
`argus_get_context`	Capture everything broken on the open tab for Claude to diagnose
`argus_watch_snapshot`	Snapshot the open tab without navigating (preserves auth/form state)
`argus_last_report`	Return last JSON report without re-running
`argus_design_audit`	Figma URL → 13 design-token finding types (color, spacing, typography, shadows, etc.)
`argus_visual_diff`	Screenshot baseline comparison. Pass `updateBaseline: true` to reset.
`argus_pr_validate`	Fetch GitHub PR diff → map changed files to affected routes → targeted audit → baseline-aware block decision (blocks on findings the PR introduces) + idempotent PR comment + Check Run → `{ blocked, findings, baseline, reporting }`

Every tool response is projected through the Aegis egress boundary before it reaches the agent, and carries an optional redaction rider ({ redacted, total }) when sensitive detail was withheld.

Example prompts:

code

Run argus_audit on http://localhost:3000/checkout
Run argus_audit_full on http://localhost:3000/dashboard
Run argus_compare
Run argus_get_context

Full Setup

Prerequisites

Requirement	Version
Node.js	v20.19+
Chrome	Stable (desktop or headless)
Claude Code	Latest (`npm install -g @anthropic-ai/claude-code`)
Slack workspace	Optional — omit for local `report.html` mode

Option A — MCP Server (recommended for Claude Code users)

No local install needed. Use the Quick Start above, then add your target URL:

env

# .env in your project root
TARGET_DEV_URL=http://localhost:3000
TARGET_STAGING_URL=https://staging.example.com   # optional — enables argus_compare

Optional — Slack notifications:

api.slack.com/apps → Create New App → name it BugBot
OAuth & Permissions → Bot Token Scopes: chat:write, files:write, files:read
Install to workspace → copy the xoxb-... token
Create channels #bugs-critical, #bugs-warnings, #bugs-digest and run /invite @BugBot in each

env

SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_CRITICAL=C0000000000
SLACK_CHANNEL_WARNINGS=C0000000001
SLACK_CHANNEL_DIGEST=C0000000002

Without Slack: Argus auto-generates reports/report.html and opens it in your browser — zero extra config.

Option B — npm Package (CI / dev dependency)

bash

npm install --save-dev argusqa-os
npx argus init   # interactive wizard — detects framework, discovers routes, writes .env
npm run crawl    # run after Chrome is started

Option C — Clone the Repository (contributors / full source)

bash

git clone https://github.com/ironclawdevs27/Argus.git
cd Argus
npm install
npm run init     # interactive setup wizard

Manual setup (skip the wizard):

bash

cp .env.example .env
# Fill in TARGET_DEV_URL and optional Slack tokens

Then configure your routes in src/config/targets.js:

export const routes = [
  { path: '/',          name: 'Home',      critical: true,  waitFor: 'main' },
  { path: '/login',     name: 'Login',     critical: true,  waitFor: 'form' },
  { path: '/dashboard', name: 'Dashboard', critical: true,  waitFor: '[data-testid="dashboard"]' },
  { path: '/settings',  name: 'Settings',  critical: false, waitFor: null },
];

critical: true — errors on this route go to #bugs-critical
waitFor — CSS selector Argus waits for before capturing (signals page-ready)

CLI Commands

bash

npm run chrome         # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
npm run doctor         # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
npm run crawl          # Batch audit of all configured routes
npm run compare        # Dev vs staging diff (CSS-only if no staging URL)
npm run watch          # Passive monitor — polls open Chrome tab every 1s
npm run report:html    # Generate reports/report.html from last JSON audit
npm run report:pdf     # Export HTML report to A4 PDF (requires: npm install puppeteer)
npm run server         # Start Slack slash-command server (port 3001)
npm run init           # Interactive setup wizard
npm run test:unit          # 495 unit tests — no Chrome required
npm run test:harness       # 168-block correctness harness — requires Chrome
npm run test:harness:log   # same, but tees full output to harness-results.txt
npm run test:coverage      # merged unit + harness coverage gate (requires Chrome)

Watch mode — live monitoring as you develop:

bash

# Terminal 1: start your app
npm run dev

# Terminal 2: start Argus watcher
npm run watch
# Ctrl+C → stops monitor and writes reports/report.html

Slack slash command (on-demand from any channel):

code

/argus-retest https://staging.example.com/checkout

To expose the server via tunnel: cloudflared tunnel --url http://localhost:3001 (free, no account required). Set the resulting URL as the Request URL in Slack App → Slash Commands.

GitHub Actions CI

Add to your repo's secrets (Settings → Secrets → Actions):

Secret	Required	Value
`TARGET_STAGING_URL`	Yes	Your staging base URL
`SLACK_BOT_TOKEN`	No	`xoxb-...` token (omit for HTML-only mode)
`SLACK_CHANNEL_CRITICAL`	No*	Channel ID (needed when Slack is configured)
`SLACK_CHANNEL_WARNINGS`	No*	Channel ID
`SLACK_CHANNEL_DIGEST`	No*	Channel ID
`GITHUB_TOKEN`	No	Auto-injected by Actions for PR comments + Check Runs

The included workflow runs on push to main, daily at 6 AM UTC, and on manual trigger. If critical issues are found, the pipeline fails.

Environment Variables

<details> <summary>Full reference (click to expand)</summary>

Variable	Default	Description
`TARGET_DEV_URL`	—	Required. Base URL of your dev environment
`TARGET_STAGING_URL`	—	Staging URL — enables `argus_compare`; omit for CSS-only mode
`SLACK_BOT_TOKEN`	—	`xoxb-...` token. Omit for local `report.html` mode
`SLACK_SIGNING_SECRET`	—	For `/argus-retest` slash command verification
`SLACK_CHANNEL_CRITICAL`	—	Channel ID for critical bugs
`SLACK_CHANNEL_WARNINGS`	—	Channel ID for warnings
`SLACK_CHANNEL_DIGEST`	—	Channel ID for info / daily digest
`PORT`	`3001`	Slack slash-command server port
`REPORT_OUTPUT_DIR`	`./reports`	Where to write JSON reports
`ARGUS_CONCURRENCY`	`1`	Parallel MCP clients for route crawling
`ARGUS_LOG_LEVEL`	`info`	`trace` / `debug` / `info` / `warn` / `error`
`ARGUS_LOG_PRETTY`	—	Set `1` for human-readable logs in dev
`ARGUS_RETRY_ATTEMPTS`	`3`	Max retries for `navigate`/`fill` MCP calls
`ARGUS_WATCH_INTERVAL_MS`	`1000`	Watch mode poll interval (ms)
`ARGUS_WATCH_UI_PORT`	`3002`	Watch mode web dashboard port
`ARGUS_SOURCE_DIR`	—	App source path — enables env-var / feature-flag / dead-route analysis and framework-aware PR route mapping (import-graph: a changed component/stylesheet → only the routes that render it)
`ARGUS_ENV_FILE`	—	Path to app `.env` for codebase cross-reference
`SCREENSHOT_DIFF_THRESHOLD`	`0.5`	Pixel diff % threshold for environment comparison
`GITHUB_TOKEN`	—	For PR comments + Check Runs
`GITHUB_REPOSITORY`	—	`owner/repo` format
`GITHUB_PR_NUMBER`	—	Auto-injected by Actions from PR context
`ARGUS_CRITICAL_THRESHOLD`	`1`	New criticals before blocking merge (0 = never block)
`ARGUS_DIFF_IMAGE_URL`	—	Visual diff image URL to embed in PR comment
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	OTLP collector for Jaeger / Grafana Tempo
`FIGMA_API_TOKEN`	—	Required for `argus_design_audit`
`FONT_SLOW_MS`	`1000`	Slow web font load threshold (ms)
`A11Y_CONTRAST_AA`	`4.5`	WCAG AA min contrast ratio for CVD simulation
`ARGUS_REDACT_SENSITIVE`	`ON`	Aegis egress redaction. `0` disables (byte-identical pre-Aegis output)
`ARGUS_REDACT_MODE`	`mask`	Matched-span style: `mask` / `label` / `hash` / `token` / `drop`
`ARGUS_REDACT_HTML`	off local / ON in CI	`1` redacts the hosted HTML report too
`ARGUS_REDACT_VAULT`	`OFF`	`1` (with `ARGUS_REDACT_MODE=token`) mints reversible `AEGIS_<hmac16>` tokens into a local `0600` vault; re-inflate with `npm run report:rehydrate`

</details>

Troubleshooting

Chrome DevTools MCP not connecting

bash

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
# Restart Claude Code after adding

Slack messages not posting

Token must start with xoxb- (not xoxp-, xoxe-, or xapp-)
Run /invite @BugBot in each channel
Required scopes: chat:write, files:write, files:read

Screenshots are blank

Page hasn't settled — increase pageSettleMs in src/config/targets.js or add a waitFor selector for the route

/argus-retest returns "dispatch_failed"

Tunnel URL changed — update the Request URL in Slack App → Slash Commands and reinstall

CSS analysis returns empty results

Page may be behind auth — ensure you're logged in on the Chrome instance Argus is controlling

CI pipeline fails immediately

Chrome may not start fast enough — increase sleep 3 to sleep 5 in .github/workflows/argus.yml

How Argus Differs From Playwright / Cypress

Argus is a complementary layer, not a replacement for unit or E2E tests:

	Playwright / Cypress	Argus
Purpose	Test your logic and API contracts	Catch what the user actually sees
What it catches	Regressions in behavior	CSS drift, visual regressions, API loops, console noise, perf budgets
When it runs	In your test suite	Continuously, on the live running app
Setup	Write test files	Configure routes in `targets.js`
Output	Pass / fail	Structured Slack reports with screenshots

Known Limitations

All 978 harness assertions pass (978/978) — there are currently no known MCP- or Chrome-layer restrictions. Lighthouse now runs in headless (after the lighthouse_audit argument fix); the remaining soft assertions (perf traces, GC-dependent heap-growth) are promoted to counted hard assertions only in the weekly strict-soft lane (harness-strict.yml) via ARGUS_HARNESS_STRICT_SOFT.

Project Structure

code

src/
  argus.js              — single-page audit entry point
  mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
  orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
  adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
  config/targets.js     — routes, thresholds, auth steps
  cli/
    init.js             — argus init interactive setup wizard
    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
    pr-validate.js      — headless CI entry point for GitHub Actions
test-harness/           — 168-block correctness harness, 978 hard assertions, 64 fixture pages
test/unit/              — 495 Vitest unit tests (no Chrome required)
landing/                — Product landing page (React 19 + Vite + Tailwind)

Full source map → CLAUDE.md · MCP/DSL reference → SKILL.md

Contributing

Fork the repo and create a branch
npm run test:unit — verify without Chrome (495 tests)
npm run test:harness — full integration coverage (requires Chrome on port 9222)
Open a PR — Argus audits itself via the CI workflow

License

Argus Panoptes — the all-seeing giant of Greek mythology who never slept.

argus-qa.com · npm · MCP Registry

</div>

Install

Configuration

Environment variables

TARGET_DEV_URLrequired

Base URL of the dev environment to audit (e.g. http://localhost:3000)

TARGET_STAGING_URL

Base URL of the staging environment — used by argus_compare for dev vs staging diff. Omit to use CSS analysis mode.

SLACK_BOT_TOKENsecret

Slack bot token (xoxb-...) for posting reports. Omit to generate a local report.html instead.

FIGMA_API_TOKENsecret

Figma personal access token — enables argus_design_audit to fetch design specs from a Figma frame and compare them against the live DOM (13 fidelity finding types). Omit to skip design fidelity audits.

ARGUS_REDACT_SENSITIVE

Aegis confidentiality egress boundary. Default ON: every tool response is redacted so secrets, PII, and exploit detail never cross into the calling agent's context (the local on-disk report keeps full fidelity). Set to 0 for byte-identical pre-Aegis output.

claude_desktop_config.json

{
  "mcpServers": {
    "argus": {
      "command": "npx",
      "args": [
        "-y",
        "argusqa-os@9.9.0"
      ],
      "env": {
        "TARGET_DEV_URL": "<YOUR_TARGET_DEV_URL>",
        "TARGET_STAGING_URL": "<YOUR_TARGET_STAGING_URL>",
        "SLACK_BOT_TOKEN": "<YOUR_SLACK_BOT_TOKEN>",
        "FIGMA_API_TOKEN": "<YOUR_FIGMA_API_TOKEN>",
        "ARGUS_REDACT_SENSITIVE": "<YOUR_ARGUS_REDACT_SENSITIVE>"
      }
    }
  }
}