convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
ironclawdevs27

Argus — QA Automatizado Baseado em IA

ironclawdevs27/Argus

Detecção automática de bugs visuais, API e performance via Chrome DevTools

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que integra detecção automática de bugs em aplicações web via Chrome DevTools Protocol, sem necessidade de escrever testes. Detecta 140+ tipos de problemas (regressões visuais, loops de API, falhas de acessibilidade, vazamentos de estilo CSS, problemas de segurança) e entrega relatórios em Slack ou dashboard HTML local.

Instalação

$npx convez-ai ironclawdevs27/Argus

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 meses
Versão
v9.8.0
Issues abertas
9
Contribuidores
1

Casos de uso

  • Auditoria contínua de qualidade sem manutenção de testes
  • Detecção de regressões visuais e CSS drift em CI/CD
  • Validação de acessibilidade e conformidade WCAG em escala
  • Detecção de loops de API, vazamentos de memória e problemas de performance
  • Verificação de segurança (tokens expostos, CSP, vulnerabilidades npm)

Veredito

Argus é uma ferramenta sólida e pragmática para QA automatizado sem sobrecarga de testes manuais. Seu catálogo de 32 engines de análise cobre casos reais (segurança, perf, acessibilidade), mas depende de Chrome headless e configuração inicial em .mcp.json — adequado para times que buscam automação QA profissional.

README

A tradução para o português deste README ainda está na fila.

Argus — AI-Powered Automated QA

npm MCP Server Harness License: MIT

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


Quick Start

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

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

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

Or via Claude Code CLI:

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:

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

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, 140 distinct issue types, zero test-file maintenance:

CategoryWhat it detects
JavaScriptUncaught exceptions, unhandled promise rejections, console.error on critical routes
Network & APIHTTP 5xx, 401/403 auth failures, duplicate API calls (infinite loops), 4xx errors, broken links
PerformanceLCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB
Accessibilityaxe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy
SEOMissing meta description, OG tags, canonical, viewport, h1
SecurityAuth tokens in localStorage/URL, eval(), missing CSP/X-Frame-Options, CSP violations, missing SRI on external scripts, source map exposure, open redirects, npm CVEs
CSSCascade overrides, component style leaks, unused rules, React inline style conflicts
Contentnull/undefined as visible text, lorem ipsum, broken images, empty data lists
ResponsiveHorizontal overflow at 375px/768px, touch targets < 44×44px
MemoryDetached DOM nodes via V8 heap snapshot, heap growth across navigation
VisualPixel-level screenshot regression via pixelmatch (≥0.1% warning, ≥5% critical)
FigmaDesign-to-implementation fidelity — 13 property types (color, spacing, typography, shadows, etc.)
FormsMissing required, autocomplete, aria-describedby; unlabelled inputs
FontsFOIT, FOUT, missing fallbacks, slow loads > 1s, suboptimal formats
Motionprefers-reduced-motion violations, autoplay without pause controls
Network baselineNew requests, missing requests, status-code regressions vs saved HAR baseline
Environment diffDev vs staging — screenshot diff, DOM changes, console/network regressions

And every finding is post-processed with:

Post-processorWhat it adds
Intelligent baseline filteringFindings 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 linkingNew 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.


MCP Tools

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

ToolDescription
argus_auditFast pass — JS, network, accessibility, SEO, security, CSS, content
argus_audit_fullDeep pass — adds Lighthouse, responsive checks, memory leak detection, hover-state bugs
argus_compareDiff dev vs staging — screenshots, findings delta, environment regressions
argus_get_contextCapture everything broken on the open tab for Claude to diagnose
argus_watch_snapshotSnapshot the open tab without navigating (preserves auth/form state)
argus_last_reportReturn last JSON report without re-running
argus_design_auditFigma URL → 13 design-token finding types (color, spacing, typography, shadows, etc.)
argus_visual_diffScreenshot baseline comparison. Pass updateBaseline: true to reset.
argus_pr_validateFetch GitHub PR diff → map changed files to affected routes → targeted audit → { blocked, findings }

Example prompts:

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

RequirementVersion
Node.jsv20.19+
ChromeStable (desktop or headless)
Claude CodeLatest (npm install -g @anthropic-ai/claude-code)
Slack workspaceOptional — 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 in your project root
TARGET_DEV_URL=http://localhost:3000
TARGET_STAGING_URL=https://staging.example.com   # optional — enables argus_compare

Optional — Slack notifications:

  1. api.slack.com/apps → Create New App → name it BugBot
  2. OAuth & Permissions → Bot Token Scopes: chat:write, files:write, files:read
  3. Install to workspace → copy the xoxb-... token
  4. Create channels #bugs-critical, #bugs-warnings, #bugs-digest and run /invite @BugBot in each
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)

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)

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

Manual setup (skip the wizard):

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

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          # 72 unit tests — no Chrome required
npm run test:harness       # 149-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:

# 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):

/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):

SecretRequiredValue
TARGET_STAGING_URLYesYour staging base URL
SLACK_BOT_TOKENNoxoxb-... token (omit for HTML-only mode)
SLACK_CHANNEL_CRITICALNo*Channel ID (needed when Slack is configured)
SLACK_CHANNEL_WARNINGSNo*Channel ID
SLACK_CHANNEL_DIGESTNo*Channel ID
GITHUB_TOKENNoAuto-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

VariableDefaultDescription
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
PORT3001Slack slash-command server port
REPORT_OUTPUT_DIR./reportsWhere to write JSON reports
ARGUS_CONCURRENCY1Parallel MCP clients for route crawling
ARGUS_LOG_LEVELinfotrace / debug / info / warn / error
ARGUS_LOG_PRETTY—Set 1 for human-readable logs in dev
ARGUS_RETRY_ATTEMPTS3Max retries for navigate/fill MCP calls
ARGUS_WATCH_INTERVAL_MS1000Watch mode poll interval (ms)
ARGUS_WATCH_UI_PORT3002Watch mode web dashboard port
ARGUS_SOURCE_DIR—App source path — enables env-var / feature-flag / dead-route analysis
ARGUS_ENV_FILE—Path to app .env for codebase cross-reference
SCREENSHOT_DIFF_THRESHOLD0.5Pixel 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_THRESHOLD1New 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_MS1000Slow web font load threshold (ms)
A11Y_CONTRAST_AA4.5WCAG AA min contrast ratio for CVD simulation

Troubleshooting

Chrome DevTools MCP not connecting

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


How Argus Differs From Playwright / Cypress

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

Playwright / CypressArgus
PurposeTest your logic and API contractsCatch what the user actually sees
What it catchesRegressions in behaviorCSS drift, visual regressions, API loops, console noise, perf budgets
When it runsIn your test suiteContinuously, on the live running app
SetupWrite test filesConfigure routes in targets.js
OutputPass / failStructured Slack reports with screenshots

Known Limitations

All 845 harness assertions pass (845/845) — there are currently no known MCP- or Chrome-layer restrictions. Soft assertions (Lighthouse, performance traces) still require non-headless Chrome and are skipped in headless CI.


Project Structure

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/           — 149-block correctness harness, 845 hard assertions, 63 fixture pages
test/unit/              — 72 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

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

License

MIT © ironclawdevs27


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

argus-qa.com · npm · MCP Registry

Ver o original no GitHub

Bom para

Relacionados