Argus — Chrome DevTools MCP Reference

1. What Argus Is

Argus is an AI-driven automated QA harness that audits web pages against 67 detection categories (positively verified by the correctness harness except 3 environment-limited Chrome-Issues detectors, which are covered as negative controls) using Chrome DevTools Protocol (CDP) via the chrome-devtools MCP server. It drives a real Chromium browser, executes multi-step user flows, and emits structured JSON findings.

Entry points

• src/argus.js — single-page audit (CLI)
• src/batch-runner.js — multi-page batch audit
• src/mcp-server.js — MCP server (AI-callable via Claude or any MCP client; registers argus_audit / argus_audit_full / argus_compare / argus_last_report / argus_watch_snapshot / argus_get_context / argus_design_audit / argus_visual_diff / argus_pr_validate)
• test-harness/validate.js — 171-block correctness harness (998 hard assertions)
• test-harness/harness-config.js — fixture page routing table

2. MCP Tool Reference

All tools are accessed via the mcp object injected into argus.js / flow-runner.js.

Navigation & Page Lifecycle

Critical rule: Always call navigate_page and then wait_for before any inspection or interaction. Never assume a page is ready after navigate_page alone.

navigate_page type variants:

await mcp.navigate_page({ type: 'url', url: 'https://example.com' });
await mcp.navigate_page({ type: 'back' });
await mcp.navigate_page({ type: 'forward' });
await mcp.navigate_page({ type: 'reload' });

navigate_page_history — preferred for back/forward in multi-step flows:

await mcp.navigate_page_history({ navigate: 'back' });
await mcp.navigate_page_history({ navigate: 'forward' });

Use for SPA route history, breadcrumb navigation, and multi-step form flows where users may backtrack.

Snapshot & Screenshot

Snapshot-first rule: Use take_snapshot to discover element uids before calling any interaction tool. Never guess a uid.

Screenshot variants:

await mcp.take_screenshot({ filePath: './screen.png' });                            // viewport only
await mcp.take_screenshot({ filePath: './full.png', fullPage: true });              // full page
await mcp.take_screenshot({ uid: 'e4', filePath: './element.png' });               // single element
await mcp.take_screenshot({ filePath: './screen.jpg', format: 'jpeg', quality: 80 }); // compressed

DOM inspection over screenshots: Prefer evaluate_script to read page state — structured data, no 5MB limit. Only use take_screenshot for visual evidence or pixel-level verification.

DPR coordinate conversion: CDP interaction events use CSS pixels, but screenshot pixel coordinates are physical pixels. Convert before using screenshot coords for interaction:

const dpr = unwrapEval(await mcp.evaluate_script({ function: `() => window.devicePixelRatio` }));
// CSS px = screenshot px / DPR
const cssX = Math.round(screenshotX / dpr);
const cssY = Math.round(screenshotY / dpr);

take_snapshot response is wrapped in a markdown code fence — always strip before parsing:

function unwrapFence(raw) {
  const text = typeof raw === 'string' ? raw : JSON.stringify(raw ?? '');
  const m = text.match(/```(?:json|text)?\s*([\s\S]*?)\s*```/);
  return m ? m[1] : text;
}

File inputs appear in the snapshot as button "Choose file:" (new format, uid=N_M). Use extractFileInputUid from flow-runner.js which tries five patterns in order:

// 1. Primary — new format: uid=N_M button "Choose file:" value="No file chosen"
const p1 = text.match(/uid=([^\s]+)[^\n]*value="No file chosen"/);
if (p1) return p1[1];
// 2. Fallback — "Choose file" keyword anywhere on the uid line
const p2 = text.match(/uid=([^\s]+)[^\n]*[Cc]hoose file/);
if (p2) return p2[1];
// 3. Legacy text-tree — "- input [Upload] e4" role (pre-v8 snapshot format)
const p3 = text.match(/\[Upload\]\s+([A-Za-z0-9_-]+)/);
if (p3) return p3[1];
// 4. Legacy JSON tree — uid near "inputType":"file" marker (either order)
const jsonA = text.match(/"inputType"\s*:\s*"file"[^}]{0,200}"uid"\s*:\s*"([^"]+)"/);
if (jsonA) return jsonA[1];
const jsonB = text.match(/"uid"\s*:\s*"([^"]+)"[^}]{0,200}"inputType"\s*:\s*"file"/);
if (jsonB) return jsonB[1];
// 5. Line-scan — any snapshot line with uid= near upload/file keywords
for (const line of text.split('\n')) {
  if (/upload|file.input|Choose file/i.test(line)) {
    const m = line.match(/uid=([^\s]+)/);
    if (m) return m[1];
  }
}

Interaction Tools (require uid from snapshot)

`select_option` is a DSL action only — it is not an MCP tool. In flow-runner.js the select_option case resolves a uid via resolveUidForSelector then calls mcp.fill({ uid, value }). Never call mcp.select_option(...) — the MCP server has no such tool.

uid contract: Every interaction tool requires a uid from the current page snapshot. If the page changes (navigation, SPA route), the uid changes — always re-snapshot after transitions.

Focus before `type_text`: type_text types into whichever element currently has focus. The fill step with typing: true (inside runFlow) handles focus by calling mcp.click({ uid }) before typing — this works correctly within a flow. When writing direct test code outside `runFlow` (e.g., in validate.js), mcp.click({ uid }) may not reliably set document.activeElement for text inputs in headless Chrome. Use evaluate_script to focus explicitly in that context:

// In direct test code outside runFlow — use evaluate_script:
await mcp.evaluate_script({ function: `() => document.querySelector('#my-input').focus()` });
await mcp.type_text({ text: 'hello' });

// Inside a flow — use fill with typing: true (handles focus internally via mcp.click):
{ action: 'fill', selector: '#my-input', value: 'hello', typing: true }

fill_form — prefer over multiple fill calls when filling several fields at once:

await mcp.fill_form({
  fields: [
    { uid: emailUid, value: '[email protected]' },
    { uid: passUid,  value: 's3cr3t' },
    { uid: nameUid,  value: 'Test User' },
  ],
});

