Skip to content

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

fix: audit never collects uncaught JS errors and its summary score is accessibility-only, so a broken page reports ok at 95 (PIN-122)

Luigi Agosti467f4eb55ed4
diff --git a/docs/audit.md b/docs/audit.md
index 16fa62bf..74deeab8 100644
--- a/docs/audit.md
+++ b/docs/audit.md
@@ -82,20 +82,27 @@ sitemap).
```
schemaVersion, generatedAt, input, options
-summaryScore # mean accessibility score of enriched pages
+summaryScore # mean accessibility score of enriched pages;
+ # broken assets, failed requests and uncaught
+ # JS errors do not move it
pages[]:
url, title, error? # error set when the page failed to load
seaportal? # HTTP-extraction summary when ingested
securityFindings[]? # ruleId, severity, detail, url
browser:
screenshotPath # relative path under the output dir
- consoleLogs[], networkRequests[], brokenAssets[]
+ consoleLogs[], jsErrors[], networkRequests[], brokenAssets[]
interactiveElements[], accessibilityScore
timingMetrics: ttfbMs, fcpMs, lcpMs, cls, domContentLoadedMs, loadMs
securityFindings[] # page findings aggregated site-level
recommendations[]
```
+`jsErrors[]` are uncaught JavaScript exceptions (message, stack, line,
+column) — the `GET /errors` channel, separate from `consoleLogs[]`, so a
+`console.error` call and a thrown exception never merge. A page that raised
+one is never reported `ok`.
+
`--format md` / `--format html` write `report.md` / `report.html` next to
`report.json` (or print to stdout without `--output-dir`). The HTML is
self-contained — inline CSS, relative screenshot links. `--format pdf` prints
diff --git a/internal/audit/enrich.go b/internal/audit/enrich.go
index 66da9775..bd1e6778 100644
--- a/internal/audit/enrich.go
+++ b/internal/audit/enrich.go
@@ -12,11 +12,13 @@ import (
type PageOptions struct {
Screenshot bool `json:"screenshot"`
Network bool `json:"network"`
- Console bool `json:"console"`
- A11y bool `json:"a11y"`
- Timing bool `json:"timing"`
- Elements bool `json:"elements"`
- Security bool `json:"security"`
+ // Console captures both page-message channels: console calls and
+ // uncaught JavaScript exceptions.
+ Console bool `json:"console"`
+ A11y bool `json:"a11y"`
+ Timing bool `json:"timing"`
+ Elements bool `json:"elements"`
+ Security bool `json:"security"`
}
// DefaultPageOptions enables every collector.
@@ -30,6 +32,7 @@ type Collectors struct {
Title func() (string, error)
Screenshot func() ([]byte, error)
Console func() ([]bridge.LogEntry, error)
+ JSErrors func() ([]bridge.ErrorEntry, error)
Network func() ([]observe.NetworkEntry, error)
Snapshot func() ([]observe.A11yNode, error)
PageFacts func() (PageFacts, error)
@@ -83,6 +86,14 @@ func EnrichPage(url string, opts PageOptions, c Collectors) PageAudit {
}
}
+ if opts.Console && c.JSErrors != nil {
+ if errors, err := c.JSErrors(); err != nil {
+ fail("jsErrors", err)
+ } else {
+ pa.JSErrors = MapJSErrors(errors)
+ }
+ }
+
if opts.Network && c.Network != nil {
if entries, err := c.Network(); err != nil {
fail("network", err)
@@ -159,6 +170,23 @@ func MapConsoleLogs(logs []bridge.LogEntry) []ConsoleLogEntry {
return out
}
+// MapJSErrors converts bridge uncaught-exception entries to the audit schema.
+func MapJSErrors(errors []bridge.ErrorEntry) []JSError {
+ out := make([]JSError, 0, len(errors))
+ for _, e := range errors {
+ out = append(out, JSError{
+ Timestamp: e.Timestamp,
+ Message: e.Message,
+ Type: e.Type,
+ URL: e.URL,
+ Line: e.Line,
+ Column: e.Column,
+ Stack: e.Stack,
+ })
+ }
+ return out
+}
+
// MapNetworkRequests converts observed network entries to the audit schema.
func MapNetworkRequests(entries []observe.NetworkEntry) []NetworkRequest {
out := make([]NetworkRequest, 0, len(entries))
diff --git a/internal/audit/enrich_test.go b/internal/audit/enrich_test.go
index 7fcc687c..b56796c2 100644
--- a/internal/audit/enrich_test.go
+++ b/internal/audit/enrich_test.go
@@ -20,6 +20,16 @@ func fullCollectors() Collectors {
Console: func() ([]bridge.LogEntry, error) {
return []bridge.LogEntry{{Timestamp: enrichTS, Level: "error", Message: "boom", Source: "app.js"}}, nil
},
+ JSErrors: func() ([]bridge.ErrorEntry, error) {
+ return []bridge.ErrorEntry{{
+ Timestamp: enrichTS,
+ Message: "Uncaught: ReferenceError: undefinedFn is not defined\n at http://fixtures/page.html:5:64",
+ URL: "http://fixtures/page.html",
+ Line: 4,
+ Column: 63,
+ Stack: "ReferenceError: undefinedFn is not defined\n at http://fixtures/page.html:5:64",
+ }}, nil
+ },
Network: func() ([]observe.NetworkEntry, error) {
return []observe.NetworkEntry{
{URL: "http://fixtures/page.html", Method: "GET", Status: 200, ResourceType: "Document", Finished: true},
@@ -54,6 +64,9 @@ func TestEnrichPageAllCollectors(t *testing.T) {
if len(pa.ConsoleLogs) != 1 || pa.ConsoleLogs[0].Level != "error" {
t.Errorf("ConsoleLogs = %+v", pa.ConsoleLogs)
}
+ if len(pa.JSErrors) != 1 || !strings.Contains(pa.JSErrors[0].Message, "ReferenceError") || pa.JSErrors[0].Stack == "" {
+ t.Errorf("JSErrors = %+v (want the uncaught exception with its stack)", pa.JSErrors)
+ }
if len(pa.NetworkRequests) != 2 {
t.Errorf("NetworkRequests = %+v", pa.NetworkRequests)
}
@@ -105,6 +118,52 @@ func TestEnrichPageOptionToggles(t *testing.T) {
}
}
+// A broken asset and an uncaught exception are the two failures a page can
+// carry while still navigating fine; both must reach the report and the page
+// must not read as healthy.
+func TestEnrichPageSurfacesBrokenAssetAndUncaughtError(t *testing.T) {
+ pr := EnrichPage("http://fixtures/page.html", DefaultPageOptions(), fullCollectors()).ToPageResult()
+ if len(pr.Browser.BrokenAssets) != 1 {
+ t.Errorf("BrokenAssets = %+v, want the 404 image", pr.Browser.BrokenAssets)
+ }
+ if len(pr.Browser.JSErrors) != 1 {
+ t.Fatalf("JSErrors = %+v, want the uncaught exception", pr.Browser.JSErrors)
+ }
+ if !strings.Contains(pr.Browser.JSErrors[0].Message, "undefinedFn") || pr.Browser.JSErrors[0].Stack == "" {
+ t.Errorf("JSError = %+v, want the message and stack", pr.Browser.JSErrors[0])
+ }
+ if got := PageStatus(pr); got == "ok" {
+ t.Errorf("PageStatus = %q, want a page raising an uncaught exception not to read as ok", got)
+ }
+}
+
+// The two channels stay separate all the way into the report: console.error
+// is not an uncaught exception and an uncaught exception is not console noise.
+func TestEnrichPageKeepsConsoleAndUncaughtErrorsDistinct(t *testing.T) {
+ pa := EnrichPage("http://fixtures/page.html", DefaultPageOptions(), fullCollectors())
+ if len(pa.ConsoleLogs) != 1 || pa.ConsoleLogs[0].Message != "boom" {
+ t.Errorf("ConsoleLogs = %+v, want only the console.error entry", pa.ConsoleLogs)
+ }
+ if len(pa.JSErrors) != 1 || strings.Contains(pa.JSErrors[0].Message, "boom") {
+ t.Errorf("JSErrors = %+v, want only the uncaught exception", pa.JSErrors)
+ }
+}
+
+func TestEnrichPageConsoleOptionGatesBothChannels(t *testing.T) {
+ opts := DefaultPageOptions()
+ opts.Console = false
+ pa := EnrichPage("http://fixtures/page.html", opts, fullCollectors())
+ if len(pa.ConsoleLogs) != 0 || len(pa.JSErrors) != 0 {
+ t.Errorf("ConsoleLogs = %+v, JSErrors = %+v, want both empty", pa.ConsoleLogs, pa.JSErrors)
+ }
+ data, _ := json.Marshal(pa)
+ var fields map[string]any
+ _ = json.Unmarshal(data, &fields)
+ if _, ok := fields["jsErrors"]; ok {
+ t.Error("jsErrors should be omitted when the console collector is disabled")
+ }
+}
+
func TestEnrichPageCollectorFailureIsData(t *testing.T) {
c := fullCollectors()
c.Timing = func() (*observe.TimingMetrics, error) { return nil, errors.New("timing exploded") }
diff --git a/internal/audit/report/html.go b/internal/audit/report/html.go
index 2221635b..6214fcc3 100644
--- a/internal/audit/report/html.go
+++ b/internal/audit/report/html.go
@@ -30,6 +30,8 @@ var htmlTemplate = template.Must(template.New("report").Funcs(template.FuncMap{
"formatCLS": formatCLS,
"sortedKeys": sortedKeys,
"pageErrors": pageConsoleErrors,
+ "pageStatus": audit.PageStatus,
+ "firstLine": firstLine,
// Screenshot sources are our own artifact paths or data: URIs built by
// BuildPDFHTML, so they are trusted; html/template would otherwise
// reject data: URLs.
@@ -46,10 +48,10 @@ var htmlTemplate = template.Must(template.New("report").Funcs(template.FuncMap{
<p>Schema version {{.R.SchemaVersion}} · generated {{.R.GeneratedAt.Format "2006-01-02 15:04:05 UTC"}} · {{len .R.Pages}} page(s)</p>
<h2>Summary</h2>
-<p class="score">Summary score: {{.R.SummaryScore}}/100</p>
+<p class="score">Mean accessibility score: {{.R.SummaryScore}}/100</p>
<table>
-<tr><th>Page</th><th>Score</th><th>Load</th><th>Broken assets</th><th>Console errors</th><th>Status</th></tr>
-{{range .R.Pages}}<tr><td>{{pageLabel .}}</td><td>{{.Browser.AccessibilityScore}}</td><td>{{formatMs .Browser.TimingMetrics.Load}}</td><td>{{len .Browser.BrokenAssets}}</td><td>{{pageErrors .}}</td><td>{{if .Error}}<span class="error">{{.Error}}</span>{{else}}ok{{end}}</td></tr>
+<tr><th>Page</th><th>Score</th><th>Load</th><th>Broken assets</th><th>Console errors</th><th>Uncaught JS errors</th><th>Status</th></tr>
+{{range .R.Pages}}<tr><td>{{pageLabel .}}</td><td>{{.Browser.AccessibilityScore}}</td><td>{{formatMs .Browser.TimingMetrics.Load}}</td><td>{{len .Browser.BrokenAssets}}</td><td>{{pageErrors .}}</td><td>{{len .Browser.JSErrors}}</td><td>{{if .Error}}<span class="error">{{.Error}}</span>{{else}}{{pageStatus .}}{{end}}</td></tr>
{{end}}</table>
{{if .HasSeaportal}}<h2>SEO &amp; Metadata</h2>
@@ -73,8 +75,9 @@ var htmlTemplate = template.Must(template.New("report").Funcs(template.FuncMap{
{{end}}</table>{{end}}
{{if .HasConsole}}<h2>Console &amp; JS Errors</h2>
-{{range .R.Pages}}{{$problems := consoleProblems .}}{{if $problems}}<h3>{{pageLabel .}}</h3><ul>
-{{range $problems}}<li><code>{{.Level}}</code> {{.Message}}</li>
+{{range .R.Pages}}{{$problems := consoleProblems .}}{{if or $problems .Browser.JSErrors}}<h3>{{pageLabel .}}</h3><ul>
+{{range .Browser.JSErrors}}<li><code>uncaught</code> {{firstLine .Message}}</li>
+{{end}}{{range $problems}}<li><code>{{.Level}}</code> {{.Message}}</li>
{{end}}</ul>{{end}}{{end}}{{end}}
{{if .HasBroken}}<h2>Broken Assets</h2>
@@ -130,7 +133,7 @@ func renderHTML(r audit.AuditReport) ([]byte, error) {
HasElements: hasElements(r),
HasVisualDiff: hasVisualDiff(r),
HasTiming: hasTiming(r),
- HasConsole: hasConsoleProblems(r),
+ HasConsole: hasConsoleProblems(r) || hasJSErrors(r),
HasBroken: hasBrokenAssets(r),
Usability: usabilityPages(r),
Recommendations: recommendations(r),
diff --git a/internal/audit/report/markdown.go b/internal/audit/report/markdown.go
index 7a0edf30..6cd6fbdd 100644
--- a/internal/audit/report/markdown.go
+++ b/internal/audit/report/markdown.go
@@ -20,18 +20,14 @@ func renderMarkdown(r audit.AuditReport) []byte {
w("## Summary")
w("")
- w("**Summary score: %d/100**", r.SummaryScore)
+ w("**Mean accessibility score: %d/100**", r.SummaryScore)
w("")
- w("| Page | Score | Load | Broken assets | Console errors | Status |")
- w("|---|---|---|---|---|---|")
+ w("| Page | Score | Load | Broken assets | Console errors | Uncaught JS errors | Status |")
+ w("|---|---|---|---|---|---|---|")
for _, p := range r.Pages {
- status := "ok"
- if p.Error != "" {
- status = "error: " + p.Error
- }
- w("| %s | %d | %s | %d | %d | %s |",
+ w("| %s | %d | %s | %d | %d | %d | %s |",
pageLabel(p), p.Browser.AccessibilityScore, formatMs(p.Browser.TimingMetrics.Load),
- len(p.Browser.BrokenAssets), pageConsoleErrors(p), status)
+ len(p.Browser.BrokenAssets), pageConsoleErrors(p), len(p.Browser.JSErrors), audit.PageStatus(p))
}
w("")
@@ -94,16 +90,19 @@ func renderMarkdown(r audit.AuditReport) []byte {
w("")
}
- if hasConsoleProblems(r) {
+ if hasConsoleProblems(r) || hasJSErrors(r) {
w("## Console & JS Errors")
w("")
for _, p := range r.Pages {
problems := consoleProblems(p)
- if len(problems) == 0 {
+ if len(problems) == 0 && len(p.Browser.JSErrors) == 0 {
continue
}
w("### %s", pageLabel(p))
w("")
+ for _, e := range p.Browser.JSErrors {
+ w("- `uncaught` %s", firstLine(e.Message))
+ }
for _, l := range problems {
w("- `%s` %s", l.Level, l.Message)
}
diff --git a/internal/audit/report/report.go b/internal/audit/report/report.go
index a80bd5e3..78887c8f 100644
--- a/internal/audit/report/report.go
+++ b/internal/audit/report/report.go
@@ -109,6 +109,24 @@ func hasConsoleProblems(r audit.AuditReport) bool {
return false
}
+func hasJSErrors(r audit.AuditReport) bool {
+ for _, p := range r.Pages {
+ if len(p.Browser.JSErrors) > 0 {
+ return true
+ }
+ }
+ return false
+}
+
+// firstLine trims an exception message down to its first line, so a stack trace
+// never breaks the list or table cell it is rendered into.
+func firstLine(s string) string {
+ if i := strings.IndexByte(s, '\n'); i >= 0 {
+ return strings.TrimSpace(s[:i])
+ }
+ return strings.TrimSpace(s)
+}
+
func hasBrokenAssets(r audit.AuditReport) bool {
for _, p := range r.Pages {
if len(p.Browser.BrokenAssets) > 0 {
@@ -137,6 +155,14 @@ func totalBrokenAssets(r audit.AuditReport) int {
return n
}
+func totalJSErrors(r audit.AuditReport) int {
+ n := 0
+ for _, p := range r.Pages {
+ n += len(p.Browser.JSErrors)
+ }
+ return n
+}
+
func totalConsoleErrors(r audit.AuditReport) int {
n := 0
for _, p := range r.Pages {
@@ -156,6 +182,9 @@ func recommendations(r audit.AuditReport) []string {
if n := totalBrokenAssets(r); n > 0 {
recs = append(recs, fmt.Sprintf("Fix %d broken asset reference(s) — see Broken Assets.", n))
}
+ if n := totalJSErrors(r); n > 0 {
+ recs = append(recs, fmt.Sprintf("Fix %d uncaught JS error(s) — each halts the script that raised it; see Console & JS Errors.", n))
+ }
if n := totalConsoleErrors(r); n > 0 {
recs = append(recs, fmt.Sprintf("Investigate %d console error(s) — see Console & JS Errors.", n))
}
diff --git a/internal/audit/report/report_test.go b/internal/audit/report/report_test.go
index 3de64403..ec65f873 100644
--- a/internal/audit/report/report_test.go
+++ b/internal/audit/report/report_test.go
@@ -43,6 +43,9 @@ func sampleReport() audit.AuditReport {
{Level: "warning", Message: "careful"},
{Level: "log", Message: "ignored in report"},
},
+ JSErrors: []audit.JSError{
+ {Message: "Uncaught: ReferenceError: undefinedFn is not defined\n at http://fixtures/audit-site/index.html:5:64", URL: "http://fixtures/audit-site/index.html", Line: 4, Column: 63},
+ },
BrokenAssets: []audit.BrokenAsset{
{URL: "http://fixtures/audit-site/assets/missing.png", ResourceType: "image", Status: 404},
{URL: "http://fixtures/api", ResourceType: "xhr", Error: "net::ERR_FAILED"},
diff --git a/internal/audit/report/testdata/report.golden.html b/internal/audit/report/testdata/report.golden.html
index e72167e4..f8d0eedb 100644
--- a/internal/audit/report/testdata/report.golden.html
+++ b/internal/audit/report/testdata/report.golden.html
@@ -21,11 +21,11 @@ code { background: #f2f4f8; padding: .1rem .3rem; border-radius: 3px; }
<p>Schema version 1.0 · generated 2026-07-04 12:00:00 UTC · 2 page(s)</p>
<h2>Summary</h2>
-<p class="score">Summary score: 85/100</p>
+<p class="score">Mean accessibility score: 85/100</p>
<table>
-<tr><th>Page</th><th>Score</th><th>Load</th><th>Broken assets</th><th>Console errors</th><th>Status</th></tr>
-<tr><td>Audit Fixture Site</td><td>70</td><td>200 ms</td><td>2</td><td>1</td><td>ok</td></tr>
-<tr><td>http://fixtures/audit-site/down.html</td><td>0</td><td>-</td><td>0</td><td>0</td><td><span class="error">navigation failed: net::ERR_CONNECTION_REFUSED</span></td></tr>
+<tr><th>Page</th><th>Score</th><th>Load</th><th>Broken assets</th><th>Console errors</th><th>Uncaught JS errors</th><th>Status</th></tr>
+<tr><td>Audit Fixture Site</td><td>70</td><td>200 ms</td><td>2</td><td>1</td><td>1</td><td>1 uncaught JS error(s)</td></tr>
+<tr><td>http://fixtures/audit-site/down.html</td><td>0</td><td>-</td><td>0</td><td>0</td><td>0</td><td><span class="error">navigation failed: net::ERR_CONNECTION_REFUSED</span></td></tr>
</table>
<h2>SEO &amp; Metadata</h2>
@@ -55,6 +55,7 @@ code { background: #f2f4f8; padding: .1rem .3rem; border-radius: 3px; }
<h2>Console &amp; JS Errors</h2>
<h3>Audit Fixture Site</h3><ul>
+<li><code>uncaught</code> Uncaught: ReferenceError: undefinedFn is not defined</li>
<li><code>error</code> boom</li>
<li><code>warning</code> careful</li>
</ul>
@@ -76,6 +77,7 @@ code { background: #f2f4f8; padding: .1rem .3rem; border-radius: 3px; }
<h2>Recommendations</h2><ol>
<li>Serve the site over https.</li>
<li>Fix 2 broken asset reference(s) — see Broken Assets.</li>
+<li>Fix 1 uncaught JS error(s) — each halts the script that raised it; see Console &amp; JS Errors.</li>
<li>Investigate 1 console error(s) — see Console &amp; JS Errors.</li>
<li>Improve accessibility on 1 page(s) scoring below 100 — see Usability Issues.</li>
<li>Address 1 security finding(s) — see Security Findings.</li>
diff --git a/internal/audit/report/testdata/report.golden.md b/internal/audit/report/testdata/report.golden.md
index 13488aab..15b6b956 100644
--- a/internal/audit/report/testdata/report.golden.md
+++ b/internal/audit/report/testdata/report.golden.md
@@ -6,12 +6,12 @@
## Summary
-**Summary score: 85/100**
+**Mean accessibility score: 85/100**
-| Page | Score | Load | Broken assets | Console errors | Status |
-|---|---|---|---|---|---|
-| Audit Fixture Site | 70 | 200 ms | 2 | 1 | ok |
-| http://fixtures/audit-site/down.html | 0 | - | 0 | 0 | error: navigation failed: net::ERR_CONNECTION_REFUSED |
+| Page | Score | Load | Broken assets | Console errors | Uncaught JS errors | Status |
+|---|---|---|---|---|---|---|
+| Audit Fixture Site | 70 | 200 ms | 2 | 1 | 1 | 1 uncaught JS error(s) |
+| http://fixtures/audit-site/down.html | 0 | - | 0 | 0 | 0 | error: navigation failed: net::ERR_CONNECTION_REFUSED |
## SEO & Metadata
@@ -44,6 +44,7 @@
### Audit Fixture Site
+- `uncaught` Uncaught: ReferenceError: undefinedFn is not defined
- `error` boom
- `warning` careful
@@ -66,8 +67,9 @@
1. Serve the site over https.
2. Fix 2 broken asset reference(s) — see Broken Assets.
-3. Investigate 1 console error(s) — see Console & JS Errors.
-4. Improve accessibility on 1 page(s) scoring below 100 — see Usability Issues.
-5. Address 1 security finding(s) — see Security Findings.
-6. Re-check 1 page(s) that failed to audit.
+3. Fix 1 uncaught JS error(s) — each halts the script that raised it; see Console & JS Errors.
+4. Investigate 1 console error(s) — see Console & JS Errors.
+5. Improve accessibility on 1 page(s) scoring below 100 — see Usability Issues.
+6. Address 1 security finding(s) — see Security Findings.
+7. Re-check 1 page(s) that failed to audit.
diff --git a/internal/audit/run.go b/internal/audit/run.go
index 57cb4926..6f9c0f85 100644
--- a/internal/audit/run.go
+++ b/internal/audit/run.go
@@ -213,8 +213,24 @@ func mergeSeaportal(pr PageResult, sp *SeaportalPage) PageResult {
return pr
}
-// summaryScore is the mean accessibility score across browser-enriched
-// pages that were audited without error, 0 when none were.
+// PageStatus is the one-line health verdict every report surface prints for
+// a page: the audit failure when it could not be collected, otherwise the
+// uncaught-exception count, otherwise ok. An uncaught exception halts the
+// script that raised it, so a page carrying one is never ok.
+func PageStatus(p PageResult) string {
+ switch {
+ case p.Error != "":
+ return "error: " + p.Error
+ case len(p.Browser.JSErrors) > 0:
+ return fmt.Sprintf("%d uncaught JS error(s)", len(p.Browser.JSErrors))
+ default:
+ return "ok"
+ }
+}
+
+// summaryScore is the mean accessibility score of enriched pages that were
+// audited without error, 0 when none were. It deliberately ignores broken
+// assets, failed requests and uncaught JS errors; see AuditReport.SummaryScore.
func summaryScore(plans []pagePlan, results []PageResult) int {
sum, n := 0, 0
for i, pr := range results {
diff --git a/internal/audit/run_test.go b/internal/audit/run_test.go
index af174170..88e0f9d0 100644
--- a/internal/audit/run_test.go
+++ b/internal/audit/run_test.go
@@ -197,3 +197,36 @@ func TestRunAuditErrorsAreData(t *testing.T) {
t.Errorf("SummaryScore = %d, want 80 (failed pages excluded)", report.SummaryScore)
}
}
+
+func TestPageStatus(t *testing.T) {
+ cases := []struct {
+ name string
+ page PageResult
+ want string
+ }{
+ {"clean", PageResult{}, "ok"},
+ {"failed", PageResult{Error: "connection refused"}, "error: connection refused"},
+ {
+ "uncaught exception",
+ PageResult{Browser: BrowserPageData{JSErrors: []JSError{{Message: "Uncaught: ReferenceError"}}}},
+ "1 uncaught JS error(s)",
+ },
+ {
+ "console error only",
+ PageResult{Browser: BrowserPageData{ConsoleLogs: []ConsoleLogEntry{{Level: "error", Message: "boom"}}}},
+ "ok",
+ },
+ {
+ "failure outranks the exception",
+ PageResult{Error: "timeout", Browser: BrowserPageData{JSErrors: []JSError{{Message: "Uncaught"}}}},
+ "error: timeout",
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ if got := PageStatus(tc.page); got != tc.want {
+ t.Errorf("PageStatus = %q, want %q", got, tc.want)
+ }
+ })
+ }
+}
diff --git a/internal/audit/types.go b/internal/audit/types.go
index 0d379bb2..d53d7fe5 100644
--- a/internal/audit/types.go
+++ b/internal/audit/types.go
@@ -24,6 +24,27 @@ type ConsoleLogEntry struct {
Source string `json:"source,omitempty"`
}
+// JSError is a single uncaught JavaScript exception raised while the page
+// loaded. It mirrors the bridge error-log shape served by GET /errors, the
+// channel that is separate from console messages: a console.error call lands
+// in ConsoleLogEntry, a thrown exception lands here.
+type JSError struct {
+ // Timestamp is when the exception was raised.
+ Timestamp time.Time `json:"timestamp"`
+ // Message is the exception text, including the exception description.
+ Message string `json:"message"`
+ // Type classifies the exception when the browser reported one.
+ Type string `json:"type,omitempty"`
+ // URL is the script URL the exception was raised from.
+ URL string `json:"url,omitempty"`
+ // Line is the 0-based line number within that script.
+ Line int64 `json:"line,omitempty"`
+ // Column is the 0-based column number within that script.
+ Column int64 `json:"column,omitempty"`
+ // Stack is the exception stack trace, when available.
+ Stack string `json:"stack,omitempty"`
+}
+
// NetworkRequest is a single resource request observed while loading a page.
// It mirrors the observe network entry shape, trimmed to audit-relevant fields.
type NetworkRequest struct {
@@ -137,6 +158,8 @@ type BrowserPageData struct {
FullPageScreenshot bool `json:"fullPageScreenshot,omitempty"`
// ConsoleLogs are the console messages captured during load.
ConsoleLogs []ConsoleLogEntry `json:"consoleLogs,omitempty"`
+ // JSErrors are the uncaught JavaScript exceptions raised during load.
+ JSErrors []JSError `json:"jsErrors,omitempty"`
// NetworkRequests are the resource requests observed during load.
NetworkRequests []NetworkRequest `json:"networkRequests,omitempty"`
// BrokenAssets are resources that failed to load, especially 404 images.
@@ -217,7 +240,9 @@ type AuditReport struct {
Options AuditOptions `json:"options"`
// Pages are the per-page audit results.
Pages []PageResult `json:"pages"`
- // SummaryScore is the overall site score, in [0,100].
+ // SummaryScore is the mean accessibility score of enriched pages, in
+ // [0,100]. It is not an overall health score: broken assets, failed
+ // requests and uncaught JS errors do not move it.
SummaryScore int `json:"summaryScore"`
// SecurityFindings are site-wide security-surface findings.
SecurityFindings []SecurityFinding `json:"securityFindings,omitempty"`
diff --git a/internal/audit/types_test.go b/internal/audit/types_test.go
index 8a701148..9f7157ac 100644
--- a/internal/audit/types_test.go
+++ b/internal/audit/types_test.go
@@ -215,6 +215,7 @@ type mirrorPair struct {
var mirrorPairsWithTypes = []mirrorPair{
{"InteractiveElement", "InteractiveElement", InteractiveElement{}, pinchtabaudit.InteractiveElement{}},
{"ConsoleLogEntry", "ConsoleLogEntry", ConsoleLogEntry{}, pinchtabaudit.ConsoleLogEntry{}},
+ {"JSError", "JSError", JSError{}, pinchtabaudit.JSError{}},
{"NetworkRequest", "NetworkRequest", NetworkRequest{}, pinchtabaudit.NetworkRequest{}},
{"BrokenAsset", "BrokenAsset", BrokenAsset{}, pinchtabaudit.BrokenAsset{}},
{"SecurityFinding", "SecurityFinding", SecurityFinding{}, pinchtabaudit.SecurityFinding{}},
diff --git a/internal/cli/actions/actions_audit.go b/internal/cli/actions/actions_audit.go
index 695c348f..739eebb6 100644
--- a/internal/cli/actions/actions_audit.go
+++ b/internal/cli/actions/actions_audit.go
@@ -494,34 +494,28 @@ func writeAuditArtifacts(dir string, report map[string]any) error {
}
func printAuditSummary(report map[string]any) {
- pages, _ := report["pages"].([]any)
- failed := 0
- broken := 0
- for _, p := range pages {
- page, ok := p.(map[string]any)
- if !ok {
- continue
- }
- if e, _ := page["error"].(string); e != "" {
+ for _, line := range auditSummaryLines(typedAuditReport(report)) {
+ fmt.Println(line)
+ }
+}
+
+// auditSummaryLines renders the human summary of an audit run: the headline
+// counts followed by one status line per page. The headline names the score
+// for what it measures, since it cannot move for the failures printed beside it.
+func auditSummaryLines(report audit.AuditReport) []string {
+ failed, broken, jsErrors := 0, 0, 0
+ for _, p := range report.Pages {
+ if p.Error != "" {
failed++
}
- if browser, ok := page["browser"].(map[string]any); ok {
- if assets, ok := browser["brokenAssets"].([]any); ok {
- broken += len(assets)
- }
- }
+ broken += len(p.Browser.BrokenAssets)
+ jsErrors += len(p.Browser.JSErrors)
}
- fmt.Printf("Audited %d page(s) · summary score %v · %d broken asset(s) · %d failed page(s)\n",
- len(pages), report["summaryScore"], broken, failed)
- for _, p := range pages {
- page, ok := p.(map[string]any)
- if !ok {
- continue
- }
- status := "ok"
- if e, _ := page["error"].(string); e != "" {
- status = "error: " + e
- }
- fmt.Printf(" %s · %s\n", page["url"], status)
+ lines := []string{fmt.Sprintf(
+ "Audited %d page(s) · mean accessibility score %d · %d broken asset(s) · %d uncaught JS error(s) · %d failed page(s)",
+ len(report.Pages), report.SummaryScore, broken, jsErrors, failed)}
+ for _, p := range report.Pages {
+ lines = append(lines, fmt.Sprintf(" %s · %s", p.URL, audit.PageStatus(p)))
}
+ return lines
}
diff --git a/internal/cli/actions/actions_audit_test.go b/internal/cli/actions/actions_audit_test.go
index 4ed4b496..823d6d45 100644
--- a/internal/cli/actions/actions_audit_test.go
+++ b/internal/cli/actions/actions_audit_test.go
@@ -279,3 +279,39 @@ func TestAuditSeaportalReportInjectsCookiesWithoutPositionalURL(t *testing.T) {
t.Fatalf("cookie URLs = %v, want %v", cookieURLs, want)
}
}
+
+func TestAuditSummaryLines(t *testing.T) {
+ report := audit.NewAuditReport()
+ report.SummaryScore = 95
+ report.Pages = []audit.PageResult{
+ {
+ URL: "http://fixtures/audit.html",
+ Browser: audit.BrowserPageData{
+ BrokenAssets: []audit.BrokenAsset{{URL: "/missing-image.png", Status: 404}, {URL: "/missing-script.js", Status: 404}},
+ ConsoleLogs: []audit.ConsoleLogEntry{{Level: "error", Message: "boom"}},
+ JSErrors: []audit.JSError{{Message: "Uncaught: ReferenceError: undefinedFn is not defined"}},
+ },
+ },
+ {URL: "http://fixtures/clean.html"},
+ {URL: "http://fixtures/down.html", Error: "connection refused"},
+ }
+
+ lines := auditSummaryLines(report)
+ want := []string{
+ "Audited 3 page(s) · mean accessibility score 95 · 2 broken asset(s) · 1 uncaught JS error(s) · 1 failed page(s)",
+ " http://fixtures/audit.html · 1 uncaught JS error(s)",
+ " http://fixtures/clean.html · ok",
+ " http://fixtures/down.html · error: connection refused",
+ }
+ if len(lines) != len(want) {
+ t.Fatalf("auditSummaryLines = %q", lines)
+ }
+ for i := range want {
+ if lines[i] != want[i] {
+ t.Errorf("line %d = %q, want %q", i, lines[i], want[i])
+ }
+ }
+ if strings.Contains(lines[0], "summary score") {
+ t.Errorf("headline still calls the accessibility mean a summary score: %q", lines[0])
+ }
+}
diff --git a/internal/handlers/audit_page.go b/internal/handlers/audit_page.go
index 8984c062..5c75156a 100644
--- a/internal/handlers/audit_page.go
+++ b/internal/handlers/audit_page.go
@@ -195,6 +195,9 @@ func (h *Handlers) auditCollectors(tCtx context.Context, tabID string) audit.Col
Console: func() ([]bridge.LogEntry, error) {
return h.Bridge.GetConsoleLogs(tabID, 0), nil
},
+ JSErrors: func() ([]bridge.ErrorEntry, error) {
+ return h.Bridge.GetErrorLogs(tabID, 0), nil
+ },
Network: func() ([]observe.NetworkEntry, error) {
nm := h.Bridge.NetworkMonitor()
if nm == nil {
diff --git a/pkg/pinchtabaudit/example_test.go b/pkg/pinchtabaudit/example_test.go
index 4afca2ea..d470aa1d 100644
--- a/pkg/pinchtabaudit/example_test.go
+++ b/pkg/pinchtabaudit/example_test.go
@@ -37,5 +37,5 @@ func ExampleClient_EnrichWithBrowser() {
log.Fatal(err)
}
- fmt.Printf("audited %d pages, summary score %d/100\n", len(report.Pages), report.SummaryScore)
+ fmt.Printf("audited %d pages, mean accessibility score %d/100\n", len(report.Pages), report.SummaryScore)
}
diff --git a/pkg/pinchtabaudit/types.go b/pkg/pinchtabaudit/types.go
index 69f2d81c..6b752255 100644
--- a/pkg/pinchtabaudit/types.go
+++ b/pkg/pinchtabaudit/types.go
@@ -14,6 +14,19 @@ type ConsoleLogEntry struct {
Source string `json:"source,omitempty"`
}
+// JSError is an uncaught JavaScript exception raised while the page loaded.
+// It is a separate channel from ConsoleLogEntry: a console.error call lands
+// there, a thrown exception lands here.
+type JSError struct {
+ Timestamp time.Time `json:"timestamp"`
+ Message string `json:"message"`
+ Type string `json:"type,omitempty"`
+ URL string `json:"url,omitempty"`
+ Line int64 `json:"line,omitempty"`
+ Column int64 `json:"column,omitempty"`
+ Stack string `json:"stack,omitempty"`
+}
+
// NetworkRequest is a resource request observed while loading a page.
type NetworkRequest struct {
URL string `json:"url"`
@@ -88,6 +101,7 @@ type BrowserPageData struct {
ScreenshotPath string `json:"screenshotPath,omitempty"`
FullPageScreenshot bool `json:"fullPageScreenshot,omitempty"`
ConsoleLogs []ConsoleLogEntry `json:"consoleLogs,omitempty"`
+ JSErrors []JSError `json:"jsErrors,omitempty"`
NetworkRequests []NetworkRequest `json:"networkRequests,omitempty"`
BrokenAssets []BrokenAsset `json:"brokenAssets,omitempty"`
InteractiveElements []InteractiveElement `json:"interactiveElements,omitempty"`
@@ -167,11 +181,14 @@ type AuditOptions struct {
// omitempty is a no-op on a non-pointer struct field anyway, so keeping it would
// only make the two sides of the mirror read as if they disagreed.
type AuditReport struct {
- SchemaVersion string `json:"schemaVersion"`
- GeneratedAt time.Time `json:"generatedAt"`
- Input AuditReportInput `json:"input"`
- Options AuditOptions `json:"options"`
- Pages []PageResult `json:"pages"`
+ SchemaVersion string `json:"schemaVersion"`
+ GeneratedAt time.Time `json:"generatedAt"`
+ Input AuditReportInput `json:"input"`
+ Options AuditOptions `json:"options"`
+ Pages []PageResult `json:"pages"`
+ // SummaryScore is the mean accessibility score of enriched pages, in
+ // [0,100]; broken assets, failed requests and uncaught JS errors do not
+ // move it.
SummaryScore int `json:"summaryScore"`
SecurityFindings []SecurityFinding `json:"securityFindings,omitempty"`
Recommendations []string `json:"recommendations,omitempty"`
diff --git a/tests/e2e/fixtures/audit-site/golden-report.json b/tests/e2e/fixtures/audit-site/golden-report.json
index dd0985b0..29358d3a 100644
--- a/tests/e2e/fixtures/audit-site/golden-report.json
+++ b/tests/e2e/fixtures/audit-site/golden-report.json
@@ -61,6 +61,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -109,6 +110,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -171,6 +173,7 @@
"role": "link"
}
],
+ "jsErrors": 1,
"networkRequests": [
{
"method": "GET",
@@ -205,6 +208,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -244,6 +248,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -281,6 +286,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -319,6 +325,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -344,6 +351,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -369,6 +377,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -394,6 +403,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -419,6 +429,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
@@ -444,6 +455,7 @@
"role": "link"
}
],
+ "jsErrors": 0,
"networkRequests": [
{
"method": "GET",
diff --git a/tests/e2e/fixtures/audit-site/normalize-report.jq b/tests/e2e/fixtures/audit-site/normalize-report.jq
index 58fd1181..a5538800 100644
--- a/tests/e2e/fixtures/audit-site/normalize-report.jq
+++ b/tests/e2e/fixtures/audit-site/normalize-report.jq
@@ -9,6 +9,10 @@
# Console messages are trimmed of trailing whitespace and interactive-element
# refs are dropped: both vary by capture path / accessibility tree across
# browser providers (chrome vs cloak) while the content itself is stable.
+# Uncaught JS errors collapse to their COUNT: their message text is assembled
+# differently by the two capture paths (Runtime.exceptionThrown prefixes the
+# exception description, the Console-domain fallback does not) and carries the
+# script URL, so only the count is comparable across providers.
#
# Regenerate the golden report (from a runner shell against the e2e stack):
# curl -s -H "Authorization: Bearer $E2E_SERVER_TOKEN" -X POST "$E2E_SERVER/audit" \
@@ -22,6 +26,7 @@
| .browser.screenshotPath = ""
| .browser.timingMetrics = {}
| .browser.consoleLogs = ((.browser.consoleLogs // []) | map({level: .level, message: (.message | sub("\\s+$"; ""))}))
+ | .browser.jsErrors = ((.browser.jsErrors // []) | length)
| .browser.interactiveElements = ((.browser.interactiveElements // []) | map(del(.ref)))
| .browser.networkRequests = ((.browser.networkRequests // [])
| map({url: .url, method: .method, status: .status, resourceType: .resourceType})