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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.goindex 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.shnew file mode 100755index 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