Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

3.9 KB
Raw Blame

Accessibility Audit

/a11y/audit scores a page for accessibility issues. It has two engines:

  • native (default) — PinchTab's home-grown rule set over the accessibility snapshot. Fast, no page script.
  • axe — vendored axe-core run in the page, returning the industry rule ids, WCAG tags and help URLs humans already know, plus a snapshot ref for each failing element so an agent can act on it directly.

Endpoints

  • GET /a11y/audit
  • GET /tabs/{id}/a11y/audit

Query Parameters

Parameter Engine Default Description
engine both native native or axe; any other value is a 400
tabId both active tab Tab ID when using GET /a11y/audit
tags axe WCAG tags without best-practice Comma list of WCAG tags to run, e.g. wcag2a,wcag2aa,best-practice
rules axe all in-tag rules Comma allowlist of rule ids; wins over tags
includeIncomplete axe false Include rules axe could not decide (the incomplete set)
selector axe whole document Scope the run to a CSS selector

A best-practice rule appears only when tags includes best-practice; the default tag set is WCAG conformance tags only.

axe Response

{
  "tabId": "...",
  "vocabularyToken": "...",
  "engine": "axe",
  "version": "4.13.0",
  "url": "https://example.com/",
  "violations": [
    {
      "id": "image-alt",
      "impact": "critical",
      "tags": ["wcag2a", "wcag111"],
      "help": "Images must have alternate text",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.13/image-alt",
      "nodes": [
        {
          "target": ["#no-alt"],
          "html": "<img id=\"no-alt\">",
          "ref": "e5",
          "failureSummary": "Fix any of the following: ..."
        }
      ]
    }
  ],
  "passes": 9,
  "incomplete": 0,
  "inapplicable": 51,
  "score": 90
}
  • version echoes the vendored axe-core version (see THIRD_PARTY_LICENSES.md).
  • ref is filled when the failing element maps to a snapshot ref, so an agent can fall straight to /action on it. Only single-hop targets (top-frame elements) get a ref; a node inside an iframe is left without one.
  • The axe run publishes the tab's ref cache, so it returns a fresh vocabularyToken (also sent as the X-PinchTab-Vocab header); echo it as vocab on the follow-up action or a ref from an older read is refused 409.
  • incompleteViolations (details) is included only when includeIncomplete=true; the incomplete count is always present.
  • score reuses the native 0–100 scale (100 minus severity-weighted violation counts — serious/critical 10, moderate 5, minor 2 per node — floored at 0) so axe and native scores stay comparable on a dashboard.

The script runs in PinchTab's isolated world, so a page that overrides window.axe or a DOM prototype cannot alter the result.

Examples

# axe engine, JSON
curl "http://localhost:9867/a11y/audit?engine=axe" -H "Authorization: Bearer $TOKEN"

# WCAG 2.0 A only (drops the AA-only color-contrast rule)
curl "http://localhost:9867/a11y/audit?engine=axe&tags=wcag2a" -H "Authorization: Bearer $TOKEN"

# CLI
pinchtab a11y audit --axe
pinchtab a11y audit --axe --tags wcag2a,wcag2aa --json

CLI flags: --axe (same as --engine axe), --engine, --tags, --rules, --include-incomplete, --selector, --tab, --json.

MCP: pinchtab_a11y_audit takes tabId, engine, tags, rules, includeIncomplete and browser (no selector).

Covered by tests/e2e/scenarios/api/a11y-axe-basic.sh, tests/e2e/scenarios/api/a11y-audit-basic.sh and tests/e2e/scenarios/cli/a11y-axe-basic.sh.

Native Response

With engine omitted the response is the native report unchanged:

{ "tabId": "...", "score": 88, "findings": [ { "rule": "missing-alt", "severity": "serious", "count": 1, "samples": ["image e5"] } ] }