High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat(a11y): audit iframes via per-frame axe injection, make axe refs actionable, and add e2e scenarios (PIN-397)
Luigi Agostidd1e52a1a69c
diff --git a/internal/audit/testdata/axe-violations.json b/internal/audit/testdata/axe-violations.jsonindex 347cd4c8..08695869 100644--- a/internal/audit/testdata/axe-violations.json+++ b/internal/audit/testdata/axe-violations.json@@ -1,5 +1,5 @@{- "tabId": "8A006E97AB7902D27586073510FD8AD4",+ "tabId": "32B0564F5CAD10D61054DDFD282E49D3","engine": "axe","version": "4.13.0","url": "http://fixtures/a11y-violations.html",@@ -60,6 +60,14 @@"html": "<img id=\"no-alt\" src=\"data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==\">","ref": "e3","failureSummary": "Fix any of the following:\n Element does not have an alt attribute\n aria-label attribute does not exist or is empty\n aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty\n Element has no title attribute\n Element's default semantics were not overridden with role=\"none\" or role=\"presentation\""+ },+ {+ "target": [+ "iframe",+ "img"+ ],+ "html": "<img src=\"data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==\">",+ "failureSummary": "Fix any of the following:\n Element does not have an alt attribute\n aria-label attribute does not exist or is empty\n aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty\n Element has no title attribute\n Element's default semantics were not overridden with role=\"none\" or role=\"presentation\""}]},@@ -95,6 +103,35 @@}],"incompleteViolations": [+ {+ "id": "bypass",+ "impact": "serious",+ "tags": [+ "cat.keyboard",+ "wcag2a",+ "wcag241",+ "section508",+ "section508.22.o",+ "TTv5",+ "TT9.a",+ "EN-301-549",+ "EN-9.2.4.1",+ "RGAAv4",+ "RGAA-12.7.1"+ ],+ "help": "Page must have means to bypass repeated blocks",+ "helpUrl": "https://dequeuniversity.com/rules/axe/4.13/bypass?application=axeAPI",+ "nodes": [+ {+ "target": [+ "iframe",+ "html"+ ],+ "html": "<html lang=\"en\"><head></head><body><img src=\"data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==\"></body></html>",+ "failureSummary": "Fix any of the following:\n No valid skip link found\n Page does not have a heading\n Page does not have a landmark region"+ }+ ]+ },{"id": "duplicate-id-aria","impact": "critical",@@ -121,7 +158,7 @@}],"passes": 15,- "incomplete": 1,- "inapplicable": 45,- "score": 70+ "incomplete": 2,+ "inapplicable": 44,+ "score": 60}diff --git a/internal/handlers/a11y_axe.go b/internal/handlers/a11y_axe.goindex 92a2c680..8c53f983 100644--- a/internal/handlers/a11y_axe.go+++ b/internal/handlers/a11y_axe.go@@ -9,6 +9,7 @@ import ("github.com/pinchtab/pinchtab/internal/assets""github.com/pinchtab/pinchtab/internal/audit""github.com/pinchtab/pinchtab/internal/bridge"+ "github.com/pinchtab/pinchtab/internal/bridge/observe""github.com/pinchtab/pinchtab/internal/httpx")@@ -29,15 +30,19 @@ func (h *Handlers) runAxeAudit(w http.ResponseWriter, r *http.Request, tCtx contreturn}- expression := assets.AxeJS + "\n;" + axeRunSnippet(config, selector)+ // Inject axe into every frame's isolated world first, so axe.run in the top+ // frame can coordinate its same-origin iframe audit with an axe instance+ // already listening in each child frame.+ injectAxeIntoAllFrames(tCtx)+var raw audit.AxeRawResult- if err := bridge.EvaluateInIsolatedWorld(tCtx, "", expression, &raw); err != nil {+ if err := bridge.EvaluateInIsolatedWorld(tCtx, "", axeRunSnippet(config, selector), &raw); err != nil {httpx.Error(w, http.StatusInternalServerError, fmt.Errorf("run axe: %w", err))return}report := audit.BuildAxeReport(raw, assets.AxeVersion, includeIncomplete)- h.fillAxeRefs(tCtx, &report)+ h.fillAxeRefs(tCtx, resolvedTabID, &report)httpx.JSON(w, 200, struct {TabID string `json:"tabId"`@@ -45,6 +50,24 @@ func (h *Handlers) runAxeAudit(w http.ResponseWriter, r *http.Request, tCtx cont}{resolvedTabID, report})}+// injectAxeIntoAllFrames loads the axe source into every reachable frame's+// isolated world (the top frame included), so a subsequent axe.run can audit+// same-origin iframes through the axe instance waiting in each. A cross-origin+// frame whose isolated world cannot be created is skipped, exactly as snapshot+// and text extraction skip it.+func injectAxeIntoAllFrames(tCtx context.Context) {+ var ids []string+ if tree, err := observe.FetchFrameTree(tCtx); err == nil {+ ids = observe.FrameIDs(tree)+ }+ if len(ids) == 0 {+ ids = []string{""} // top frame only+ }+ for _, id := range ids {+ _ = bridge.EvaluateInIsolatedWorld(tCtx, id, assets.AxeJS, nil)+ }+}+// axeRunSnippet builds the in-page call: run axe over the document (or a// selector scope), await it, and return the fields the report needs, reducing// the large passes/inapplicable node lists to counts before they cross the wire.@@ -71,8 +94,8 @@ func axeRunSnippet(config, selector string) string {// an agent can actuate a failing element directly. A node whose target does not// resolve to a snapshot ref (a cross-origin iframe, a node not in the tree) is// left without one rather than guessed.-func (h *Handlers) fillAxeRefs(tCtx context.Context, report *audit.AxeReport) {- backendToRef := h.snapshotBackendRefs(tCtx)+func (h *Handlers) fillAxeRefs(tCtx context.Context, tabID string, report *audit.AxeReport) {+ backendToRef := h.snapshotBackendRefs(tCtx, tabID)if len(backendToRef) == 0 {return}@@ -80,11 +103,14 @@ func (h *Handlers) fillAxeRefs(tCtx context.Context, report *audit.AxeReport) {for i := range violations {for j := range violations[i].Nodes {node := &violations[i].Nodes[j]- if len(node.Target) == 0 {+ // Only a single-hop target names a top-frame element the top+ // document's querySelector can resolve. A multi-hop target is+ // inside an iframe; resolving its last selector against the top+ // document would map it to the wrong element, so leave it unref'd.+ if len(node.Target) != 1 {continue}- selector := node.Target[len(node.Target)-1]- backendID, err := bridge.BackendNodeIDForSelector(tCtx, "", selector)+ backendID, err := bridge.BackendNodeIDForSelector(tCtx, "", node.Target[0])if err != nil || backendID == 0 {continue}@@ -98,16 +124,24 @@ func (h *Handlers) fillAxeRefs(tCtx context.Context, report *audit.AxeReport) {fill(report.IncompleteViolations)}-// snapshotBackendRefs maps backend node id → snapshot ref from a fresh snapshot,-// the same tree /snapshot mints, so an axe node's ref is one /action can use.-func (h *Handlers) snapshotBackendRefs(tCtx context.Context) map[int64]string {+// snapshotBackendRefs builds a full-tree snapshot, stores it as the tab's ref+// cache (as /snapshot and /find do), and returns backend node id → ref from that+// cache. Storing the cache is what makes an axe node's ref actionable: /action+// resolves a ref against the tab's cache, so the ref would 404 if the audit+// computed it without publishing the snapshot it came from. A full tree (not the+// interactive filter) is used so non-interactive violation targets — images,+// low-contrast text — still map to a ref.+func (h *Handlers) snapshotBackendRefs(tCtx context.Context, tabID string) map[int64]string {rawNodes, err := bridge.FetchAXTree(tCtx)if err != nil {return nil}- nodes, _ := bridge.BuildSnapshot(rawNodes, "", -1)- refs := make(map[int64]string, len(nodes))- for _, n := range nodes {+ flat, _ := bridge.BuildSnapshot(rawNodes, "", -1)+ cache := bridge.EpochRefs(h.Bridge.GetRefCache(tabID), flat)+ h.Bridge.SetRefCache(tabID, cache)++ refs := make(map[int64]string, len(cache.Nodes))+ for _, n := range cache.Nodes {if n.NodeID != 0 && n.Ref != "" {refs[n.NodeID] = n.Ref}diff --git a/tests/e2e/fixtures/a11y-violations.html b/tests/e2e/fixtures/a11y-violations.htmlindex aabd2cec..1b002d7d 100644--- a/tests/e2e/fixtures/a11y-violations.html+++ b/tests/e2e/fixtures/a11y-violations.html@@ -28,5 +28,17 @@<!-- an iframe with its own missing-alt image, audited by axe's frame support --><iframe title="child frame" srcdoc='<!doctype html><html lang="en"><body><img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="></body></html>'></iframe>++ <!-- Hostile tampering in the MAIN world: a fake axe that reports nothing, and a+ poisoned getAttribute that hides missing alts. The audit runs in the+ isolated world, so none of this reaches it and the violations still show. -->+ <script>+ window.axe = { run: function () { return Promise.resolve({ violations: [], passes: [], incomplete: [], inapplicable: [] }); } };+ var realGetAttribute = Node.prototype.getAttribute;+ Node.prototype.getAttribute = function (name) {+ if (name === 'alt') { return 'not actually here'; }+ return realGetAttribute.call(this, name);+ };+ </script></body></html>diff --git a/tests/e2e/scenarios/api/a11y-axe-basic.sh b/tests/e2e/scenarios/api/a11y-axe-basic.shnew file mode 100755index 00000000..32012b99--- /dev/null+++ b/tests/e2e/scenarios/api/a11y-axe-basic.sh@@ -0,0 +1,120 @@+#!/bin/bash+# a11y-axe-basic.sh — GET /a11y/audit?engine=axe: violations with impact/tags/+# helpUrl and ref-mapped nodes, iframe auditing, isolated-world tamper-proofing,+# tag filtering, actuation of a ref, and the engine=bogus refusal.++GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+source "${GROUP_DIR}/../../helpers/api.sh"++# ─────────────────────────────────────────────────────────────────+start_test "a11y axe: violations carry id, impact, tags, helpUrl and refs"++pt_post /navigate -d "{\"url\":\"${FIXTURES_URL}/a11y-violations.html\"}"+assert_ok "navigate to a11y-violations.html"++pt_get "/a11y/audit?engine=axe"+assert_ok "axe audit"+assert_json_eq "$RESULT" '.engine' 'axe' "engine echoes axe"+assert_json_eq "$RESULT" '.version' '4.13.0' "axe version echoed"++IDS=$(echo "$RESULT" | jq -r '[.violations[].id] | sort | join(",")')+for want in image-alt label color-contrast; do+ if echo "$IDS" | grep -q "$want"; then+ echo -e " ${GREEN}✓${NC} violation $want present"+ ((ASSERTIONS_PASSED++)) || true+ else+ echo -e " ${RED}✗${NC} violation $want missing (got: $IDS)"+ ((ASSERTIONS_FAILED++)) || true+ fi+done++assert_json_exists "$RESULT" '.violations[] | select(.id=="image-alt") | select(.impact!=null)' "image-alt has impact"+assert_json_exists "$RESULT" '.violations[] | select(.id=="image-alt") | select(.helpUrl!="")' "image-alt has helpUrl"+assert_json_exists "$RESULT" '.violations[].nodes[] | select(.target!=null and .html!="")' "nodes carry target and html"++end_test++# ─────────────────────────────────────────────────────────────────+# The fixture tampers in the main world (fake window.axe, poisoned getAttribute).+# The audit still finds the violations, which proves it ran in the isolated world.+start_test "a11y axe: isolated world defeats page tampering"++VIOLATION_COUNT=$(echo "$RESULT" | jq '.violations | length')+if [ "$VIOLATION_COUNT" -ge 3 ]; then+ echo -e " ${GREEN}✓${NC} $VIOLATION_COUNT violations despite a fake window.axe returning none"+ ((ASSERTIONS_PASSED++)) || true+else+ echo -e " ${RED}✗${NC} only $VIOLATION_COUNT violations; page tampering leaked into the run"+ ((ASSERTIONS_FAILED++)) || true+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "a11y axe: a ref-mapped node is actionable via /action"++REF=$(echo "$RESULT" | jq -r 'first(.violations[] | select(.id=="label") | .nodes[] | select(.ref!=null and .ref!="") | .ref)')+if [ -n "$REF" ] && [ "$REF" != "null" ]; then+ echo -e " ${GREEN}✓${NC} label violation carries ref $REF"+ ((ASSERTIONS_PASSED++)) || true+else+ echo -e " ${RED}✗${NC} label violation carries no ref"+ ((ASSERTIONS_FAILED++)) || true+fi++pt_post /action -d "{\"kind\":\"focus\",\"ref\":\"${REF}\"}"+assert_ok "focus the failing element by its axe ref"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "a11y axe: iframe content is audited"++pt_get "/a11y/audit?engine=axe"+assert_ok "axe audit (iframe check)"+IFRAME_NODE=$(echo "$RESULT" | jq '[.violations[].nodes[] | select((.target | length) > 1)] | length')+if [ "$IFRAME_NODE" -ge 1 ]; then+ echo -e " ${GREEN}✓${NC} an iframe-nested violation node is reported"+ ((ASSERTIONS_PASSED++)) || true+else+ echo -e " ${RED}✗${NC} no iframe-nested violation reported"+ ((ASSERTIONS_FAILED++)) || true+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "a11y axe: tags=wcag2a drops the wcag2aa-only color-contrast rule"++pt_get "/a11y/audit?engine=axe&tags=wcag2a"+assert_ok "axe audit tags=wcag2a"+assert_json_exists "$RESULT" '.violations[] | select(.id=="image-alt")' "wcag2a keeps image-alt"+CC=$(echo "$RESULT" | jq '[.violations[] | select(.id=="color-contrast")] | length')+if [ "$CC" -eq 0 ]; then+ echo -e " ${GREEN}✓${NC} color-contrast (wcag2aa) absent under tags=wcag2a"+ ((ASSERTIONS_PASSED++)) || true+else+ echo -e " ${RED}✗${NC} color-contrast present under tags=wcag2a"+ ((ASSERTIONS_FAILED++)) || true+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "a11y axe: unknown engine is a 400"++pt_get "/a11y/audit?engine=bogus"+assert_http_status 400 "engine=bogus refused"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "a11y native: engine omitted keeps the native report"++pt_get "/a11y/audit"+assert_ok "native audit"+assert_json_exists "$RESULT" '.findings' "native report has findings"+assert_json_exists "$RESULT" 'select(.score!=null)' "native report has score"+assert_json_eq "$RESULT" '.engine' 'null' "native report has no engine field"++end_testdiff --git a/tests/e2e/scenarios/cli/a11y-axe-basic.sh b/tests/e2e/scenarios/cli/a11y-axe-basic.shnew file mode 100755index 00000000..76fd1867--- /dev/null+++ b/tests/e2e/scenarios/cli/a11y-axe-basic.sh@@ -0,0 +1,41 @@+#!/bin/bash+# a11y-axe-basic.sh — CLI: pinchtab a11y audit --axe yields the same violation+# ids as the API, and --tags filters the run.++GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+source "${GROUP_DIR}/../../helpers/cli.sh"++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab a11y audit --axe --json"++pt_ok nav "${FIXTURES_URL}/a11y-violations.html"++pt_ok a11y audit --axe --json+assert_output_contains '"engine": "axe"' "engine echoes axe"+assert_output_contains '"version": "4.13.0"' "axe version echoed"+for want in image-alt label color-contrast; do+ assert_output_contains "\"$want\"" "violation $want present"+done++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab a11y audit --axe --tags wcag2a filters"++pt_ok a11y audit --axe --tags wcag2a --json+assert_output_contains '"image-alt"' "wcag2a keeps image-alt"+if grep -q '"color-contrast"' <<<"$PT_OUT"; then+ fail_assert "color-contrast (wcag2aa) should be dropped under --tags wcag2a"+else+ pass_assert "color-contrast absent under --tags wcag2a"+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab a11y audit (native) summary"++pt_ok a11y audit+assert_output_contains "engine=native" "native engine summary line"++end_testdiff --git a/tests/e2e/scenarios/manifest.json b/tests/e2e/scenarios/manifest.jsonindex a83308c5..ed984c33 100644--- a/tests/e2e/scenarios/manifest.json+++ b/tests/e2e/scenarios/manifest.json@@ -57,6 +57,20 @@"pr"]},+ "api/a11y-axe-basic.sh": {+ "tags": [+ "a11y",+ "axe",+ "pr"+ ]+ },+ "cli/a11y-axe-basic.sh": {+ "tags": [+ "a11y",+ "axe",+ "pr"+ ]+ },"api/browser-extended.sh": {"tags": ["browser",