includeSnapshot: false — suppress the automatic re-snapshot after interactions when you don't need updated state immediately (cuts round-trips by ~40% in bulk flows):

await mcp.click({ uid: 'e4', includeSnapshot: false });
await mcp.fill({ uid: 'e5', value: 'test', includeSnapshot: false });

press_key modifier syntax:

await mcp.press_key({ key: 'Enter' });
await mcp.press_key({ key: 'Tab' });
await mcp.press_key({ key: 'Escape' });
await mcp.press_key({ key: 'ArrowDown' });
await mcp.press_key({ key: 'Control+A' });   // select all
await mcp.press_key({ key: 'Shift+Tab' });   // reverse tab
await mcp.press_key({ key: 'Meta+K' });      // Cmd+K (Mac)

Script Evaluation

// Simple expression
const raw = await mcp.evaluate_script({
  function: `() => document.querySelector('#id').textContent`,
});

// Multi-statement — always wrap in IIFE
const raw2 = await mcp.evaluate_script({
  function: `() => {
    const score = document.querySelector('.score')?.textContent;
    const items = Array.from(document.querySelectorAll('.item')).map(el => el.textContent);
    return JSON.stringify({ score, items });
  }`,
});

// Pass DOM element by uid
const raw3 = await mcp.evaluate_script({
  function: `(el) => ({ text: el.innerText, tag: el.tagName })`,
  args: [{ uid: 'e4' }],
});

Response is wrapped in a markdown code fence — always unwrap:

function unwrapEval(raw) {
  const s = typeof raw === 'string' ? raw : JSON.stringify(raw ?? '');
  const m = s.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
  const inner = m ? m[1].trim() : s.trim();
  try { return JSON.parse(inner); } catch { return inner; }
}

Batch DOM operations: Never make separate evaluate_script calls for independent DOM reads/actions — batch in one IIFE:

// ❌ Slow — 3 round-trips
await mcp.evaluate_script({ function: `() => document.getElementById('a').click()` });
await mcp.evaluate_script({ function: `() => document.getElementById('b').click()` });

// ✅ Fast — 1 round-trip
await mcp.evaluate_script({
  function: `() => { ['a', 'b'].forEach(id => document.getElementById(id)?.click()); return 'done'; }`,
});

DOM-change rule: When the DOM may change between calls (pagination, live updates, reactive frameworks), collect all required data in one call. Index-based selection across multiple calls is unsafe — the DOM may reorder:

// ❌ Fragile — DOM may shift between calls
const count = unwrapEval(await mcp.evaluate_script({ function: `() => document.querySelectorAll('.item').length` }));
const third  = unwrapEval(await mcp.evaluate_script({ function: `() => document.querySelectorAll('.item')[2]?.textContent` }));

// ✅ Safe — atomic snapshot
const items = unwrapEval(await mcp.evaluate_script({
  function: `() => Array.from(document.querySelectorAll('.item')).map(el => el.textContent.trim())`,
}));

Network & Console

Timing: Call list_network_requests immediately after wait_for networkidle to capture all requests before the list clears.

Filtering & pagination:

await mcp.list_network_requests({ types: ['fetch', 'xhr'] });
await mcp.list_network_requests({ pageSize: 50, pageIdx: 0 });
await mcp.list_network_requests({ includePreservedRequests: true });
await mcp.list_console_messages({ types: ['error', 'warn'] });
await mcp.list_console_messages({ pageSize: 100, pageIdx: 0 });
await mcp.list_console_messages({ types: ['issue'], includePreservedMessages: true });

Issues panel is a separate namespace — types: ['issue'] surfaces the Chrome DevTools Issues panel, not the console. It catches CSP violations, CORS blocks, mixed content, cookie misconfigs, deprecated API use, and native low-contrast. None of these appear in `types: ['error']`.

// Always capture Issues separately from console errors
const consoleErrors = normalizeArray(await mcp.list_console_messages({ types: ['error'] }));
const issuesPanel   = normalizeArray(await mcp.list_console_messages({ types: ['issue'], includePreservedMessages: true }));

Performance

Named insights for performance_analyze_insight:

await mcp.performance_analyze_insight({ insightName: 'LCPBreakdown' });    // LCP subpart breakdown
await mcp.performance_analyze_insight({ insightName: 'DocumentLatency' }); // TTFB + parse time
// Omit insightName for all insights

Emulation

// Combined device + network
await mcp.emulate({ device: 'iPhone 12', networkCondition: 'Slow 3G' });
await mcp.emulate({ geolocation: { latitude: 37.7749, longitude: -122.4194 } });
await mcp.emulate({ cpuThrottlingRate: 4 });
await mcp.emulate({ device: null, networkCondition: null }); // reset

// Change one dimension at a time — emulate only applies the properties you pass
await mcp.resize_page({ width: 375, height: 812 });
await mcp.emulate({ networkConditions: 'Slow 3G' }); // Offline | Slow 3G | Fast 3G | Slow 4G | Fast 4G
await mcp.emulate({ cpuThrottlingRate: 4 });          // 1=no throttle, 4=4×, 6=6×, 20=max

Pass multiple properties to emulate to set several conditions in one call; pass one property to change a single dimension without affecting others.

Snapshot Verbosity

await mcp.take_snapshot();                 // compact — role + name + uid only
await mcp.take_snapshot({ verbose: true }); // verbose — includes all ARIA attributes and states

Use verbose: true only when debugging ARIA attributes or hunting hidden states.

2b. CdpBrowserAdapter Quick Reference

All Argus analyzers and test code use browser.* — never mcp.* directly. CdpBrowserAdapter wraps every MCP tool call. Import from src/adapters/browser.js.

import { CdpBrowserAdapter } from '../adapters/browser.js';
const browser = new CdpBrowserAdapter(mcp);

Patterns:

// Navigate + settle + screenshot
await browser.navigate(url);
await browser.waitFor({ state: 'networkidle' }).catch(() => {});
await new Promise(r => setTimeout(r, 1000));  // let observers settle
const shot = await browser.screenshot({ format: 'png' });
const pngBuf = Buffer.from(shot.data, 'base64');

