Skip to content

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

feat: add GET /a11y/audit with rule-based accessibility score

Luigi Agostiff177089d776
diff --git a/internal/audit/a11y.go b/internal/audit/a11y.go
new file mode 100644
index 00000000..4d720dae
--- /dev/null
+++ b/internal/audit/a11y.go
@@ -0,0 +1,150 @@
+package audit
+
+import (
+ "fmt"
+ "sort"
+ "strings"
+
+ "github.com/pinchtab/pinchtab/internal/bridge/observe"
+)
+
+// Severity levels for accessibility findings.
+const (
+ SeveritySerious = "serious"
+ SeverityModerate = "moderate"
+ SeverityMinor = "minor"
+)
+
+// a11yWeights are the per-violation score deductions by severity. The score
+// formula is: 100 - Σ weight(severity) × count, floored at 0.
+var a11yWeights = map[string]int{
+ SeveritySerious: 10,
+ SeverityModerate: 5,
+ SeverityMinor: 2,
+}
+
+// maxA11ySamples caps how many sample descriptions a finding carries.
+const maxA11ySamples = 5
+
+// A11yFinding is one accessibility rule violation aggregated across a page.
+type A11yFinding struct {
+ // Rule is the stable rule identifier (e.g. "missing-alt").
+ Rule string `json:"rule"`
+ // Severity is serious, moderate, or minor.
+ Severity string `json:"severity"`
+ // Count is how many times the rule was violated.
+ Count int `json:"count"`
+ // Samples describe up to maxA11ySamples offending elements.
+ Samples []string `json:"samples"`
+}
+
+// A11yReport is the page-level accessibility audit result.
+type A11yReport struct {
+ // Score is 100 minus severity-weighted violation counts, floored at 0.
+ Score int `json:"score"`
+ // Findings are the rule violations, sorted by rule for determinism.
+ Findings []A11yFinding `json:"findings"`
+}
+
+// PageFacts holds page-level facts the AX tree cannot provide, gathered by
+// PageFactsScript.
+type PageFacts struct {
+ // Title is document.title.
+ Title string `json:"title"`
+ // Lang is the html element's lang attribute.
+ Lang string `json:"lang"`
+ // HeadingLevels are the h1–h6 levels in document order.
+ HeadingLevels []int `json:"headingLevels"`
+}
+
+// PageFactsScript evaluates to the PageFacts JSON shape in the page.
+const PageFactsScript = `(() => ({
+ title: document.title || '',
+ lang: document.documentElement.getAttribute('lang') || '',
+ headingLevels: Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6')).map((h) => Number(h.tagName[1])),
+}))()`
+
+// labelableRoles are AX roles that require an accessible name from a label.
+var labelableRoles = map[string]bool{
+ "textbox": true,
+ "searchbox": true,
+ "combobox": true,
+ "listbox": true,
+ "checkbox": true,
+ "radio": true,
+ "spinbutton": true,
+ "slider": true,
+ "switch": true,
+}
+
+// EvaluateA11y derives rule-based findings and a 0–100 score from the
+// accessibility snapshot plus page facts. Deterministic for the same inputs:
+// findings are keyed and sorted by rule, samples follow node order.
+func EvaluateA11y(nodes []observe.A11yNode, facts PageFacts) A11yReport {
+ collector := map[string]*A11yFinding{}
+ record := func(rule, severity, sample string) {
+ f, ok := collector[rule]
+ if !ok {
+ f = &A11yFinding{Rule: rule, Severity: severity, Samples: []string{}}
+ collector[rule] = f
+ }
+ f.Count++
+ if len(f.Samples) < maxA11ySamples {
+ f.Samples = append(f.Samples, sample)
+ }
+ }
+
+ for _, node := range nodes {
+ if node.Hidden {
+ continue
+ }
+ name := strings.TrimSpace(node.Name)
+ switch {
+ case (node.Role == "image" || node.Role == "img") && name == "" && strings.TrimSpace(node.Alt) == "":
+ record("missing-alt", SeveritySerious, nodeSample(node))
+ case labelableRoles[node.Role] && name == "" && strings.TrimSpace(node.Label) == "":
+ record("missing-label", SeveritySerious, nodeSample(node))
+ case node.Role == "link" && name == "" && strings.TrimSpace(node.Text) == "":
+ record("empty-link", SeverityModerate, nodeSample(node))
+ case node.Role == "button" && name == "" && strings.TrimSpace(node.Text) == "":
+ record("empty-button", SeverityModerate, nodeSample(node))
+ }
+ }
+
+ if strings.TrimSpace(facts.Title) == "" {
+ record("missing-title", SeverityModerate, "document.title is empty")
+ }
+ if strings.TrimSpace(facts.Lang) == "" {
+ record("missing-lang", SeverityModerate, "html element has no lang attribute")
+ }
+ prev := 0
+ for _, level := range facts.HeadingLevels {
+ if prev > 0 && level > prev+1 {
+ record("heading-skip", SeverityMinor, fmt.Sprintf("h%d follows h%d", level, prev))
+ }
+ prev = level
+ }
+
+ report := A11yReport{Score: 100, Findings: []A11yFinding{}}
+ for _, f := range collector {
+ report.Findings = append(report.Findings, *f)
+ report.Score -= a11yWeights[f.Severity] * f.Count
+ }
+ if report.Score < 0 {
+ report.Score = 0
+ }
+ sort.Slice(report.Findings, func(i, j int) bool {
+ return report.Findings[i].Rule < report.Findings[j].Rule
+ })
+ return report
+}
+
+func nodeSample(node observe.A11yNode) string {
+ if node.Ref != "" {
+ return node.Role + " " + node.Ref
+ }
+ if node.Tag != "" {
+ return node.Role + " <" + node.Tag + ">"
+ }
+ return node.Role
+}
diff --git a/internal/audit/a11y_test.go b/internal/audit/a11y_test.go
new file mode 100644
index 00000000..310ed7e9
--- /dev/null
+++ b/internal/audit/a11y_test.go
@@ -0,0 +1,153 @@
+package audit
+
+import (
+ "reflect"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/bridge/observe"
+)
+
+var cleanFacts = PageFacts{Title: "Page", Lang: "en", HeadingLevels: []int{1, 2}}
+
+func findingByRule(t *testing.T, report A11yReport, rule string) A11yFinding {
+ t.Helper()
+ for _, f := range report.Findings {
+ if f.Rule == rule {
+ return f
+ }
+ }
+ t.Fatalf("finding %q not present in %+v", rule, report.Findings)
+ return A11yFinding{}
+}
+
+func TestCleanTreeScoresPerfect(t *testing.T) {
+ nodes := []observe.A11yNode{
+ {Role: "image", Name: "logo"},
+ {Role: "textbox", Name: "Search"},
+ {Role: "link", Name: "Home"},
+ {Role: "button", Name: "Submit"},
+ }
+ report := EvaluateA11y(nodes, cleanFacts)
+ if report.Score != 100 {
+ t.Errorf("Score = %d, want 100", report.Score)
+ }
+ if len(report.Findings) != 0 {
+ t.Errorf("Findings = %+v, want none", report.Findings)
+ }
+ if report.Findings == nil {
+ t.Error("Findings should be an empty slice, not nil (JSON [])")
+ }
+}
+
+func TestMissingAltRule(t *testing.T) {
+ report := EvaluateA11y([]observe.A11yNode{{Role: "image", Ref: "e3"}}, cleanFacts)
+ f := findingByRule(t, report, "missing-alt")
+ if f.Severity != SeveritySerious || f.Count != 1 {
+ t.Errorf("missing-alt = %+v", f)
+ }
+ if report.Score != 90 {
+ t.Errorf("Score = %d, want 90 (100 - 10)", report.Score)
+ }
+ named := EvaluateA11y([]observe.A11yNode{{Role: "image", Name: "logo"}}, cleanFacts)
+ altOnly := EvaluateA11y([]observe.A11yNode{{Role: "img", Alt: "logo"}}, cleanFacts)
+ if len(named.Findings) != 0 || len(altOnly.Findings) != 0 {
+ t.Error("image with name or alt should not violate missing-alt")
+ }
+}
+
+func TestMissingLabelRule(t *testing.T) {
+ for _, role := range []string{"textbox", "searchbox", "combobox", "checkbox", "radio", "spinbutton", "slider", "switch"} {
+ report := EvaluateA11y([]observe.A11yNode{{Role: role}}, cleanFacts)
+ f := findingByRule(t, report, "missing-label")
+ if f.Severity != SeveritySerious || f.Count != 1 {
+ t.Errorf("%s: missing-label = %+v", role, f)
+ }
+ }
+ labeled := EvaluateA11y([]observe.A11yNode{{Role: "textbox", Label: "Search"}}, cleanFacts)
+ if len(labeled.Findings) != 0 {
+ t.Error("labeled textbox should not violate missing-label")
+ }
+}
+
+func TestEmptyLinkAndButtonRules(t *testing.T) {
+ report := EvaluateA11y([]observe.A11yNode{{Role: "link"}, {Role: "button"}}, cleanFacts)
+ if f := findingByRule(t, report, "empty-link"); f.Severity != SeverityModerate {
+ t.Errorf("empty-link = %+v", f)
+ }
+ if f := findingByRule(t, report, "empty-button"); f.Severity != SeverityModerate {
+ t.Errorf("empty-button = %+v", f)
+ }
+ if report.Score != 90 {
+ t.Errorf("Score = %d, want 90 (100 - 5 - 5)", report.Score)
+ }
+ withText := EvaluateA11y([]observe.A11yNode{{Role: "link", Text: "Home"}, {Role: "button", Name: "Go"}}, cleanFacts)
+ if len(withText.Findings) != 0 {
+ t.Error("link with text / named button should not violate")
+ }
+}
+
+func TestHiddenNodesSkipped(t *testing.T) {
+ report := EvaluateA11y([]observe.A11yNode{{Role: "image", Hidden: true}}, cleanFacts)
+ if len(report.Findings) != 0 {
+ t.Errorf("hidden node should be skipped, got %+v", report.Findings)
+ }
+}
+
+func TestPageFactRules(t *testing.T) {
+ report := EvaluateA11y(nil, PageFacts{HeadingLevels: []int{1, 3, 4, 6}})
+ if f := findingByRule(t, report, "missing-title"); f.Severity != SeverityModerate {
+ t.Errorf("missing-title = %+v", f)
+ }
+ if f := findingByRule(t, report, "missing-lang"); f.Severity != SeverityModerate {
+ t.Errorf("missing-lang = %+v", f)
+ }
+ skip := findingByRule(t, report, "heading-skip")
+ if skip.Severity != SeverityMinor || skip.Count != 2 {
+ t.Errorf("heading-skip = %+v, want count 2 (h1→h3, h4→h6)", skip)
+ }
+ if skip.Samples[0] != "h3 follows h1" {
+ t.Errorf("heading-skip sample = %q", skip.Samples[0])
+ }
+ if report.Score != 100-5-5-2*2 {
+ t.Errorf("Score = %d, want %d", report.Score, 100-5-5-2*2)
+ }
+}
+
+func TestScoreFlooredAtZero(t *testing.T) {
+ var nodes []observe.A11yNode
+ for range 20 {
+ nodes = append(nodes, observe.A11yNode{Role: "image"})
+ }
+ report := EvaluateA11y(nodes, cleanFacts)
+ if report.Score != 0 {
+ t.Errorf("Score = %d, want 0 (floored)", report.Score)
+ }
+ if f := findingByRule(t, report, "missing-alt"); f.Count != 20 || len(f.Samples) != maxA11ySamples {
+ t.Errorf("missing-alt count/samples = %d/%d, want 20/%d", f.Count, len(f.Samples), maxA11ySamples)
+ }
+}
+
+func TestDeterministicOrderingAndScore(t *testing.T) {
+ nodes := []observe.A11yNode{
+ {Role: "button"},
+ {Role: "image", Ref: "e1"},
+ {Role: "link"},
+ {Role: "textbox"},
+ }
+ first := EvaluateA11y(nodes, cleanFacts)
+ second := EvaluateA11y(nodes, cleanFacts)
+ if !reflect.DeepEqual(first, second) {
+ t.Errorf("repeated evaluation differs:\n%+v\n%+v", first, second)
+ }
+ var rules []string
+ for _, f := range first.Findings {
+ rules = append(rules, f.Rule)
+ }
+ want := []string{"empty-button", "empty-link", "missing-alt", "missing-label"}
+ if !reflect.DeepEqual(rules, want) {
+ t.Errorf("rules order = %v, want %v", rules, want)
+ }
+ if first.Score != 100-10-10-5-5 {
+ t.Errorf("Score = %d, want %d", first.Score, 100-10-10-5-5)
+ }
+}
diff --git a/internal/handlers/a11y_audit.go b/internal/handlers/a11y_audit.go
new file mode 100644
index 00000000..f5cb5902
--- /dev/null
+++ b/internal/handlers/a11y_audit.go
@@ -0,0 +1,53 @@
+package handlers
+
+import (
+ "fmt"
+ "net/http"
+
+ "github.com/pinchtab/pinchtab/internal/audit"
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/httpx"
+)
+
+// @Endpoint GET /a11y/audit
+func (h *Handlers) HandleA11yAudit(w http.ResponseWriter, r *http.Request) {
+ tabID := r.URL.Query().Get("tabId")
+
+ if !h.ensureBrowserOrRespond(w, h.Config) {
+ return
+ }
+ h.recordReadRequest(r, "a11y_audit", tabID)
+
+ resolvedTabID, tCtx, cancel, ok := h.resolveReadContext(w, r, tabID, h.Config.ActionTimeout)
+ if !ok {
+ return
+ }
+ defer h.armAutoCloseIfEnabled(resolvedTabID)
+ defer cancel()
+
+ h.waitForReadyState(tCtx)
+
+ rawNodes, err := bridge.FetchAXTree(tCtx)
+ if err != nil {
+ httpx.Error(w, 500, fmt.Errorf("fetch accessibility tree: %w", err))
+ return
+ }
+ nodes, _ := bridge.BuildSnapshot(rawNodes, "", -1)
+
+ var facts audit.PageFacts
+ if err := h.Bridge.Evaluate(tCtx, audit.PageFactsScript, &facts, bridge.EvalOpts{}); err != nil {
+ httpx.Error(w, 500, fmt.Errorf("collect page facts: %w", err))
+ return
+ }
+
+ report := audit.EvaluateA11y(nodes, facts)
+ httpx.JSON(w, 200, struct {
+ TabID string `json:"tabId"`
+ audit.A11yReport
+ }{resolvedTabID, report})
+}
+
+// @Endpoint GET /tabs/{id}/a11y/audit
+func (h *Handlers) HandleTabA11yAudit(w http.ResponseWriter, r *http.Request) {
+ h.withPathTabID(w, r, h.HandleA11yAudit)
+}
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index 779182ea..46be76d2 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -321,6 +321,7 @@ func (h *Handlers) bridgeBindings() []routeBinding {
{pattern: "DELETE /cookies", root: h.HandleClearCookies, tab: h.HandleTabClearCookies},
{pattern: "GET /metrics", root: h.HandleMetrics, tab: h.HandleTabMetrics},
{pattern: "GET /timing", root: h.HandleTiming, tab: h.HandleTabTiming},
+ {pattern: "GET /a11y/audit", root: h.HandleA11yAudit, tab: h.HandleTabA11yAudit},
{pattern: "GET /network", root: h.HandleNetwork, tab: h.HandleTabNetwork},
{pattern: "GET /network/stream", root: h.HandleNetworkStream, tab: h.HandleTabNetworkStream},
{pattern: "GET /network/export", root: h.HandleNetworkExport, tab: h.HandleTabNetworkExport},
diff --git a/internal/routes/routes.go b/internal/routes/routes.go
index dd6273c0..9f88bb33 100644
--- a/internal/routes/routes.go
+++ b/internal/routes/routes.go
@@ -123,6 +123,7 @@ var coreEndpoints = []Endpoint{
{"GET", "/metrics", "Runtime metrics", CapNone, true},
{"GET", "/timing", "Page timing and Core Web Vitals", CapNone, true},
+ {"GET", "/a11y/audit", "Accessibility findings and score", CapNone, true},
{"GET", "/network", "Network log", CapNone, true},
{"GET", "/network/stream", "Network SSE stream", CapNone, true},
diff --git a/tests/e2e/scenarios/api/a11y-audit-basic.sh b/tests/e2e/scenarios/api/a11y-audit-basic.sh
new file mode 100755
index 00000000..d099fa61
--- /dev/null
+++ b/tests/e2e/scenarios/api/a11y-audit-basic.sh
@@ -0,0 +1,65 @@
+#!/bin/bash
+# a11y-audit-basic.sh — GET /a11y/audit accessibility score and findings.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../../helpers/api.sh"
+
+# ─────────────────────────────────────────────────────────────────
+start_test "a11y-issues page scores below 100 with expected rules"
+
+pt_post /navigate -d "{\"url\":\"${FIXTURES_URL}/audit-site/a11y-issues.html\"}"
+assert_ok "navigate to a11y-issues.html"
+
+pt_get /a11y/audit
+assert_ok "get a11y audit"
+assert_json_exists "$RESULT" '.score' "has score"
+assert_json_exists "$RESULT" '.findings' "has findings"
+
+SCORE=$(echo "$RESULT" | jq '.score')
+if [ "$SCORE" -lt 100 ] 2>/dev/null; then
+ pass_assert "score < 100 (got: $SCORE)"
+else
+ fail_assert "score < 100 (got: $SCORE)"
+fi
+
+for rule in missing-alt missing-label empty-link; do
+ if echo "$RESULT" | jq -e --arg rule "$rule" '.findings[] | select(.rule == $rule)' >/dev/null 2>&1; then
+ pass_assert "findings include $rule"
+ else
+ fail_assert "findings include $rule (got: $(echo "$RESULT" | jq -c '[.findings[].rule]'))"
+ fi
+done
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "a11y audit is deterministic across consecutive calls"
+
+pt_get /a11y/audit
+assert_ok "first audit call"
+FIRST=$(echo "$RESULT" | jq -S '{score, findings}')
+
+pt_get /a11y/audit
+assert_ok "second audit call"
+SECOND=$(echo "$RESULT" | jq -S '{score, findings}')
+
+if [ "$FIRST" = "$SECOND" ]; then
+ pass_assert "consecutive audits identical"
+else
+ fail_assert "consecutive audits differ: $FIRST vs $SECOND"
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "clean page scores 100 with zero findings"
+
+pt_post /navigate -d "{\"url\":\"${FIXTURES_URL}/audit-site/clean.html\"}"
+assert_ok "navigate to clean.html"
+
+pt_get /a11y/audit
+assert_ok "get a11y audit"
+assert_json_eq "$RESULT" '.score' "100" "score is 100"
+assert_json_length "$RESULT" '.findings' 0 "zero findings"
+
+end_test