Skip to content

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.json
index 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.go
index 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 cont
return
}
- 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.html
index 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.sh
new file mode 100755
index 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_test
diff --git a/tests/e2e/scenarios/cli/a11y-axe-basic.sh b/tests/e2e/scenarios/cli/a11y-axe-basic.sh
new file mode 100755
index 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_test
diff --git a/tests/e2e/scenarios/manifest.json b/tests/e2e/scenarios/manifest.json
index 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",