// Evaluate and unwrap
const raw = await browser.evaluate(`() => document.title`);
const title = unwrapEval(raw);  // import unwrapEval from utils/mcp-client.js

// Get uid for interaction
const snapRaw = await browser.snapshot();
const snapText = unwrapFence(snapRaw);
const uid = snapText.match(/uid=([^\s]+)[^\n]*#my-button/)?.[1];

2c. Argus MCP Tool Reference

All 9 tools are exposed by src/mcp-server.js and accessed via Claude or any MCP client (argus server in .mcp.json).

Quick Reference

argus_compare reads TARGET_DEV_URL / TARGET_STAGING_URL from env — no per-call override. argus_last_report returns {"error":"No reports found in reports/"} when no audits have run.

argus_audit — parameter schema

{ url: string, critical?: boolean, cache?: boolean }
// critical: escalate console.error to 'critical' severity (default: false)
// cache:    return cached result for this URL if one exists in this session (default: false)
//           cache hit response includes _cached: true, _cachedAt: ISO timestamp
//           session-scoped Map, max 20 entries, LRU eviction

argus_watch_snapshot / argus_get_context — parameter schema

{
  url?:         string,  // defaults to TARGET_DEV_URL; does NOT navigate
  tabId?:       string,  // Chrome page/tab ID — get from open_tabs in prior argus_get_context
  snapshot_id?: string,  // argus_get_context only — pass back from prior call to get a diff
}

Fix loop with `snapshot_id`:

// Step 1 — capture current state
// Response: { snapshot_id: 'abc123', critical_issues: [...], summary: '2 criticals on ...' }

// Step 2 — apply fix, then pass snapshot_id back
// Response: { snapshot_id: 'xyz789', resolved: [...], new_issues: [...], persisting: [...] }
//   resolved   — findings cleared since last snapshot
//   new_issues — findings that appeared since last snapshot
//   persisting — findings unchanged since last snapshot
// Repeat until resolved.length > 0 && critical_issues.length === 0

Multi-tab: get tab IDs from open_tabs array in any argus_get_context response, then pass as tabId.

argus_visual_diff — parameter schema

{
  url:             string,   // full URL to capture and compare
  updateBaseline?: boolean,  // delete existing baseline and save fresh PNG (default: false)
  baselineDir?:    string,   // override baseline directory (default: reports/baselines/screenshots/)
}
// summary.status: 'baseline_created' | 'regression' | 'no_change'
// regression severity: 'warning' (≥0.1% pixels changed) | 'critical' (≥5%)

argus_design_audit — parameter schema

{
  url:           string,  // page to audit (must be reachable by Chrome)
  figmaFrameUrl: string,  // Figma URL — must include ?node-id=42%3A0 (frame node ID)
}
// Requires FIGMA_API_TOKEN env var
// summary keys: tokenMismatches, missingComponents, colorMismatches, typographyMismatches,
//               spacingMismatches, radiusMismatches, boundsOverflows, positionDrifts,
//               strokeMismatches, shadowMismatches, opacityMismatches, gapMismatches, textMismatches

argus_pr_validate — parameter schema

{
  prUrl:        string,              // GitHub PR URL, e.g. https://github.com/owner/repo/pull/42
  targetUrl?:   string,              // base URL to audit (default: TARGET_DEV_URL env var)
  githubToken?: string,              // GitHub token (default: GITHUB_TOKEN env var; optional for public repos)
  blockOn?:     'none'|'warning'|'critical',  // default: ARGUS_BLOCK_ON env var → 'critical'
}
// Returns:
// {
//   prUrl, targetUrl, affectedRoutes: string[], changedFiles: string[],
//   findings: Finding[], perRoute: { route, critical, warning, info }[],
//   summary: { critical, warning, info },
//   blocked: boolean,  // true when findings ≥ blockOn threshold
//   blockOn: string,
// }
// Infrastructure files (next.config.*, layout.*, package.json, etc.) trigger a full audit.
// Slug heuristic: maps "src/pages/checkout.tsx" → routes with "checkout" segment.
// Conservative fallback: if no routes match, ALL routes are audited.
// AI verdict (PASS/WARN/BLOCK + attribution) is NOT included here — that's in argus-pro.

Audit cache internals

Both snapshotStore (fix-loop snapshots) and auditCache (audit results) are module-level Maps in mcp-server.js. Max 20 entries each, oldest-first LRU eviction. They reset when the MCP server process restarts.

3. Core Workflow Patterns

Pattern A — Snapshot-First Interaction

navigate_page → wait_for → take_snapshot → extract uid → interact (click/fill/etc.)

Never skip the snapshot step. The uid is the only safe element identifier.

Pattern B — Error Recovery

When a tool throws:

1. Check list_console_messages for JS errors on the page
2. Call take_snapshot — inspect accessibility tree for unexpected modal/overlay
3. Check list_network_requests — look for failed requests (4xx/5xx)
4. Screenshot for visual evidence: take_screenshot

Pattern C — Performance Profiling

emulate (device + network) → navigate_page → performance_start_trace
→ wait_for networkidle → performance_stop_trace → performance_analyze_insight
→ lighthouse_audit

Always emulate target conditions before starting the trace.

Pattern D — Flow Execution (Argus-specific)

runFlow(flowConfig, baseUrl, mcp)
→ for each step: runStep(step, ctx) → emit finding on error
→ return { flowName, findings[] }

flow_step_failed findings are emitted automatically on step exceptions — never swallow step errors without re-throwing or recording them.

Pattern E — Investigate Before Interacting

Extract page structure in a single evaluate_script call before touching anything:

const recon = unwrapEval(await mcp.evaluate_script({
  function: `() => ({
    title: document.title,
    url: location.href,
    forms: document.forms.length,
    buttons: document.querySelectorAll('button').length,
    inputs: document.querySelectorAll('input').length,
    headings: Array.from(document.querySelectorAll('h1,h2,h3'))
               .map(h => ({ level: h.tagName, text: h.textContent.trim() })),
    mainHtml: document.body.innerHTML.slice(0, 2000),
  })`,
}));

Never interact blind.

Pattern F — Authenticated Browser State

When testing pages behind login, launch Chrome with the user's actual profile:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --profile-directory="Default"

# Linux
google-chrome --remote-debugging-port=9222 --profile-directory="Default"

# Windows (PowerShell) — fixed stable profile (persists cookies/cache across runs)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-devtools-profile"

Connect via --browserUrl=http://127.0.0.1:9222 in the MCP config.

4. Argus Flow Runner DSL

Defined in src/utils/flow-runner.js. Steps are objects with an action field.

All Supported Actions

// Navigation
{ action: 'navigate', url: 'https://example.com' }        // absolute URL
{ action: 'navigate', path: '/dashboard' }                // relative to baseUrl

// Waiting
{ action: 'waitFor', selector: '#loaded' }                // polls until selector appears (polling loop)
{ action: 'sleep', ms: 500 }                              // fixed delay (use sparingly)

// Interaction (uid resolved automatically from snapshot via resolveUidForSelector)
{ action: 'click', selector: 'button.submit' }
{ action: 'fill', selector: 'input[name=email]', value: '[email protected]' }
{ action: 'fill', selector: 'textarea', value: 'Hello', typing: true }  // typing:true → per-keystroke keyboard events via type_text (vs fill's single consolidated input event)
{ action: 'drag', sourceSelector: '.draggable', targetSelector: '.dropzone' }
{ action: 'upload_file', selector: 'input[type=file]', filePath: '/abs/path/to/file.txt' }
{ action: 'upload_file', uid: 'e4', filePath: '/abs/path/to/file.txt' }  // uid bypasses snapshot lookup

// Form
{ action: 'select_option', selector: 'select#country', value: 'US' }
{ action: 'select_option', uid: 'e5', value: 'US' }                      // uid bypasses snapshot lookup

// Keyboard
{ action: 'press_key', key: 'Enter' }
{ action: 'press_key', key: 'Tab' }

// Browser
{ action: 'handle_dialog', accept: true }                 // accept = true|false; text for prompt dialogs
{ action: 'handle_dialog', accept: false, text: 'No' }

// Inline assertions (stops flow on critical failure unless failFast: false)
{ action: 'assert', type: 'no_console_errors' }
{ action: 'assert', type: 'no_network_errors' }
{ action: 'assert', type: 'element_visible',     selector: '#confirm-banner' }
{ action: 'assert', type: 'element_not_visible', selector: '.spinner' }
{ action: 'assert', type: 'url_contains',        value: '/checkout/success' }
{ action: 'assert', type: 'no_js_errors' }

Not in flow DSL: hover, evaluate, screenshot, and type_text are not direct flow actions. — For keyboard input with events, use fill with typing: true. — For script execution or screenshots, call mcp.evaluate_script / mcp.take_screenshot directly in test code.

Selector Resolution

flow-runner.js resolves CSS selectors to uid via resolveUidForSelector before every interaction tool call — including click and fill. All MCP interaction tools require a `uid`; none accept a raw CSS selector. Passing { selector: '...' } to mcp.click or mcp.fill silently does nothing — always resolve to uid first.

waitFor vs wait_for: The DSL action is waitFor (camelCase) — it uses a polling loop via evaluate_script, not the MCP wait_for tool (which is unreliable in headless mode for missing elements). For network-idle waits, call mcp.wait_for({ state: 'networkidle' }) directly in test code after navigation.

upload_file uid Resolution (extractFileInputUid)

Five fallback strategies in order (v8 — new snapshot format uid=N_M):

1. uid=N_M … value="No file chosen" — primary; file inputs appear as button "Choose file:" in the accessibility tree
2. uid=N_M … Choose file — broader keyword fallback on the same uid line
3. [Upload] eN — legacy text-tree role format (pre-v8 snapshot format)
4. "inputType":"file" adjacent to "uid":"…" in JSON tree — either field order
5. Line-scan: any snapshot line containing uid= near upload/file keywords

5. Assertion Patterns (validate.js)

Hard vs. Soft

• Hard assertion (assert(condition, label)): throws immediately on failure, stops the block
• Soft assertion (findings.filter(...)): inspects findings array, assert at the end

Finding Shapes

All findings share: { type, severity, url, message? }

Post-processing annotations (added after applyBaseline in report-processor.js): isNew (baseline diff), noisy / noiseScore / originalSeverity (noise filter — flip-flopping findings downgraded to info, never suppressed), and rootCause: { files, commits, global } (root-cause linker, NEW findings only).

// ── Core (A1–A2) ──────────────────────────────────────────────────────────
{ type: 'broken_link',          url, status, sourceUrl }
{ type: 'console',              level, message, source, line, url }
{ type: 'uncaught_exception',   message, source, line, url }
{ type: 'unhandled_rejection',  message, url }
{ type: 'seo_missing_og',       message, severity: 'warning', url }
{ type: 'a11y_missing_name',    tag, role, snippet, message, severity: 'warning', url }

// ── Flow execution ─────────────────────────────────────────────────────────
{ type: 'flow_step_failed',   flowName, action, selector, message, severity: 'critical', url }
{ type: 'flow_assert_failed', flowName, assertType, message, severity, url }

// ── Chrome DevTools Issues panel ────────────────────
{ type: 'csp_violation',               message, url, severity: 'critical' }
{ type: 'cors_violation',              message, url, severity: 'critical'|'warning' }
{ type: 'mixed_content',               message, url, severity: 'warning' }
{ type: 'cookie_attribute_missing',    message, url, severity: 'warning' }
{ type: 'deprecated_api_use',          message, url, severity: 'info' }
{ type: 'low_contrast_native',         message, url, severity: 'warning' }
{ type: 'permission_policy_violation', message, url, severity: 'info' }

// ── Network timing ────────────────────
{ type: 'slow_third_party_blocking', requestUrl, waitMs, message, severity: 'warning', url }

// ── Heading structure ────────────────────
{ type: 'heading_level_skip', from, to, text, message, severity: 'warning', url }
//   from/to are heading level numbers (e.g. from:1, to:3)

// ── Keyboard accessibility ────────────────────
{ type: 'focus_visible_missing', tag, id, snippet, message, severity: 'warning', url }
{ type: 'focus_lost',            steps, message, severity: 'warning', url }  // steps = array of tab-step numbers; no fixture yet (v6.105)

// ── ARIA state ────────────────────
{ type: 'aria_expanded_no_controls', tag, id, snippet, message, severity: 'warning', url }
//   when aria-controls references a missing id, detail is folded into message

// ── Security (v6.101, v6.102) ────────────────────────────────────────────
{ type: 'security_no_https',          severity: 'warning', url }
{ type: 'security_iframe_no_sandbox', src, severity: 'warning', url }

// ── A7 Theme & Dark Mode ─────────────────────────────────────────────────
{ type: 'theme_no_dark_mode', message, severity: 'info', url }    // no prefers-color-scheme: dark rule
{ type: 'theme_static_var',   vars, count, message, severity: 'warning', url }  // CSS vars identical light vs dark
{ type: 'theme_summary',  hasDarkMode, rootVarCount, darkEmulated, message, severity: 'info', url }

// ── D9 Design Fidelity — 13 mismatch types ────────────────────────────────
{ type: 'design_token_mismatch',     token, expected, actual,   message, severity: 'warning', url }
{ type: 'design_component_missing',  name, selector,            message, severity: 'warning', url }
{ type: 'design_color_mismatch',     selector, expected, actual, delta, matchedSelector, message, severity: 'warning', url }
{ type: 'design_typography_mismatch',selector, field, expected, actual, matchedSelector, message, severity: 'warning', url }
  //   field: 'fontSize'|'fontWeight'|'lineHeight'|'fontFamily'|'letterSpacing'
{ type: 'design_spacing_mismatch',   selector, field, expected, actual, matchedSelector, message, severity: 'warning', url }
  //   field: 'paddingTop'|'paddingRight'|'paddingBottom'|'paddingLeft'|'gap'
{ type: 'design_radius_mismatch',    selector, corner, expected, actual, matchedSelector, message, severity: 'warning', url }
  //   corner: 'topLeft'|'topRight'|'bottomRight'|'bottomLeft'
{ type: 'design_bounds_overflow',    selector, expected, actual, matchedSelector,  message, severity: 'warning', url }
{ type: 'design_position_drift',     selector, axis, expected, actual, matchedSelector, message, severity: 'warning', url }
  //   axis: 'x'|'y'
{ type: 'design_stroke_mismatch',    selector, field, expected, actual, matchedSelector, message, severity: 'warning', url }
  //   field: 'color'|'weight'
{ type: 'design_shadow_mismatch',    selector, field, expected, actual, matchedSelector, message, severity: 'warning', url }
  //   field: 'offsetX'|'offsetY'|'blur'|'spread'|'color'
{ type: 'design_opacity_mismatch',   selector, expected, actual, matchedSelector, message, severity: 'warning', url }
{ type: 'design_gap_mismatch',       selector, expected, actual, matchedSelector, message, severity: 'warning', url }
{ type: 'design_text_mismatch',      selector, expected, actual, matchedSelector, message, severity: 'warning', url }
{ type: 'design_fidelity_summary',   tokenMismatches, componentMissing, colorMismatches, typographyMismatches,
                                      spacingMismatches, radiusMismatches, boundsOverflows, positionDrifts,
                                      strokeMismatches, shadowMismatches, opacityMismatches, gapMismatches,
                                      textMismatches, message, severity: 'info', url }

// ── Web Vitals & Bundle Size ──────────────────────────────────────────────
{ type: 'perf_lcp',          value, threshold, message, severity: 'warning'|'critical', url }
  //   warning ≥2500ms, critical ≥4000ms
{ type: 'perf_cls',          value, threshold, message, severity: 'warning'|'critical', url }
  //   warning ≥0.1, critical ≥0.25
{ type: 'perf_fcp',          value, threshold, message, severity: 'warning'|'critical', url }
  //   warning ≥1800ms, critical ≥3000ms
{ type: 'perf_tti',          value, threshold, message, severity: 'warning'|'critical', url }
  //   warning ≥3500ms, critical ≥7300ms (domInteractive)
{ type: 'perf_bundle_large', ext, sizeKb, resourceUrl, durationMs, isThirdParty, message, severity: 'warning'|'critical', url }
  //   JS: warning ≥500KB, critical ≥2MB | CSS: warning ≥150KB
{ type: 'perf_vitals_summary', lcp, cls, fcp, tti, ttfb, bundleCount, message, severity: 'info', url }
  //   always emitted even when all metrics are null

// ── A12 Deep Accessibility — axe-core + Color Blind Simulation ───────────
{ type: 'a11y_axe_violation',    axeId, impact, selector, html, description, helpUrl, message, severity: 'critical'|'warning'|'info', url }
  //   impact: 'critical'→'critical', 'serious'|'moderate'→'warning', 'minor'→'info'
  //   axeIds suppressed (already in snapshot-analyzer): label, button-name, heading-order, aria-required-children, landmark-unique
{ type: 'a11y_colorblind_risk',  selector, colorType, contrastRatio, fg, bg, message, severity: 'warning', url }
  //   colorType: 'protanopia'|'deuteranopia'; contrastRatio < 4.5 (WCAG AA) under CVD simulation
{ type: 'a11y_deep_summary',     axeViolations, criticalCount, seriousCount, moderateCount, minorCount, colorblindRisks, message, severity: 'info', url }

// ── GitHub PR enrichments (github-reporter.js) ───────────────────────────
// formatPrComment: now includes Selector column + Visual Regressions section + diff image embed
// buildStatusPayload: now includes newCriticalCount and threshold fields
// generateReleaseNotes(currentReport, prevReport, { fromTag, toTag }) → markdown changelog
// createCheckRun(name?, sha?) → Promise<checkRunId>   [requires GITHUB_TOKEN + GITHUB_REPOSITORY + GITHUB_SHA]
// completeCheckRun(id, report, diff) → Promise<void>
// New env vars: ARGUS_CRITICAL_THRESHOLD (default 1), ARGUS_DIFF_IMAGE_URL, GITHUB_CHECK_NAME

// ── N1 HAR Network Baseline ───────────────────────────────────────────────
{ type: 'har_baseline_created',   requestCount, baselineFile, message, severity: 'info', url }
  //   first run: baseline HAR saved to reports/baselines/har/{slug}.json
{ type: 'har_new_request',        method, requestUrl, status, message, severity: 'warning', url }
  //   current run has a request not present in the baseline
{ type: 'har_missing_request',    method, requestUrl, message, severity: 'warning', url }
  //   baseline request no longer made in current run
{ type: 'har_status_changed',     requestUrl, baselineStatus, currentStatus, message, severity: 'warning'|'critical', url }
  //   HTTP status code changed from baseline; critical when currentStatus ≥ 400
{ type: 'har_comparison_summary', newRequests, missingRequests, statusChanges, totalCurrent, totalBaseline, message, severity: 'info', url }
  //   always emitted when a baseline exists

// ── A9 Motion & Animation Accessibility ───────────────────────────────────
{ type: 'motion_no_reduced_motion_query', message, severity: 'warning', url }
  //   CSS animation/transition in use but no @media (prefers-reduced-motion) query in any stylesheet
{ type: 'motion_autoplay_no_pause', src, hasMuted?, message, severity: 'warning'|'info', url }
  //   <video autoplay> without controls (warning) or animated GIF/APNG without pause (info)
{ type: 'motion_interactive_animation', selector, animation, transition, message, severity: 'warning', url }
  //   interactive element (button/a/input/[role=button]) has animation/transition without reduced-motion override
{ type: 'motion_reduced_not_honoured', count, message, severity: 'warning', url }
  //   elements still animate after emulating prefers-reduced-motion: reduce
{ type: 'motion_summary', hasAnimation, hasReducedQuery, animationCount, autoplayCount, message, severity: 'info', url }
  //   always emitted

// ── A10 Font Loading ──────────────────────────────────────────────────────
{ type: 'font_foit_risk',          fontFamily, message, severity: 'warning', url }
  //   @font-face without font-display — Chrome defaults to 'auto' (invisible text while loading)
{ type: 'font_fout_risk',          fontFamily, fontDisplay, message, severity: 'info', url }
  //   font-display: swap or fallback — layout shift (CLS) risk when fallback metrics differ
{ type: 'font_no_fallback',        selector, fontFamily, message, severity: 'warning', url }
  //   font-family declaration with web font but no system font fallback (e.g. no , sans-serif)
{ type: 'font_slow_load',          fontUrl, duration, message, severity: 'warning', url }
  //   web font resource took > FONT_SLOW_MS (default 1000ms) to load via PerformanceResourceTiming
{ type: 'font_suboptimal_format',  fontFamily, message, severity: 'info', url }
  //   font served in .ttf or .eot format — use .woff2 for production
{ type: 'font_summary', foitRisks, foutRisks, noFallbacks, slowLoads, suboptimalFmts, message, severity: 'info', url }
  //   always emitted

// ── A11 Form Validation ───────────────────────────────────────────────────
{ type: 'form_missing_required',  inputName, inputType, message, severity: 'warning', url }
  //   <input> inside a <form> with no required or aria-required="true" attribute
{ type: 'form_no_autocomplete',   inputName, inputType, message, severity: 'warning', url }
  //   personal data field (name/email/address/phone/CC) missing autocomplete attribute (WCAG 1.3.5)
{ type: 'form_inaccessible_error', errorId, errorText, message, severity: 'warning', url }
  //   error element (role=alert / .error / .invalid-feedback) not linked via aria-describedby to its input
{ type: 'form_unmasked_password', inputName, message, severity: 'critical', url }
  //   input type="text" with label/name containing "password" — should use type="password"
{ type: 'form_no_validation',     formId, message, severity: 'info', url }
  //   form with required fields but no HTML5 pattern/type/novalidate — client-side validation may be absent
{ type: 'form_summary', missingRequired, missingAutocomplete, inaccessibleErrors, unmaskedPasswords, noValidation, totalIssues, message, severity: 'info', url }
  //   always emitted

// ── A8 Visual Regression ──────────────────────────────────────────────────
{ type: 'visual_baseline_created', baselinePath, message, severity: 'info', url }
  //   emitted on first run — no baseline existed; PNG saved for future comparison
{ type: 'visual_regression',  diffPercent, diffPixels, totalPixels, threshold, message, severity: 'warning'|'critical', url }
  //   warning ≥0.1%, critical ≥5% pixels changed
{ type: 'visual_diff_summary', diffPercent, diffPixels, totalPixels, message, severity: 'info', url }
  //   always emitted when a baseline exists

Standard Block Template

// ── [N] description — DX.Y
const result = await runAudit(url, mcp, options);

const violations = result.findings.filter(f => f.type === 'some_type');
assert(violations.length === 0, `[Na] no violations on clean page`);

const detected = result.findings.filter(f => f.type === 'some_type');
assert(detected.length >= 1, `[Nb] detects violation on broken fixture`);

5b. Finding Type Index

Flat alphabetical reference for writing assertions in validate.js. Every type string Argus can emit is listed here with its emitting module and severity range.

Always-emitted summary types (*_summary, *_vitals_summary, har_comparison_summary, har_baseline_created, visual_baseline_created, visual_diff_summary) are present on every run for their analyzer. Assert their severity === 'info' in block [Nc] pattern; assert detector-specific types in [Nb].

6. SEO & OG Tag Rules

Argus uses querySelector('meta[property="og:image"]') — the property attribute, not name.

All fixture pages with OG tags must use:

<meta property="og:image" content="http://localhost:3100/static/og-image.png">
<meta property="og:title" content="Page Title">
<meta property="og:description" content="Description">

Never use name="og:..." — it will not be detected.

7. Performance & LCP Debugging

Core Web Vitals (current — as of March 2024)

TBT is NOT a Core Web Vital — it is a lab proxy for INP, useful in Lighthouse but not a field metric. Do not report TBT as a CWV failure.

INP measures: input delay + processing time + presentation delay. Requires real interactions — cannot be captured from page load alone.

LCP Subpart Budget

LCP Debugging Workflow

// 1. Set conditions
await mcp.emulate({ device: 'iPhone 12', networkCondition: 'Slow 3G' });

// 2. Trace page load
await mcp.performance_start_trace({ reload: true, autoStop: true });

// 3. Analyze
await mcp.performance_analyze_insight({ insightName: 'LCPBreakdown' });
await mcp.lighthouse_audit({ url, mode: 'navigation' });

Manual trace (capture specific user actions):

await mcp.performance_start_trace();
// ... drive interactions ...
await mcp.performance_stop_trace({ outputFilePath: '/tmp/trace.json' });
await mcp.performance_analyze_insight();

Optimization Levers by Subpart

• High TTFB: CDN, server-side caching, <link rel=preconnect>
• High resource load delay: <link rel=preload as=image> for above-fold images
• High resource load duration: compress images (WebP/AVIF), reduce transfer size
• High element render delay: eliminate render-blocking CSS/JS above LCP element

HAR Network Waterfall Analysis

list_network_requests returns HAR v1.2-compatible JSON with per-request timing:

const parsed = unwrapEval(await mcp.list_network_requests({ pageSize: 100, pageIdx: 0 }));
// Each entry: { dns, connect, ssl, send, wait, receive } — all in ms
// wait = TTFB per resource

const slowest = parsed
  .filter(r => r.timing?.wait > 500)
  .sort((a,b) => b.timing.wait - a.timing.wait)
  .slice(0, 10)
  .map(r => ({ url: r.url, waitMs: r.timing.wait, type: r.resourceType }));

Cross-origin TTFB gap: window.performance.getEntriesByType('resource') returns 0ms for cross-origin resources that omit Timing-Allow-Origin. Use list_network_requests HAR timing for accurate third-party TTFB. network-timing-analyzer.js (parseNetworkTiming) automates this — see §14d.

CPU Throttling Tiers

8. Accessibility — Deep Audit Workflows

A11y Tree vs DOM

take_snapshot reflects what assistive technologies see — use it as the source of truth for semantic checks, not the DOM.

Role Tag Reference

Uid format (current): N_M numeric pairs — e.g., 3_4, 5_2, 12_1. The old alphanumeric format (e4, r12) was used before v8 and may still appear in cached snapshots. Always extract uid from the current snapshot; never reuse across page transitions.

ARIA Snapshot YAML Notation

Some environments emit the accessibility tree as YAML:

- banner:
  - link "Home" [ref=e1]
      /url: https://example.com
- main:
  - heading "Welcome" [level=1]
  - textbox [ref=e5]
      /placeholder: "Search"
      /value: ""
  - checkbox [ref=e6] [checked]
  - button "Submit" [ref=e7] [disabled]

Workflow 1 — Lighthouse A11y Audit (Baseline)

await mcp.lighthouse_audit({ url, mode: 'navigation', outputDirPath: '/tmp/lh-a11y' });
// Score 0-1; < 1 means violations exist

Extract only failing audits from the saved JSON report:

node -e "
  const r = require('/tmp/lh-a11y/report.json');
  Object.values(r.audits)
    .filter(a => a.score !== null && a.score < 1)
    .forEach(a => console.log(JSON.stringify({ id: a.id, title: a.title, items: a.details?.items?.slice(0,5) })));
"

Workflow 2 — Browser Native A11y Issues

const issues = await mcp.list_console_messages({
  types: ['issue'],
  includePreservedMessages: true,
});
// Look for: missing labels, invalid ARIA, low contrast

Run this before manual checks — Chrome often reports violations automatically.

Workflow 3 — Heading Hierarchy & Semantic Structure

const snap = unwrapFence(await mcp.take_snapshot());
// Scan for [heading] level=N entries
// Verify: h1 → h2 → h3 — no level skips

DOM order drives the accessibility tree. CSS reordering (floats, flex order) can jumble logical reading order without affecting appearance.

Workflow 4 — Labels, Forms & Alt Text

1. take_snapshot → locate all [TextField], [Button], [Upload] nodes
2. Verify each has a non-empty accessible name
3. Icon-only buttons must have aria-label
4. Images need alt; decorative images need alt=""

Workflow 5 — Keyboard Trap Testing

await mcp.press_key({ key: 'Tab' });
const snap = unwrapFence(await mcp.take_snapshot());
// Verify focused element is expected; modal focus must trap within modal
// Tab should cycle within modal; Escape should close and return focus

Workflow 6 — Tap Target Size

WCAG: interactive elements ≥ 44×44 CSS px. WCAG 2.2 SC 2.5.8 minimum: 24×24 CSS px.

const undersized = unwrapEval(await mcp.evaluate_script({
  function: `() => Array.from(document.querySelectorAll('button,a,input,[role="button"],[role="link"]'))
    .map(el => { const r = el.getBoundingClientRect();
      return { tag: el.tagName, text: el.textContent?.trim().slice(0,30),
               w: Math.round(r.width), h: Math.round(r.height),
               failsWcag22: r.width < 24 || r.height < 24,
               failsBestPractice: r.width < 44 || r.height < 44 };
    }).filter(e => e.failsWcag22)`,
}));

Workflow 7 — Color Contrast

1. list_console_messages({ types: ['issue'] }) → look for "Low Contrast" (Chrome native)
2. evaluate_script with contrast-ratio calculation if native audit misses it
3. take_screenshot + visual inspection for text over gradient/image backgrounds

Workflow 8 — Keyboard-Only Navigation Protocol

// Step 1: Reset focus
await mcp.evaluate_script({ function: `() => document.body.focus()` });

// Step 2: Tab through every focusable element
const focusOrder = [];
for (let i = 0; i < 30; i++) {
  await mcp.press_key({ key: 'Tab' });
  const snap = unwrapFence(await mcp.take_snapshot());
  focusOrder.push(snap.match(/focused[^\n]*/)?.[0] ?? `step-${i}-unknown`);
}
// Verify: no element appears twice, all interactive elements in visual layout are reached

Watch for: focus skipping hidden elements, CSS order/flex reordering breaking logical tab order, missing tabindex on custom widgets.

Workflow 9 — Screen Reader Testing Matrix

Automated tools catch ~30% of a11y bugs. Use this matrix for manual SR decisions:

A11y Findings (Argus)

// A12 axe-core injection (a11y-deep-analyzer) — severity mapped from axe impact:
// critical→critical, serious/moderate→warning, minor→info
{ type: 'a11y_axe_violation', axeId: 'color-contrast', impact: 'serious',  selector, html, description, helpUrl, message, severity: 'warning',  url }
{ type: 'a11y_axe_violation', axeId: 'button-name',    impact: 'critical', selector, html, description, helpUrl, message, severity: 'critical', url }
{ type: 'a11y_axe_violation', axeId: 'image-alt',      impact: 'critical', selector, html, description, helpUrl, message, severity: 'critical', url }

// Native Argus detectors (production code — see §14d for implementation details)
{ type: 'heading_level_skip',        from, to, text, message, severity: 'warning', url }
{ type: 'focus_visible_missing',     tag, id, snippet, message, severity: 'warning', url }
{ type: 'aria_expanded_no_controls', tag, id, snippet, message, severity: 'warning', url }
{ type: 'low_contrast_native',       message,            severity: 'warning', url }

9. Analyzer Development Guide

Part A — Adding a New Detection Phase (New Analyzer)

Open this checklist when adding a new analyzer. Check off in order.

Step 1 — Analyzer file → src/utils/<name>-analyzer.js

• Export the main analyze<Name>(browser, url, opts) function
• Return findings[] array — never throw, always return
• Call registerExpensive({ name, analyze }) at the bottom (side-effect registration)
• Import thresholds from src/config/targets.js for all numeric limits

Step 2 — Thresholds → src/config/targets.js

• Add a <name>: { warnX, critX, ... } block to the thresholds export
• Add env-var overrides: parseFloat(process.env.VAR ?? 'default')

Step 3 — Orchestrator side-effect import → src/orchestration/orchestrator.js line ~44-47

import '../utils/<name>-analyzer.js';

Step 4 — Fixture page → test-harness/pages/<name>-issues.html

• Must be served via HTTP (never file://)
• Use property="og:..." for all OG meta tags
• Include intentional defects that exercise every new finding type
• Use window.__argusTest.<method> to expose JS handles for harness manipulation

Step 5 — Harness route → test-harness/harness-config.js

{
  path: '/<name>-issues.html',
  name: '<Label>',
  critical: false,
  waitFor: null,
  expected: '<describe what should be detected>',
},

Step 6 — Harness block → test-harness/validate.js

• Import the new analyzer at the top alongside existing imports
• Add // ── Block [N] ── comment block
• Minimum 3 hard assertions: [Na] array returned, [Nb] primary finding detected, [Nc] severity correct
• Additional assertions for each new finding type

Step 7 — §5 Finding Shapes → SKILL.md — add all new { type, ... } shapes

Step 8 — §14 Harness Statistics → SKILL.md — update all stats rows

Part B — Version Bump Procedure

Bump version in exactly 5 places with every release (use find+replace, never miss one):

Part C — MD Update Checklist (after every release)

Run after harness passes. Update all 6 files before committing:

Gitignored files (update locally but do NOT commit):

• session.md — next steps + latest summary
• solution.md — phases complete summary

Part D — Naming Conventions

• Analyzer files: src/utils/<category>-analyzer.js
• Fixture pages: test-harness/pages/<category>-issues.html or <feature-name>.html
• Finding types: snake_case, prefixed by category (perf_, design_, visual_, theme_)
• Flow names: <category>-d<major>-<minor> (e.g. upload-d8-5)
• Commit messages: no feature labels in subject line; include (vX.Y.Z) in subject

Part E — Selector Strategy

Prefer stable selectors in this order:

1. `data-testid` attribute — survives CSS refactors: [data-testid="submit-btn"]
2. ARIA role + name — resolves via snapshot uid: [Button] "Submit"
3. Unique ID — #submit-button (if stable across renders)
4. Avoid dynamic class names (.css-1abc2def), deep DOM path selectors, index-based selectors

Multi-selector fallback:

const btn = document.querySelector('[data-testid="submit"], button[type="submit"], .submit-btn');

Part F — Incremental Testing Principles

• Clean state: Navigate fresh at the start of each test block — don't reuse leftover DOM state
• Incremental: Verify after each significant interaction; don't chain 5 steps before checking
• Shared component rule: When fixing a shared component, validate on more than one consuming page

10. Common Failure Modes & Fixes

evaluate_script returns undefined

Response is in a markdown fence. Always call unwrapEval(raw) before using the result.

Interaction tool throws "element not found"

The uid from a previous snapshot is stale. Re-call take_snapshot after any page transition or DOM update.

upload_file throws "no file-input uid found"

The <input type="file"> is hidden or absent from the accessibility tree. Ensure it is visible (not display:none or visibility:hidden).

Soft assertion passes when it should fail

Check the fixture page is serving the broken content. Confirm harness-config.js path. Verify the finding type string matches exactly.

meta[property="og:image"] not detected

Fixture uses name="og:image" instead of property="og:image". Fix: change attribute to property=.

list_network_requests returns empty

Called before wait_for { state: 'networkidle' }. Always await networkidle first.

Popup / new tab breaks interactions

After any action that opens a new tab, call list_pages then select_page on the new page.

Screenshot shows missing images

Images may be animation-triggered. Three patterns:

Intersection Observer (scroll-triggered):

await mcp.evaluate_script({ function: `() => document.querySelector('.lazy-image')?.scrollIntoView()` });
await mcp.wait_for({ ms: 1000 });
await mcp.take_screenshot({ filePath: '/tmp/after-scroll.png' });

Full-page trigger — scroll to bottom then back:

await mcp.evaluate_script({ function: `() => window.scrollTo(0, document.body.scrollHeight)` });
await mcp.wait_for({ ms: 1500 });
await mcp.evaluate_script({ function: `() => window.scrollTo(0, 0)` });
await mcp.take_screenshot({ filePath: '/tmp/fully-loaded.png', fullPage: true });

Fixture page served via file:// protocol

Never navigate fixture pages via file:// — it blocks CORS, ES modules, fetch API. Always serve via